logging

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

• func NewOTelHandler(level slog.Leveler, w io.Writer, serviceName string) slog.Handler
• func NewOTelJSONHandler(level slog.Leveler, w io.Writer, attrs ...slog.Attr) slog.Handler
• func ServiceNameAttr(serviceName string) []slog.Attr
• type Logger
  • func NewLogrLogger(l logr.Logger) Logger
  • func NewNopLogger() Logger
  • func NewSlogLogger(l slog.Logger) Logger

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 SetupOTLPLogs has installed an exporter. With no LoggerProvider installed the bridge is a no-op and only the JSON stream is written, so this is always safe to use.

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

func NewNopLogger

func NewNopLogger() Logger

NewNopLogger returns a Logger that does nothing.

func NewSlogLogger

func NewSlogLogger(l slog.Logger) Logger