telemetry

Documentation

Index

• Constants
• func ConnectClientOptions(cfg Config) ([]connect.ClientOption, error)
• func ConnectInterceptor(cfg Config) (connect.Interceptor, error)
• func ContextWithLogAttrs(ctx context.Context, args ...any) context.Context
• func DefaultLogger() *slog.Logger
• func HTTPClient(cfg Config, client *http.Client) *http.Client
• func LoggerWithContext(ctx context.Context, logger *slog.Logger) *slog.Logger
• func Middleware(cfg Config, filters ...func(*http.Request) bool) func(http.Handler) http.Handler
• func NewLogger(next slog.Handler) *slog.Logger
• func NewSampledLogger(next slog.Handler, opts ...SampledLogOption) *slog.Logger
• func Propagator() propagation.TextMapPropagator
• func SampleRatioValue(ratio float64) *float64
• func SampledLogHandler(next slog.Handler, opts ...SampledLogOption) slog.Handler
• func StartSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
• func TraceLogHandler(next slog.Handler) slog.Handler
• type Config
  • func DefaultConfig(serviceName string) Config
  • func DisabledConfig() Config
• type SampledLogOption
  • func WithSampledLogMinimumLevel(level slog.Level) SampledLogOption
  • func WithoutUnsampledLogs() SampledLogOption
• type Shutdown
  • func Setup(ctx context.Context, cfg Config) (Shutdown, error)

Constants

const (
	// DefaultEndpoint is the in-namespace OTLP/HTTP collector endpoint.
	DefaultEndpoint = "http://otel-collector:4318"

	// DefaultMetricInterval is how often metrics are exported.
	DefaultMetricInterval = 30 * time.Second
	// DefaultExportTimeout bounds one telemetry export attempt.
	DefaultExportTimeout = 5 * time.Second
	// DefaultShutdownTimeout bounds provider shutdown.
	DefaultShutdownTimeout = 5 * time.Second
)

Functions

func ConnectClientOptions

func ConnectClientOptions(cfg Config) ([]connect.ClientOption, error)

ConnectClientOptions returns Connect client options for RPC tracing, metrics, and trace context injection.

func ConnectInterceptor

func ConnectInterceptor(cfg Config) (connect.Interceptor, error)

ConnectInterceptor returns Connect RPC tracing and metrics instrumentation.

func ContextWithLogAttrs

func ContextWithLogAttrs(ctx context.Context, args ...any) context.Context

ContextWithLogAttrs stores logging attributes in ctx. Handlers wrapped with TraceLogHandler add those attributes to context-aware log records.

func DefaultLogger

func DefaultLogger() *slog.Logger

DefaultLogger returns the framework structured logger for stdout log collection.

func HTTPClient

func HTTPClient(cfg Config, client *http.Client) *http.Client

HTTPClient returns a client whose transport emits outbound HTTP telemetry.

func LoggerWithContext

func LoggerWithContext(ctx context.Context, logger *slog.Logger) *slog.Logger

LoggerWithContext returns a child logger with the current context log attributes and trace correlation fields copied onto the logger. Use this when passing a logger to an API that does not accept context at log time.

func Middleware

func Middleware(cfg Config, filters ...func(*http.Request) bool) func(http.Handler) http.Handler

Middleware returns HTTP server instrumentation middleware. Filters can be used to skip requests that are instrumented at a richer protocol layer.

func NewLogger

func NewLogger(next slog.Handler) *slog.Logger

NewLogger returns a slog logger that adds context log attributes and trace correlation fields to context-aware log records.

func NewSampledLogger

func NewSampledLogger(next slog.Handler, opts ...SampledLogOption) *slog.Logger

NewSampledLogger returns a logger that adds trace fields and suppresses low-severity records when ctx contains a valid unsampled trace.

func Propagator

func Propagator() propagation.TextMapPropagator

Propagator returns the framework trace context propagator.

func SampleRatioValue

func SampleRatioValue(ratio float64) *float64

SampleRatioValue returns a SampleRatio pointer for Config literals.

func SampledLogHandler

func SampledLogHandler(next slog.Handler, opts ...SampledLogOption) slog.Handler

SampledLogHandler wraps a slog handler and suppresses records below Warn when ctx contains a valid unsampled trace. Records without trace context, records with sampled trace context, and Warn/Error records always pass through.

func StartSpan

func StartSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

StartSpan starts a child span using the caller package as the instrumentation scope. The span name should be a stable operation name, not user input.

func TraceLogHandler

func TraceLogHandler(next slog.Handler) slog.Handler

TraceLogHandler wraps a slog handler and adds context log attributes and trace correlation fields to context-aware log records.

Types

type Config

type Config struct {
	// Enabled controls whether telemetry is installed. If nil, telemetry is
	// enabled unless OTEL_SDK_DISABLED is true.
	Enabled *bool

	// ServiceName becomes the service.name resource attribute. If empty, the
	// value comes from OTEL_SERVICE_NAME or the executable name.
	ServiceName string

	// Endpoint is the OTLP/HTTP base endpoint. If empty, OTEL_EXPORTER_OTLP_ENDPOINT
	// is used, then DefaultEndpoint.
	Endpoint string

	// TracesEnabled and MetricsEnabled can disable individual signals. If nil,
	// the signal is enabled unless the matching OTEL_*_EXPORTER env var is none.
	TracesEnabled  *bool
	MetricsEnabled *bool

	// Headers are sent with OTLP exporter requests.
	Headers map[string]string

	// ResourceAttributes are added to every exported metric and span.
	ResourceAttributes map[string]string

	MetricInterval  time.Duration
	ExportTimeout   time.Duration
	ShutdownTimeout time.Duration

	// SampleRatio sets parent-based root trace sampling. Nil samples all root
	// traces. Use SampleRatioValue to allow an explicit 0% sample ratio.
	SampleRatio *float64
}

Config controls framework OpenTelemetry setup.

func DefaultConfig

func DefaultConfig(serviceName string) Config

DefaultConfig returns the default framework telemetry configuration for a service.

func DisabledConfig

func DisabledConfig() Config

DisabledConfig returns a configuration that disables telemetry.

type SampledLogOption

type SampledLogOption func(*sampledLogConfig)

SampledLogOption customizes SampledLogHandler.

func WithSampledLogMinimumLevel

func WithSampledLogMinimumLevel(level slog.Level) SampledLogOption

WithSampledLogMinimumLevel sets the lowest log level that always passes through even when ctx contains a valid unsampled trace. The default is Warn.

func WithoutUnsampledLogs

func WithoutUnsampledLogs() SampledLogOption

WithoutUnsampledLogs suppresses every record whose ctx contains a valid unsampled trace.

type Shutdown

type Shutdown func(context.Context) error

Shutdown flushes and stops telemetry providers.

func Setup

func Setup(ctx context.Context, cfg Config) (Shutdown, error)

Setup installs OpenTelemetry providers and returns a shutdown function.