Documentation
¶
Index ¶
- Constants
- type Logger
- func (l *Logger) Debug(msg string, args ...any)
- func (l *Logger) Error(msg string, args ...any)
- func (l *Logger) Info(msg string, args ...any)
- func (l *Logger) Slog() *slog.Logger
- func (l *Logger) Verbose(msg string, args ...any)
- func (l *Logger) Warn(msg string, args ...any)
- func (l *Logger) With(args ...any) *Logger
- type OTelHandles
- type Options
- type SpanLogger
- func (s *SpanLogger) Debug(msg string, args ...any)
- func (s *SpanLogger) Error(msg string, args ...any)
- func (s *SpanLogger) Info(msg string, args ...any)
- func (s *SpanLogger) Slog() *slog.Logger
- func (s *SpanLogger) Span() trace.Span
- func (s *SpanLogger) Verbose(msg string, args ...any)
- func (s *SpanLogger) Warn(msg string, args ...any)
- func (s *SpanLogger) With(args ...any) *SpanLogger
- type Telemetry
- type Tracer
- type Transport
Constants ¶
const ( LevelDebug = slog.LevelDebug // -4 LevelVerbose = slog.Level(-2) LevelInfo = slog.LevelInfo // 0 LevelWarning = slog.LevelWarn // 4 LevelError = slog.LevelError // 8 )
slog convention: higher value = more important.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger is a thin facade over *slog.Logger. It is the top-level logger returned as Telemetry.Logger and emits records with context.Background().
To get a logger that auto-correlates to a span, use Tracer.Start — it returns a SpanLogger bound to the new span's context.
Use Slog() to reach the underlying *slog.Logger when interfacing with libraries that expect stdlib slog.
type OTelHandles ¶
type OTelHandles struct {
LoggerProvider logsapi.LoggerProvider
MeterProvider metricapi.MeterProvider
Propagator propagation.TextMapPropagator
TracerProvider traceapi.TracerProvider
}
OTelHandles bundles the OpenTelemetry providers and propagator. Returned by (*Telemetry).OTel(). Use these when wiring third-party instrumentation libraries that take a provider/propagator directly.
type Options ¶
type Options struct {
// Level is the minimum log level. "" defaults to Info silently;
// unrecognised values fall back to Info and emit one stderr warning.
// Accepted (case-insensitive): error, warn/warning, info, verbose, debug.
Level string
// LogExporter overrides the OTLP log exporter. Set this to plug in a
// test exporter or a non-OTLP backend. When set, OTLPEndpoint /
// Transport / OTLPSecure are ignored for logs.
LogExporter sdklog.Exporter
// MetricExporter overrides the OTLP metric exporter. Same semantics
// as LogExporter.
MetricExporter sdkmetric.Exporter
// MetricExportInterval controls how often metrics are pushed to the
// collector. Zero uses the SDK default (60s).
MetricExportInterval time.Duration
// OnError, if set, receives async errors from the OTel SDK (exporter
// failures, dropped batches) and from the multi-handler (per-handler
// write errors). When nil, errors are silently discarded.
//
// Setting OnError causes Init to install otel.SetErrorHandler — the
// only OTel global Init ever touches, and only on opt-in.
OnError func(error)
// OTLPEndpoint is the host[:port] of the collector. When the port is
// omitted, it defaults to 4317 for TransportGRPC and 4318 for
// TransportHTTP. Empty disables OTLP export.
OTLPEndpoint string
// OTLPSecure controls whether the OTLP exporter uses TLS.
OTLPSecure bool
// ServiceName is required.
ServiceName string
// ServiceVersion is the version reported as service.version on every
// signal. Empty triggers a debug.ReadBuildInfo() lookup; if that also
// yields nothing, the final value is "unknown".
ServiceVersion string
// TraceExporter overrides the OTLP trace exporter. Same semantics as
// LogExporter.
TraceExporter sdktrace.SpanExporter
// TraceSampleRatio: 0 means ParentBased(AlwaysOn). A value in (0,1]
// switches to ParentBased(TraceIDRatioBased(ratio)).
TraceSampleRatio float64
// Transport selects the OTLP wire protocol. Defaults to gRPC.
Transport Transport
}
Options configures Init. ServiceName is required. ServiceVersion is required unless debug.ReadBuildInfo can supply one. OTLPEndpoint being empty disables OTLP entirely — logs still print to stdout, traces and metrics fall through to noop providers. A per-signal exporter override (LogExporter/TraceExporter/MetricExporter) enables that signal even when OTLPEndpoint is empty.
type SpanLogger ¶
type SpanLogger struct {
// contains filtered or unexported fields
}
SpanLogger is a Logger bound to a span. Returned by Tracer.Start. Its log methods correlate to the span's trace_id and span_id via the otelslog bridge. SpanLogger is independent of Logger — they share an underlying *slog.Logger but the SpanLogger always emits with the bound span context.
func (*SpanLogger) Debug ¶
func (s *SpanLogger) Debug(msg string, args ...any)
func (*SpanLogger) Error ¶
func (s *SpanLogger) Error(msg string, args ...any)
func (*SpanLogger) Info ¶
func (s *SpanLogger) Info(msg string, args ...any)
func (*SpanLogger) Slog ¶
func (s *SpanLogger) Slog() *slog.Logger
Slog returns the underlying *slog.Logger. Note: callers passing this to libraries lose the span binding unless they also pass the ctx.
func (*SpanLogger) Span ¶
func (s *SpanLogger) Span() trace.Span
Span returns the underlying trace.Span. Use it to End the span, RecordError, SetAttributes, etc.
func (*SpanLogger) Verbose ¶
func (s *SpanLogger) Verbose(msg string, args ...any)
func (*SpanLogger) Warn ¶
func (s *SpanLogger) Warn(msg string, args ...any)
func (*SpanLogger) With ¶
func (s *SpanLogger) With(args ...any) *SpanLogger
With returns a new SpanLogger bound to the same span whose every record carries the given attrs.
type Telemetry ¶
type Telemetry struct {
Logger *Logger
Tracer *Tracer
Meter metricapi.Meter
// contains filtered or unexported fields
}
Telemetry is the bundle returned by Init.
The day-to-day handles are Logger, Tracer, and Meter. Tracer.Start returns a *SpanLogger so logs in that scope correlate to the span without the caller having to thread a context through every log call:
ctx, log := tel.Tracer.Start(ctx, "boot")
defer log.Span().End()
log.Info("connected to the boot span")
The OTel providers and propagator are reachable via OTel() for wiring third-party instrumentation libraries (otelhttp, otelgrpc, …).
func Init ¶
Init builds a Telemetry bundle. Init never reads or writes OTel globals unless Options.OnError is set (in which case otel.SetErrorHandler is installed so SDK errors reach the caller).
Call (*Telemetry).Shutdown to flush exporters; it is idempotent and respects the caller's ctx for its timeout budget.
func (*Telemetry) Flush ¶
Flush forces all enabled exporters to flush their pending data. Useful for short-lived jobs, k8s preStop hooks, or post-crash diagnostics that need data on the wire before continuing.
func (*Telemetry) OTel ¶
func (t *Telemetry) OTel() OTelHandles
OTel returns the bundle's OpenTelemetry providers and propagator. Use these when wiring third-party instrumentation libraries (otelhttp, otelgrpc, otelsql, …). Most callers never need this.
type Tracer ¶
type Tracer struct {
// contains filtered or unexported fields
}
Tracer wraps an OTel trace.Tracer so that Start returns, alongside the child context, a *SpanLogger pre-bound to the new span. Logs written through that SpanLogger correlate to the span automatically.
func (*Tracer) Extract ¶
func (t *Tracer) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
Extract reads incoming W3C trace-context (traceparent/tracestate) from carrier and returns a context whose active span context is the remote parent. Feed the result to Start so the service's span joins the caller's trace — e.g. a reverse-proxy's server span. A missing or invalid header leaves ctx unchanged, so Start opens a fresh root span; it never errors.
Wrap an http.Header with propagation.HeaderCarrier:
ctx = tel.Tracer.Extract(ctx, propagation.HeaderCarrier(req.Header)) ctx, log := tel.Tracer.Start(ctx, "handle") defer log.Span().End()
Source Files