modules/telemetry
Package telemetry sets up OpenTelemetry tracing and metrics and structured logs correlated with requests and traces (ADR-0007).
Tracing is always on, so every log line written with a request context carries trace and span IDs. Spans and metrics are exported only when OTLP export is enabled; the exporters read the standard OTEL_EXPORTER_OTLP_* environment variables, as OpenTelemetry specifies.
By default Setup installs its providers and the W3C trace-context propagator as OpenTelemetry globals, which instrumentation libraries use. Call it once, from the composition root.
Stability: pre-1.0 (ADR-0015).
Constants#
const KeyRequestID, …#
const (
KeyRequestID = "request_id"
KeyTraceID = "trace_id"
KeySpanID = "span_id"
KeyOrgID = "org_id"
)Log attribute keys added from the context.
Functions#
func NewLogHandler#
func NewLogHandler(h slog.Handler) slog.HandlerNewLogHandler wraps h so records logged with a context carry request_id, trace_id, span_id and org_id when available. Keys already present on the record are not added twice.
Types#
type LogFormat#
type LogFormat stringLogFormat selects the log encoding.
const LogFormatJSON, …#
const (
LogFormatJSON LogFormat = "json"
LogFormatText LogFormat = "text"
)Log formats.
type Option#
type Option interface {
// contains filtered or unexported methods
}An Option configures Setup.
func WithLogFormat#
func WithLogFormat(f LogFormat) OptionWithLogFormat sets JSON (default, for production) or text (for local development) logs.
func WithLogLevel#
func WithLogLevel(l slog.Leveler) OptionWithLogLevel sets the minimum log level. Default: info.
func WithLogWriter#
func WithLogWriter(w io.Writer) OptionWithLogWriter sets where logs are written. Default: os.Stdout.
func WithOTLPExport#
func WithOTLPExport(enabled bool) OptionWithOTLPExport enables exporting spans and metrics over OTLP/HTTP, configured by the standard OTEL_EXPORTER_OTLP_* environment variables.
func WithSampleRatio#
func WithSampleRatio(r float64) OptionWithSampleRatio sets the fraction of new traces sampled, from 0 to 1. Child spans follow their parent's decision. Default: 1.
func WithSpanExporter#
func WithSpanExporter(e sdktrace.SpanExporter) OptionWithSpanExporter adds a synchronous span exporter, for tests and custom backends.
func WithoutGlobals#
func WithoutGlobals() OptionWithoutGlobals keeps Setup from installing OpenTelemetry globals.
type Telemetry#
type Telemetry struct {
// contains filtered or unexported fields
}Telemetry holds the configured logger and OpenTelemetry providers.
func Setup#
func Setup(ctx context.Context, service, version string, opts ...Option) (*Telemetry, error)Setup configures telemetry for service at version.
func (*Telemetry) HTTPMiddleware#
func (t *Telemetry) HTTPMiddleware() func(http.Handler) http.HandlerHTTPMiddleware starts a server span for each request, extracts incoming W3C trace context, records standard HTTP server metrics, and names the span after the matched http.ServeMux pattern (for example "GET /v1/projects/{id}") so traces group by route, not by raw path.
func (*Telemetry) Logger#
func (t *Telemetry) Logger() *slog.LoggerLogger returns the correlated structured logger.
func (*Telemetry) MeterProvider#
func (t *Telemetry) MeterProvider() metric.MeterProviderMeterProvider returns the meter provider.
func (*Telemetry) Shutdown#
func (t *Telemetry) Shutdown(ctx context.Context) errorShutdown flushes and stops exporters. Register it first on the cleanup stack so it runs last.
func (*Telemetry) TracerProvider#
func (t *Telemetry) TracerProvider() trace.TracerProviderTracerProvider returns the tracer provider.