README
¶
Log API
Documentation
¶
Overview ¶
Package log provides the OpenTelemetry Logs Bridge API.
This package is intended to be a bridge between existing logging libraries and OpenTelemetry. It is not designed to be a logging API itself.
API Implementations ¶
This package does not conform to the standard Go versioning policy, all of its interfaces may have methods added to them without a package major version bump. This non-standard API evolution could surprise an uninformed implementation author. They could unknowingly build their implementation in a way that would result in a runtime panic for their users that update to the new API.
The API is designed to help inform an instrumentation author about this non-standard API evolution. It requires them to choose a default behavior for unimplemented interface methods. There are three behavior choices they can make:
- Compilation failure
- Panic
- Default to another implementation
All interfaces in this API embed a corresponding interface from go.opentelemetry.io/otel/log/embedded. If an author wants the default behavior of their implementations to be a compilation failure, signaling to their users they need to update to the latest version of that implementation, they need to embed the corresponding interface from go.opentelemetry.io/otel/log/embedded in their implementation. For example,
import "go.opentelemetry.io/otel/log/embedded"
type LoggerProvider struct {
embedded.LoggerProvider
// ...
}
If an author wants the default behavior of their implementations to a panic, they need to embed the API interface directly.
import "go.opentelemetry.io/otel/log"
type LoggerProvider struct {
log.LoggerProvider
// ...
}
This is not a recommended behavior as it could lead to publishing packages that contain runtime panics when users update other package that use newer versions of go.opentelemetry.io/otel/log.
Finally, an author can embed another implementation in theirs. The embedded implementation will be used for methods not defined by the author. For example, an author who wants to default to silently dropping the call can use go.opentelemetry.io/otel/log/noop:
import "go.opentelemetry.io/otel/log/noop"
type LoggerProvider struct {
noop.LoggerProvider
// ...
}
It is strongly recommended that authors only embed go.opentelemetry.io/otel/log/noop if they choose this default behavior. That implementation is the only one OpenTelemetry authors can guarantee will fully implement all the API interfaces when a user updates their API.
Index ¶
- type KeyValue
- func Bool(key string, value bool) KeyValue
- func Bytes(key string, value []byte) KeyValue
- func Empty(key string) KeyValue
- func Float64(key string, value float64) KeyValue
- func Int(key string, value int) KeyValue
- func Int64(key string, value int64) KeyValue
- func Map(key string, value ...KeyValue) KeyValue
- func Slice(key string, value ...Value) KeyValue
- func String(key, value string) KeyValue
- type Kind
- type Logger
- type LoggerConfig
- type LoggerOption
- type LoggerProvider
- type Record
- func (r *Record) AddAttributes(attrs ...KeyValue)
- func (r *Record) AttributesLen() int
- func (r *Record) Body() Value
- func (r *Record) ObservedTimestamp() time.Time
- func (r *Record) SetBody(v Value)
- func (r *Record) SetObservedTimestamp(t time.Time)
- func (r *Record) SetSeverity(level Severity)
- func (r *Record) SetSeverityText(text string)
- func (r *Record) SetTimestamp(t time.Time)
- func (r *Record) Severity() Severity
- func (r *Record) SeverityText() string
- func (r *Record) Timestamp() time.Time
- func (r *Record) WalkAttributes(f func(KeyValue) bool)
- type Severity
- type Value
- func (v Value) AsBool() bool
- func (v Value) AsBytes() []byte
- func (v Value) AsFloat64() float64
- func (v Value) AsInt64() int64
- func (v Value) AsMap() []KeyValue
- func (v Value) AsSlice() []Value
- func (v Value) AsString() string
- func (v Value) Empty() bool
- func (v Value) Equal(w Value) bool
- func (v Value) Kind() Kind
- func (v Value) String() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type KeyValue ¶
A KeyValue is a key-value pair used to represent a log attribute (a superset of go.opentelemetry.io/otel/attribute.KeyValue) and map item.
type Kind ¶
type Kind int
Kind is the kind of a Value.
type Logger ¶
type Logger interface {
// Users of the interface can ignore this. This embedded type is only used
// by implementations of this interface. See the "API Implementations"
// section of the package documentation for more information.
embedded.Logger
// Emit emits a log record.
//
// The record may be held by the implementation. Callers should not mutate
// the record after passed.
//
// Implementations of this method need to be safe for a user to call
// concurrently.
Emit(ctx context.Context, record Record)
// Enabled returns whether the Logger emits 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 Logger will emit for the
// provided context and record, and will be false if the Logger will not
// emit. 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).
//
// The record should not be held by the implementation. A copy should be
// made if the record needs to be held after the call returns.
//
// Implementations of this method need to be safe for a user to call
// concurrently.
Enabled(ctx context.Context, record Record) bool
}
Logger emits log records.
Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.
type LoggerConfig ¶
type LoggerConfig struct {
// contains filtered or unexported fields
}
LoggerConfig contains options for a Logger.
func NewLoggerConfig ¶
func NewLoggerConfig(options ...LoggerOption) LoggerConfig
NewLoggerConfig returns a new LoggerConfig with all the options applied.
func (LoggerConfig) InstrumentationAttributes ¶
func (cfg LoggerConfig) InstrumentationAttributes() attribute.Set
InstrumentationAttributes returns the attributes associated with the library providing instrumentation.
func (LoggerConfig) InstrumentationVersion ¶
func (cfg LoggerConfig) InstrumentationVersion() string
InstrumentationVersion returns the version of the library providing instrumentation.
func (LoggerConfig) SchemaURL ¶
func (cfg LoggerConfig) SchemaURL() string
SchemaURL returns the schema URL of the library providing instrumentation.
type LoggerOption ¶
type LoggerOption interface {
// contains filtered or unexported methods
}
LoggerOption applies configuration options to a Logger.
func WithInstrumentationAttributes ¶
func WithInstrumentationAttributes(attr ...attribute.KeyValue) LoggerOption
WithInstrumentationAttributes returns a LoggerOption that sets the instrumentation attributes of a Logger.
The passed attributes will be de-duplicated.
func WithInstrumentationVersion ¶
func WithInstrumentationVersion(version string) LoggerOption
WithInstrumentationVersion returns a LoggerOption that sets the instrumentation version of a Logger.
func WithSchemaURL ¶
func WithSchemaURL(schemaURL string) LoggerOption
WithSchemaURL returns a LoggerOption that sets the schema URL for a Logger.
type LoggerProvider ¶
type LoggerProvider interface {
// Users of the interface can ignore this. This embedded type is only used
// by implementations of this interface. See the "API Implementations"
// section of the package documentation for more information.
embedded.LoggerProvider
// Logger returns a new [Logger] with the provided name and configuration.
//
// If name is empty, implementations need to provide a default name.
//
// Implementations of this method need to be safe for a user to call
// concurrently.
Logger(name string, options ...LoggerOption) Logger
}
LoggerProvider provides access to Logger.
Warning: Methods may be added to this interface in minor releases. See package documentation on API implementation for information on how to set default behavior for unimplemented methods.
type Record ¶
type Record struct {
// contains filtered or unexported fields
}
Record represents a log record.
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) ObservedTimestamp ¶
ObservedTimestamp returns the time when the log record was observed.
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) 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.
type Severity ¶
type Severity int
Severity represents a log record severity (also known as log level). Smaller numerical values correspond to less severe log records (such as debug events), larger numerical values correspond to more severe log records (such as errors and critical events).
const ( // SeverityUndefined represents an unset Severity. SeverityUndefined Severity = 0 // UNDEFINED // A fine-grained debugging log record. Typically disabled in default // configurations. SeverityTrace1 Severity = 1 // TRACE SeverityTrace2 Severity = 2 // TRACE2 SeverityTrace3 Severity = 3 // TRACE3 SeverityTrace4 Severity = 4 // TRACE4 // A debugging log record. SeverityDebug1 Severity = 5 // DEBUG SeverityDebug2 Severity = 6 // DEBUG2 SeverityDebug3 Severity = 7 // DEBUG3 SeverityDebug4 Severity = 8 // DEBUG4 // An informational log record. Indicates that an event happened. SeverityInfo1 Severity = 9 // INFO SeverityInfo2 Severity = 10 // INFO2 SeverityInfo3 Severity = 11 // INFO3 SeverityInfo4 Severity = 12 // INFO4 // A warning log record. Not an error but is likely more important than an // informational event. SeverityWarn1 Severity = 13 // WARN SeverityWarn2 Severity = 14 // WARN2 SeverityWarn3 Severity = 15 // WARN3 SeverityWarn4 Severity = 16 // WARN4 // An error log record. Something went wrong. SeverityError1 Severity = 17 // ERROR SeverityError2 Severity = 18 // ERROR2 SeverityError3 Severity = 19 // ERROR3 SeverityError4 Severity = 20 // ERROR4 // A fatal log record such as application or system crash. SeverityFatal1 Severity = 21 // FATAL SeverityFatal2 Severity = 22 // FATAL2 SeverityFatal3 Severity = 23 // FATAL3 SeverityFatal4 Severity = 24 // FATAL4 // Convenience definitions for the base severity of each level. SeverityTrace = SeverityTrace1 SeverityDebug = SeverityDebug1 SeverityInfo = SeverityInfo1 SeverityWarn = SeverityWarn1 SeverityError = SeverityError1 SeverityFatal = SeverityFatal1 )
Severity values defined by OpenTelemetry.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
A Value represents a structured log value. A zero value is valid and represents an empty value.
func BytesValue ¶
BytesValue returns a Value for a byte slice. The passed slice must not be changed after it is passed.
func MapValue ¶
MapValue returns a new Value for a slice of key-value pairs. The passed slice must not be changed after it is passed.
func SliceValue ¶
SliceValue returns a Value for a slice of Value. The passed slice must not be changed after it is passed.
func (Value) String ¶
String returns Value's value as a string, formatted like fmt.Sprint.
The returned string is meant for debugging; the string representation is not stable.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package embedded provides interfaces embedded within the [OpenTelemetry Logs Bridge API].
|
Package embedded provides interfaces embedded within the [OpenTelemetry Logs Bridge API]. |
|
Package global provides access to a global implementation of the OpenTelemetry Logs Bridge API.
|
Package global provides access to a global implementation of the OpenTelemetry Logs Bridge API. |
|
internal
|
|
|
Package logtest is a testing helper package.
|
Package logtest is a testing helper package. |
|
Package noop provides an implementation of the [OpenTelemetry Logs Bridge API] that produces no telemetry and minimizes used computation resources.
|
Package noop provides an implementation of the [OpenTelemetry Logs Bridge API] that produces no telemetry and minimizes used computation resources. |