logging

package
v1.15.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 9 Imported by: 1

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

func NewOTelHandler(level slog.Leveler, w io.Writer, serviceName string) slog.Handler

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

func NewOTelJSONHandler(level slog.Leveler, w io.Writer, attrs ...slog.Attr) slog.Handler

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

func ServiceNameAttr(serviceName string) []slog.Attr

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

func NewLogrLogger(l logr.Logger) Logger

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 NewNopLogger

func NewNopLogger() Logger

NewNopLogger returns a Logger that does nothing.

func NewSlogLogger

func NewSlogLogger(l slog.Logger) Logger

NewSlogLogger returns a Logger that logs through l. It is a ContextLogger: after WithContext, every record carries the bound context to l's handler.

func WithContext added in v1.13.0

func WithContext(l Logger, ctx context.Context) Logger

WithContext returns l bound to ctx when l is a ContextLogger, and l unchanged when it is not. A ctx that holds no span stamps nothing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL