Audit Compliance: Logs API Logger

[MrAlias]

Blocked by:

• Logs to reuse attribute.[Key]Value and remove log.[Key]Value types #7034

1. Review the Logger section of the Logs Bridge API specification for all normative statements1. Audit the logs bridge API package for compliance with the specified normative statements.
2. Identify existing issues or create new issues to track any work needed to make the logs bridge API package compliant with the specification.

[pellared]

Blocked by:

• Specs inconsistent Enabled API for Logger #5769

[pellared]

Unblocked

[XSAM]

The Logger is responsible for emitting LogRecords.

opentelemetry-go/log/logger.go

Lines 13 to 18 in 5ba5e7a

	// 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 Logger interface {

Logger operations

The Logger MUST provide functions to:

• Emit a LogRecord

opentelemetry-go/log/logger.go

Lines 24 to 31 in 5ba5e7a

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

The Logger SHOULD provide functions to:

• Report if Logger is Enabled

opentelemetry-go/log/logger.go

Lines 33 to 57 in 5ba5e7a

	// Enabled returns whether the Logger emits for the given context and
	// param.
	//
	// This is useful for users that want to know if a [Record]
	// will be processed or dropped before they perform complex operations to
	// construct the [Record].
	//
	// The passed param is likely to be a partial record 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 param 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, param EnabledParameters) bool

We are compliant.

[XSAM]

Emit a LogRecord

The effect of calling this API is to emit a LogRecord to the processing pipeline.

opentelemetry-go/log/record.go

Lines 17 to 19 in f8df2f9

	// Record represents a log record.
	// A log record with non-empty event name is interpreted as an event record.
	type Record struct {

The API MUST accept the following parameters:

• Timestamp (optional)

opentelemetry-go/log/record.go

Lines 61 to 69 in f8df2f9

	// Timestamp returns the time when the log record occurred.
	func (r *Record) Timestamp() time.Time {
	return r.timestamp
	}
	// SetTimestamp sets the time when the log record occurred.
	func (r *Record) SetTimestamp(t time.Time) {
	r.timestamp = t
	}

• Observed Timestamp (optional).

opentelemetry-go/log/record.go

Lines 71 to 79 in f8df2f9

	// ObservedTimestamp returns the time when the log record was observed.
	func (r *Record) ObservedTimestamp() time.Time {
	return r.observedTimestamp
	}
	// SetObservedTimestamp sets the time when the log record was observed.
	func (r *Record) SetObservedTimestamp(t time.Time) {
	r.observedTimestamp = t
	}

• The Context associated with the LogRecord.
  When implicit Context is supported, then this parameter SHOULD be optional and
  if unspecified then MUST use current Context.
  When only explicit Context is supported, this parameter SHOULD be required.

opentelemetry-go/log/logger.go

Line 31 in 5ba5e7a

Emit(ctx context.Context, record Record)

• Severity Number (optional)

opentelemetry-go/log/record.go

Lines 81 to 89 in f8df2f9

	// Severity returns the [Severity] of the log record.
	func (r *Record) Severity() Severity {
	return r.severity
	}
	// SetSeverity sets the [Severity] level of the log record.
	func (r *Record) SetSeverity(level Severity) {
	r.severity = level
	}

• Severity Text (optional)

opentelemetry-go/log/record.go

Lines 91 to 101 in f8df2f9

	// 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 (r *Record) SeverityText() string {
	return r.severityText
	}
	// 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 (r *Record) SetSeverityText(text string) {
	r.severityText = text
	}

• Body (optional)

opentelemetry-go/log/record.go

Lines 103 to 111 in f8df2f9

	// Body returns the body of the log record.
	func (r *Record) Body() Value {
	return r.body
	}
	// SetBody sets the body of the log record.
	func (r *Record) SetBody(v Value) {
	r.body = v
	}

• Attributes (optional)

opentelemetry-go/log/record.go

Lines 128 to 139 in f8df2f9

	// AddAttributes adds attributes to the log record.
	func (r *Record) AddAttributes(attrs ...KeyValue) {
	var i int
	for i = 0; i < len(attrs) && r.nFront < len(r.front); i++ {
	a := attrs[i]
	r.front[r.nFront] = a
	r.nFront++
	}
	r.back = slices.Grow(r.back, len(attrs[i:]))
	r.back = append(r.back, attrs[i:]...)
	}

• Status: Development - Event Name (optional)

opentelemetry-go/log/record.go

Lines 49 to 59 in f8df2f9

	// EventName returns the event name.
	// A log record with non-empty event name is interpreted as an event record.
	func (r *Record) EventName() string {
	return r.eventName
	}
	// SetEventName sets the event name.
	// A log record with non-empty event name is interpreted as an event record.
	func (r *Record) SetEventName(s string) {
	r.eventName = s
	}

The API SHOULD provide functionality for users to convert Standard Attributes so they can be used, or directly accept them, in the log signal. This allows the reuse of Standard Attributes across signals.

opentelemetry-go/log/logger.go

Lines 117 to 126 in 80ce404

	// WithInstrumentationAttributes returns a [LoggerOption] that sets the
	// instrumentation attributes of a [Logger].
	//
	// The passed attributes will be de-duplicated.
	func WithInstrumentationAttributes(attr ...attribute.KeyValue) LoggerOption {
	return loggerOptionFunc(func(config LoggerConfig) LoggerConfig {
	config.attrs = attribute.NewSet(attr...)
	return config
	})
	}

[XSAM]

Enabled

opentelemetry-go/log/logger.go

Line 57 in 5ba5e7a

Enabled(ctx context.Context, param EnabledParameters) bool

Status: Development

To help users avoid performing computationally expensive operations when
generating a LogRecord, a Logger SHOULD provide this Enabled API.

The API SHOULD accept the following parameters:

• The Context to be associated with the LogRecord.
  When implicit Context is supported, then this parameter SHOULD be optional and
  if unspecified then MUST use current Context.

opentelemetry-go/log/logger.go

Line 57 in 5ba5e7a

Enabled(ctx context.Context, param EnabledParameters) bool

When only explicit Context is supported, accepting this parameter is REQUIRED.

• Severity Number (optional)
• Event Name (optional)

opentelemetry-go/log/logger.go

Lines 138 to 141 in 1bae8f7

	type EnabledParameters struct {
	Severity Severity
	EventName string
	}

Note

Adding parameters in the struct in the future does not seem to bring breaking changes.

This API MUST return a language idiomatic boolean type. A returned value of
true means the Logger is enabled for the provided arguments, and a returned
value of false means the Logger is disabled for the provided arguments.

opentelemetry-go/log/logger.go

Lines 45 to 50 in 5ba5e7a

	// 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).

opentelemetry-go/log/logger.go

Line 57 in 5ba5e7a

Enabled(ctx context.Context, param EnabledParameters) bool

The returned value is not always static, it can change over time. The API
SHOULD be documented that instrumentation authors needs to call this API each
time they emit a LogRecord to ensure they have the most
up-to-date response.

opentelemetry-go/log/logger.go

Lines 36 to 38 in 5ba5e7a

	// This is useful for users that want to know if a [Record]
	// will be processed or dropped before they perform complex operations to
	// construct the [Record].

We are compliant.

[XSAM]

Concurrency requirements

Logger - all methods are safe to be called concurrently.

opentelemetry-go/log/logger.go

Lines 29 to 31 in 5ba5e7a

	// Implementations of this method need to be safe for a user to call
	// concurrently.
	Emit(ctx context.Context, record Record)

opentelemetry-go/log/logger.go

Lines 55 to 57 in 5ba5e7a

	// Implementations of this method need to be safe for a user to call
	// concurrently.
	Enabled(ctx context.Context, param EnabledParameters) bool

We are compliant.

[XSAM]

@open-telemetry/go-maintainers I have a question on this #5679 (comment). I am not sure we are fully compliant.