Documentation
¶
Overview ¶
OpenTelemetry-aligned logging for provider-runtime consumers.
This is the single shared home for the OTel log model that core-provider (and every other provider-runtime consumer) previously duplicated: one JSON object per line in the OTel log model — `timestamp` RFC3339Nano UTC, the slog level (SeverityText) plus a sibling SeverityNumber, the `service`/`service.name` resource attributes, and trace_id/span_id whenever a span is in the record's context. NewOTelHandler additionally tees each record to the global OTel LoggerProvider (via the otelslog bridge), so when the binary installs an OTLP LoggerProvider (the SDK + exporter setup belongs in main, next to the trace/metric setup), logs become a first-class OTLP signal alongside traces and metrics — while the stderr JSON stream keeps working for log scrapers.
This package deliberately depends only on the OTel log API + the otelslog bridge (not the log SDK), so consumers that never export via OTLP pull no SDK.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewOTelHandler ¶
NewOTelHandler returns the recommended slog.Handler for a service: it tees each record to (a) the OTel-model JSON stream on w (stderr by default, for log scrapers) and (b) the OTel LoggerProvider via the otelslog bridge, so records are exported over OTLP once the binary's main has installed an OTLP LoggerProvider with go.opentelemetry.io/otel/log/global.SetLoggerProvider. This package installs none (see the note at the end of this file). With no LoggerProvider installed the bridge is a no-op and only the JSON stream is written, so this is always safe to use.
Both sides take the trace and span ids from the record's context: the JSON stream stamps trace_id/span_id, and the bridge hands the context to the LoggerProvider, whose SDK sets the OTLP record's trace context from it. So log through a Logger bound with WithContext (NewSlogLogger over this handler) for the records to correlate with the trace.
func NewOTelJSONHandler ¶
NewOTelJSONHandler returns a slog.Handler that writes one JSON object per line to w (defaulting to os.Stderr when nil) in the OTel log model: `timestamp` RFC3339Nano UTC, the level (SeverityText) plus a sibling SeverityNumber, the supplied persistent attrs (e.g. service.name), and trace_id/span_id whenever a span is present in the record's context.
func ServiceNameAttr ¶
ServiceNameAttr is the persistent OTel resource attribute pair to pass to NewOTelHandler / NewOTelJSONHandler for a given service name.
Types ¶
type ContextLogger ¶ added in v1.13.0
type ContextLogger interface {
// WithContext returns a Logger that passes ctx with every record it logs.
// The Loggers that its WithName and WithValues return keep ctx.
WithContext(ctx context.Context) Logger
}
A ContextLogger is a Logger that can bind a context.Context, so that every record it logs carries that context to the backend. A backend that reads the record's context can act on what it holds: NewOTelJSONHandler, and the otelslog bridge behind NewOTelHandler, stamp the trace and span ids of the span in it, which correlates the log with the trace.
It is optional, so a Logger written before it existed keeps compiling and working. Call it through WithContext, which handles a Logger that does not implement it.
type Logger ¶
type Logger interface {
// Info logs a message with optional structured data. Structured data must
// be supplied as an array that alternates between string keys and values of
// an arbitrary type. Use Info for messages that operators are
// very likely to be concerned with when running.
Info(msg string, keysAndValues ...any)
// Debug logs a message with optional structured data. Structured data must
// be supplied as an array that alternates between string keys and values of
// an arbitrary type. Use Debug for messages that operators or
// developers may be concerned with when debugging.
Debug(msg string, keysAndValues ...any)
// Error logs an error with a message and optional structured data.
// Structured data must be supplied as an array that alternates between
// string keys and values of an arbitrary type. Use Error for messages
Error(err error, msg string, keysAndValues ...any)
// Warn logs a message with optional structured data. Structured data must
// be supplied as an array that alternates between string keys and values of
// an arbitrary type. Use Warn for messages that operators should be aware of.
Warn(msg string, keysAndValues ...any)
// WithValues returns a Logger that will include the supplied structured
// data with any subsequent messages it logs. Structured data must
// be supplied as an array that alternates between string keys and values of
// an arbitrary type.
WithValues(keysAndValues ...any) Logger
// WithName returns a Logger that will include the supplied name with any
// subsequent messages it logs. The name is typically a component name or
// similar, and should be used to distinguish between different components
// or subsystems.
WithName(name string) Logger
}
A Logger logs messages. Messages may be supplemented by structured data.
func NewLogrLogger ¶
NewLogrLogger returns a Logger that is satisfied by the supplied logr.Logger, which may be satisfied in turn by various logging implementations (Zap, klog, etc). Debug messages are logged at V(1).
Its records carry no context, so they never carry trace or span ids: see logrLogger.WithContext.
func NewSlogLogger ¶
NewSlogLogger returns a Logger that logs through l. It is a ContextLogger: after WithContext, every record carries the bound context to l's handler.