log

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 8, 2024 License: Apache-2.0 Imports: 13 Imported by: 67

README

Log API

PkgGoDev

Documentation

Overview

Package log provides the OpenTelemetry Logs API.

This package is intended to be used by bridges between existing logging libraries and OpenTelemetry. Users should not directly use this package as a logging library. Instead, install one of the bridges listed in the registry, and use the associated logging library.

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type EnabledParameters added in v0.7.0 

type EnabledParameters struct {
	// contains filtered or unexported fields
}

EnabledParameters represents payload for Logger's Enabled method.

func (*EnabledParameters) SetSeverity added in v0.7.0 

func (r *EnabledParameters) SetSeverity(level Severity)

SetSeverity sets the Severity level.

func (*EnabledParameters) Severity added in v0.7.0 

func (r *EnabledParameters) Severity() (value Severity, ok bool)

Severity returns the Severity level value, or SeverityUndefined if no value was set. The ok result indicates whether the value was set.

type KeyValue 

type KeyValue struct {
	Key   string
	Value Value
}

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.

func Bool 

func Bool(key string, value bool) KeyValue

Bool returns a KeyValue for a bool value.

func Bytes 

func Bytes(key string, value []byte) KeyValue

Bytes returns a KeyValue for a []byte value. The passed slice must not be changed after it is passed.

func Empty 

func Empty(key string) KeyValue

Empty returns a KeyValue with an empty value.

func Float64 

func Float64(key string, value float64) KeyValue

Float64 returns a KeyValue for a float64 value.

func Int 

func Int(key string, value int) KeyValue

Int returns a KeyValue for an int value.

func Int64 

func Int64(key string, value int64) KeyValue

Int64 returns a KeyValue for an int64 value.

func Map 

func Map(key string, value ...KeyValue) KeyValue

Map returns a KeyValue for a map value. The passed slice must not be changed after it is passed.

func Slice 

func Slice(key string, value ...Value) KeyValue

Slice returns a KeyValue for a []Value value. The passed slice must not be changed after it is passed.

func String 

func String(key, value string) KeyValue

String returns a KeyValue for a string value.

func (KeyValue) Equal 

func (a KeyValue) Equal(b KeyValue) bool

Equal returns if a is equal to b.

func (KeyValue) String 

func (a KeyValue) String() string

String returns key-value pair as a string, formatted like "key:value".

The returned string is meant for debugging; the string representation is not stable.

type Kind 

type Kind int

Kind is the kind of a Value. 

const (
	KindEmpty Kind = iota
	KindBool
	KindFloat64
	KindInt64
	KindString
	KindBytes
	KindSlice
	KindMap
)

Kind values.

func (Kind) String 

func (i Kind) String() string

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.
	//
	// Notice: Emit is intended to be used by log bridges.
	// Is should not be used for writing instrumentation.
	Emit(ctx context.Context, record Record)

	// Enabled returns whether the Logger emits for the given context and
	// param.
	//
	// The passed param is likely to be a partial record with only the
	// bridge-relevant information being provided (e.g a param 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 param, 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 param 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.
	//
	// Notice: Enabled is intended to be used by log bridges.
	// Is should not be used for writing instrumentation.
	Enabled(ctx context.Context, param EnabledParameters) 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.
	//
	// The name needs to uniquely identify the source of logged code. It is
	// recommended that name is the Go package name of the library using a log
	// bridge (note: this is not the name of the bridge package). Most
	// commonly, this means a bridge will need to accept this value from its
	// users.
	//
	// If name is empty, implementations need to provide a default name.
	//
	// The version of the packages using a bridge can be critical information
	// to include when logging. The bridge should accept this version
	// information and use the [WithInstrumentationVersion] option to configure
	// the Logger appropriately.
	//
	// 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 

func (r *Record) AddAttributes(attrs ...KeyValue)

AddAttributes adds attributes to the log record.

func (*Record) AttributesLen 

func (r *Record) AttributesLen() int

AttributesLen returns the number of attributes in the log record.

func (*Record) Body 

func (r *Record) Body() Value

Body returns the body of the log record.

func (*Record) ObservedTimestamp 

func (r *Record) ObservedTimestamp() time.Time

ObservedTimestamp returns the time when the log record was observed.

func (*Record) SetBody 

func (r *Record) SetBody(v Value)

SetBody sets the body of the log record.

func (*Record) SetObservedTimestamp 

func (r *Record) SetObservedTimestamp(t time.Time)

SetObservedTimestamp sets the time when the log record was observed.

func (*Record) SetSeverity 

func (r *Record) SetSeverity(level Severity)

SetSeverity sets the Severity level of the log record.

func (*Record) SetSeverityText 

func (r *Record) SetSeverityText(text string)

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 

func (r *Record) SetTimestamp(t time.Time)

SetTimestamp sets the time when the log record occurred.

func (*Record) Severity 

func (r *Record) Severity() Severity

Severity returns the Severity of the log record.

func (*Record) SeverityText 

func (r *Record) SeverityText() string

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) Timestamp 

func (r *Record) Timestamp() time.Time

Timestamp returns the time when the log record occurred.

func (*Record) WalkAttributes 

func (r *Record) WalkAttributes(f func(KeyValue) bool)

WalkAttributes walks all attributes the log record holds by calling f for each on each KeyValue in the Record. Iteration stops if f returns false.

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.

func (Severity) String 

func (i Severity) String() string

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 BoolValue 

func BoolValue(v bool) Value

BoolValue returns a Value for a bool.

func BytesValue 

func BytesValue(v []byte) Value

BytesValue returns a Value for a byte slice. The passed slice must not be changed after it is passed.

func Float64Value 

func Float64Value(v float64) Value

Float64Value returns a Value for a float64.

func Int64Value 

func Int64Value(v int64) Value

Int64Value returns a Value for an int64.

func IntValue 

func IntValue(v int) Value

IntValue returns a Value for an int.

func MapValue 

func MapValue(kvs ...KeyValue) Value

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 

func SliceValue(vs ...Value) Value

SliceValue returns a Value for a slice of Value. The passed slice must not be changed after it is passed.

func StringValue 

func StringValue(v string) Value

StringValue returns a new Value for a string.

func (Value) AsBool 

func (v Value) AsBool() bool

AsBool returns the value held by v as a bool.

func (Value) AsBytes 

func (v Value) AsBytes() []byte

AsBytes returns the value held by v as a []byte.

func (Value) AsFloat64 

func (v Value) AsFloat64() float64

AsFloat64 returns the value held by v as a float64.

func (Value) AsInt64 

func (v Value) AsInt64() int64

AsInt64 returns the value held by v as an int64.

func (Value) AsMap 

func (v Value) AsMap() []KeyValue

AsMap returns the value held by v as a []KeyValue.

func (Value) AsSlice 

func (v Value) AsSlice() []Value

AsSlice returns the value held by v as a []Value.

func (Value) AsString 

func (v Value) AsString() string

AsString returns the value held by v as a string.

func (Value) Empty 

func (v Value) Empty() bool

Empty returns if v does not hold any value.

func (Value) Equal 

func (v Value) Equal(w Value) bool

Equal returns if v is equal to w.

func (Value) Kind 

func (v Value) Kind() Kind

Kind returns the Kind of v.

func (Value) String 

func (v Value) String() 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

View all 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
global
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.