README
¶
Log SDK
Documentation
¶
Overview ¶
Package log provides the OpenTelemetry Logs SDK.
Index ¶
- type BatchProcessor
- type BatchProcessorOption
- type Exporter
- type LoggerProvider
- type LoggerProviderOption
- type Processor
- type Record
- func (r *Record) AddAttributes(attrs ...log.KeyValue)
- func (r *Record) AttributesLen() int
- func (r *Record) Body() log.Value
- func (r *Record) Clone() Record
- func (r *Record) DroppedAttributes() int
- func (r *Record) InstrumentationScope() instrumentation.Scope
- func (r *Record) ObservedTimestamp() time.Time
- func (r *Record) Resource() resource.Resource
- func (r *Record) SetAttributes(attrs ...log.KeyValue)
- func (r *Record) SetBody(v log.Value)
- func (r *Record) SetObservedTimestamp(t time.Time)
- func (r *Record) SetSeverity(level log.Severity)
- func (r *Record) SetSeverityText(text string)
- func (r *Record) SetSpanID(id trace.SpanID)
- func (r *Record) SetTimestamp(t time.Time)
- func (r *Record) SetTraceFlags(flags trace.TraceFlags)
- func (r *Record) SetTraceID(id trace.TraceID)
- func (r *Record) Severity() log.Severity
- func (r *Record) SeverityText() string
- func (r *Record) SpanID() trace.SpanID
- func (r *Record) Timestamp() time.Time
- func (r *Record) TraceFlags() trace.TraceFlags
- func (r *Record) TraceID() trace.TraceID
- func (r *Record) WalkAttributes(f func(log.KeyValue) bool)
- type SimpleProcessor
- type SimpleProcessorOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BatchProcessor ¶
type BatchProcessor struct {
// contains filtered or unexported fields
}
BatchProcessor is a processor that exports batches of log records.
Use NewBatchProcessor to create a BatchProcessor. An empty BatchProcessor is shut down by default, no records will be batched or exported.
func NewBatchProcessor ¶
func NewBatchProcessor(exporter Exporter, opts ...BatchProcessorOption) *BatchProcessor
NewBatchProcessor decorates the provided exporter so that the log records are batched before exporting.
All of the exporter's methods are called synchronously.
func (*BatchProcessor) Enabled ¶
func (b *BatchProcessor) Enabled(context.Context, Record) bool
Enabled returns if b is enabled.
func (*BatchProcessor) ForceFlush ¶
func (b *BatchProcessor) ForceFlush(ctx context.Context) error
ForceFlush flushes queued log records and flushes the decorated exporter.
type BatchProcessorOption ¶
type BatchProcessorOption interface {
// contains filtered or unexported methods
}
BatchProcessorOption applies a configuration to a BatchProcessor.
func WithExportInterval ¶
func WithExportInterval(d time.Duration) BatchProcessorOption
WithExportInterval sets the maximum duration between batched exports.
If the OTEL_BLRP_SCHEDULE_DELAY environment variable is set, and this option is not passed, that variable value will be used.
By default, if an environment variable is not set, and this option is not passed, 1s will be used. The default value is also used when the provided value is less than one.
func WithExportMaxBatchSize ¶
func WithExportMaxBatchSize(size int) BatchProcessorOption
WithExportMaxBatchSize sets the maximum batch size of every export. A batch will be split into multiple exports to not exceed this size.
If the OTEL_BLRP_MAX_EXPORT_BATCH_SIZE environment variable is set, and this option is not passed, that variable value will be used.
By default, if an environment variable is not set, and this option is not passed, 512 will be used. The default value is also used when the provided value is less than one.
func WithExportTimeout ¶
func WithExportTimeout(d time.Duration) BatchProcessorOption
WithExportTimeout sets the duration after which a batched export is canceled.
If the OTEL_BLRP_EXPORT_TIMEOUT environment variable is set, and this option is not passed, that variable value will be used.
By default, if an environment variable is not set, and this option is not passed, 30s will be used. The default value is also used when the provided value is less than one.
func WithMaxQueueSize ¶
func WithMaxQueueSize(size int) BatchProcessorOption
WithMaxQueueSize sets the maximum queue size used by the Batcher. After the size is reached log records are dropped.
If the OTEL_BLRP_MAX_QUEUE_SIZE environment variable is set, and this option is not passed, that variable value will be used.
By default, if an environment variable is not set, and this option is not passed, 2048 will be used. The default value is also used when the provided value is less than one.
type Exporter ¶
type Exporter interface {
// Export transmits log records to a receiver.
//
// The deadline or cancellation of the passed context must be honored. An
// appropriate error should be returned in these situations.
//
// All retry logic must be contained in this function. The SDK does not
// implement any retry logic. All errors returned by this function are
// considered unrecoverable and will be reported to a configured error
// Handler.
//
// Implementations must not retain the records slice.
//
// Before modifying a Record, the implementation must use Record.Clone
// to create a copy that shares no state with the original.
Export(ctx context.Context, records []Record) error
// Shutdown is called when the SDK shuts down. Any cleanup or release of
// resources held by the exporter should be done in this call.
//
// The deadline or cancellation of the passed context must be honored. An
// appropriate error should be returned in these situations.
//
// After Shutdown is called, calls to Export, Shutdown, or ForceFlush
// should perform no operation and return nil error.
Shutdown(ctx context.Context) error
// ForceFlush exports log records to the configured Exporter that have not yet
// been exported.
//
// The deadline or cancellation of the passed context must be honored. An
// appropriate error should be returned in these situations.
ForceFlush(ctx context.Context) error
}
Exporter handles the delivery of log records to external receivers.
Any of the Exporter's methods may be called concurrently with itself or with other methods. It is the responsibility of the Exporter to manage this concurrency.
type LoggerProvider ¶
type LoggerProvider struct {
embedded.LoggerProvider
// contains filtered or unexported fields
}
LoggerProvider handles the creation and coordination of Loggers. All Loggers created by a LoggerProvider will be associated with the same Resource.
func NewLoggerProvider ¶
func NewLoggerProvider(opts ...LoggerProviderOption) *LoggerProvider
NewLoggerProvider returns a new and configured LoggerProvider.
By default, the returned LoggerProvider is configured with the default Resource and no Processors. Processors cannot be added after a LoggerProvider is created. This means the returned LoggerProvider, one created with no Processors, will perform no operations.
func (*LoggerProvider) ForceFlush ¶
func (p *LoggerProvider) ForceFlush(ctx context.Context) error
ForceFlush flushes all processors.
This method can be called concurrently.
func (*LoggerProvider) Logger ¶
func (p *LoggerProvider) Logger(name string, opts ...log.LoggerOption) log.Logger
Logger returns a new log.Logger with the provided name and configuration.
If p is shut down, a noop.Logger instace is returned.
This method can be called concurrently.
type LoggerProviderOption ¶
type LoggerProviderOption interface {
// contains filtered or unexported methods
}
LoggerProviderOption applies a configuration option value to a LoggerProvider.
func WithAttributeCountLimit ¶
func WithAttributeCountLimit(limit int) LoggerProviderOption
WithAttributeCountLimit sets the maximum allowed log record attribute count. Any attribute added to a log record once this limit is reached will be dropped.
Setting this to zero means no attributes will be recorded.
Setting this to a negative value means no limit is applied.
If the OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT environment variable is set, and this option is not passed, that variable value will be used.
By default, if an environment variable is not set, and this option is not passed, 128 will be used.
func WithAttributeValueLengthLimit ¶
func WithAttributeValueLengthLimit(limit int) LoggerProviderOption
AttributeValueLengthLimit sets the maximum allowed attribute value length.
This limit only applies to string and string slice attribute values. Any string longer than this value will be truncated to this length.
Setting this to a negative value means no limit is applied.
If the OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT environment variable is set, and this option is not passed, that variable value will be used.
By default, if an environment variable is not set, and this option is not passed, no limit (-1) will be used.
func WithProcessor ¶
func WithProcessor(processor Processor) LoggerProviderOption
WithProcessor associates Processor with a LoggerProvider.
By default, if this option is not used, the LoggerProvider will perform no operations; no data will be exported without a processor.
Each WithProcessor creates a separate pipeline. Use custom decorators for advanced scenarios such as enriching with attributes.
For production, use NewBatchProcessor to batch log records before they are exported. For testing and debugging, use NewSimpleProcessor to synchronously export log records.
func WithResource ¶
func WithResource(res *resource.Resource) LoggerProviderOption
WithResource associates a Resource with a LoggerProvider. This Resource represents the entity producing telemetry and is associated with all Loggers the LoggerProvider will create.
By default, if this Option is not used, the default Resource from the go.opentelemetry.io/otel/sdk/resource package will be used.
type Processor ¶
type Processor interface {
// OnEmit is called when a Record is emitted.
//
// OnEmit will be called independent of Enabled. Implementations need to
// validate the arguments themselves before processing.
//
// Implementation should not interrupt the record processing
// if the context is canceled.
//
// All retry logic must be contained in this function. The SDK does not
// implement any retry logic. All errors returned by this function are
// considered unrecoverable and will be reported to a configured error
// Handler.
//
// Before modifying a Record, the implementation must use Record.Clone
// to create a copy that shares no state with the original.
OnEmit(ctx context.Context, record Record) error
// Enabled returns whether the Processor will process for the given context
// and record.
//
// The passed record is likely to be a partial record with only the
// bridge-relevant information being provided (e.g a record with only the
// Severity set). If a Logger needs more information than is provided, it
// is said to be in an indeterminate state (see below).
//
// The returned value will be true when the Processor will process for the
// provided context and record, and will be false if the Processor will not
// process. The returned value may be true or false in an indeterminate
// state. An implementation should default to returning true for an
// indeterminate state, but may return false if valid reasons in particular
// circumstances exist (e.g. performance, correctness).
//
// Before modifying a Record, the implementation must use Record.Clone
// to create a copy that shares no state with the original.
Enabled(ctx context.Context, record Record) bool
// Shutdown is called when the SDK shuts down. Any cleanup or release of
// resources held by the exporter should be done in this call.
//
// The deadline or cancellation of the passed context must be honored. An
// appropriate error should be returned in these situations.
//
// After Shutdown is called, calls to Export, Shutdown, or ForceFlush
// should perform no operation and return nil error.
Shutdown(ctx context.Context) error
// ForceFlush exports log records to the configured Exporter that have not yet
// been exported.
//
// The deadline or cancellation of the passed context must be honored. An
// appropriate error should be returned in these situations.
ForceFlush(ctx context.Context) error
}
Processor handles the processing of log records.
Any of the Processor's methods may be called concurrently with itself or with other methods. It is the responsibility of the Processor to manage this concurrency.
type Record ¶
type Record struct {
// contains filtered or unexported fields
}
Record is a log record emitted by the Logger.
func (*Record) AddAttributes ¶
AddAttributes adds attributes to the log record.
func (*Record) AttributesLen ¶
AttributesLen returns the number of attributes in the log record.
func (*Record) Clone ¶
Clone returns a copy of the record with no shared state. The original record and the clone can both be modified without interfering with each other.
func (*Record) DroppedAttributes ¶
DroppedAttributes returns the number of attributes dropped due to limits being reached.
func (*Record) InstrumentationScope ¶
func (r *Record) InstrumentationScope() instrumentation.Scope
InstrumentationScope returns the scope that the Logger was created with.
func (*Record) ObservedTimestamp ¶
ObservedTimestamp returns the time when the log record was observed.
func (*Record) SetAttributes ¶
SetAttributes sets (and overrides) attributes to the log record.
func (*Record) SetObservedTimestamp ¶
SetObservedTimestamp sets the time when the log record was observed.
func (*Record) SetSeverity ¶
SetSeverity sets the severity level of the log record.
func (*Record) SetSeverityText ¶
SetSeverityText sets severity (also known as log level) text. This is the original string representation of the severity as it is known at the source.
func (*Record) SetTimestamp ¶
SetTimestamp sets the time when the log record occurred.
func (*Record) SetTraceFlags ¶
func (r *Record) SetTraceFlags(flags trace.TraceFlags)
SetTraceFlags sets the trace flags.
func (*Record) SetTraceID ¶
SetTraceID sets the trace ID.
func (*Record) SeverityText ¶
SeverityText returns severity (also known as log level) text. This is the original string representation of the severity as it is known at the source.
func (*Record) TraceFlags ¶
func (r *Record) TraceFlags() trace.TraceFlags
TraceFlags returns the trace flags.
func (*Record) WalkAttributes ¶
WalkAttributes walks all attributes the log record holds by calling f for each on each log.KeyValue in the Record. Iteration stops if f returns false.
type SimpleProcessor ¶
type SimpleProcessor struct {
// contains filtered or unexported fields
}
SimpleProcessor is an processor that synchronously exports log records.
func NewSimpleProcessor ¶
func NewSimpleProcessor(exporter Exporter, _ ...SimpleProcessorOption) *SimpleProcessor
NewSimpleProcessor is a simple Processor adapter.
This Processor is not recommended for production use. The synchronous nature of this Processor make it good for testing, debugging, or showing examples of other features, but it can be slow and have a high computation resource usage overhead. NewBatchProcessor is recommended for production use instead.
func (*SimpleProcessor) Enabled ¶
func (s *SimpleProcessor) Enabled(context.Context, Record) bool
Enabled returns true.
func (*SimpleProcessor) ForceFlush ¶
func (s *SimpleProcessor) ForceFlush(ctx context.Context) error
ForceFlush flushes the exporter.
type SimpleProcessorOption ¶
type SimpleProcessorOption interface {
// contains filtered or unexported methods
}
SimpleProcessorOption applies a configuration to a SimpleProcessor.
Source Files