observability

Documentation

Index

• func ExtractPropagation(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
• func InitMeterProvider(cfg Config, registry promclient.Registerer) error
• func InitTracer(cfg Config) error
• func InjectPropagation(ctx context.Context, carrier propagation.TextMapCarrier)
• func IsTracingEnabled() bool
• func Meter(instrumentationName string, opts ...metric.MeterOption) metric.Meter
• func NewHTTPHandler(handler http.Handler, name string) http.Handler
• func NewHTTPHandlerFunc(handlerFunc http.HandlerFunc, name string) http.HandlerFunc
• func ShutdownMeterProvider(ctx context.Context) error
• func ShutdownTracer(ctx context.Context) error
• func SpanError(ctx context.Context, err error)
• func SpanFromContext(ctx context.Context) trace.Span
• func SpanIDFromContext(ctx context.Context) string
• func TraceIDFromContext(ctx context.Context) string
• func TraceLogger(ctx context.Context, logger logr.Logger) logr.Logger
• func Tracer() trace.Tracer
• type Config

Functions

func ExtractPropagation

func ExtractPropagation(ctx context.Context, carrier propagation.TextMapCarrier) context.Context

ExtractPropagation extracts trace propagation headers from a carrier. Returns a new context with the extracted trace context.

func InitMeterProvider

func InitMeterProvider(cfg Config, registry promclient.Registerer) error

InitMeterProvider initializes the global MeterProvider with a Prometheus exporter. The Prometheus exporter serves metrics on the existing controller-runtime /metrics endpoint by sharing the same prometheus.Registry.

When OTLP metric export is needed in the future, an additional OTLP metric exporter can be added as a reader alongside the Prometheus exporter.

func InitTracer

func InitTracer(cfg Config) error

InitTracer sets up the global TracerProvider. When cfg.OTLPEndpoint is empty, a no-op provider is used and tracing is effectively disabled.

func InjectPropagation

func InjectPropagation(ctx context.Context, carrier propagation.TextMapCarrier)

InjectPropagation injects trace propagation headers into a carrier (e.g. HTTP headers). This is useful for propagating trace context across service boundaries.

func IsTracingEnabled

func IsTracingEnabled() bool

IsTracingEnabled returns true if a real (non-noop) TracerProvider is configured.

func Meter

func Meter(instrumentationName string, opts ...metric.MeterOption) metric.Meter

Meter returns the global Meter for this service. If the MeterProvider has not been initialized, a no-op Meter is returned.

func NewHTTPHandler

func NewHTTPHandler(handler http.Handler, name string) http.Handler

NewHTTPHandler wraps an http.Handler with OpenTelemetry tracing middleware. When tracing is disabled, the original handler is returned unchanged.

Usage:

handler := observability.NewHTTPHandler(myHandler, "my-service")

func NewHTTPHandlerFunc

func NewHTTPHandlerFunc(handlerFunc http.HandlerFunc, name string) http.HandlerFunc

NewHTTPHandlerFunc wraps an http.HandlerFunc with OpenTelemetry tracing middleware. When tracing is disabled, the original handler is returned unchanged.

func ShutdownMeterProvider

func ShutdownMeterProvider(ctx context.Context) error

ShutdownMeterProvider flushes and shuts down the MeterProvider.

func ShutdownTracer

func ShutdownTracer(ctx context.Context) error

ShutdownTracer flushes and shuts down the TracerProvider.

func SpanError

func SpanError(ctx context.Context, err error)

SpanError records an error on the current span from context (if tracing is enabled). It also sets the span status to Error.

func SpanFromContext

func SpanFromContext(ctx context.Context) trace.Span

SpanFromContext returns the current span from the context. Returns nil if tracing is disabled or no span exists.

func SpanIDFromContext

func SpanIDFromContext(ctx context.Context) string

SpanIDFromContext extracts the span ID from the context. Returns an empty string if no valid span exists.

func TraceIDFromContext

func TraceIDFromContext(ctx context.Context) string

TraceIDFromContext extracts the trace ID from the context. Returns an empty string if no valid span exists.

func TraceLogger

func TraceLogger(ctx context.Context, logger logr.Logger) logr.Logger

TraceLogger returns a logger augmented with trace_id and span_id fields when tracing is enabled and a valid span exists in the context. When tracing is disabled or no span is present, the original logger is returned unchanged.

Usage:

logger := observability.TraceLogger(ctx, log.FromContext(ctx))

func Tracer

func Tracer() trace.Tracer

Tracer returns the global tracer for this service. If tracing is disabled, it returns a no-op tracer.

Types

type Config

type Config struct {
	// ServiceName is the name of this service, e.g. "rocket-manager" or "rocket-agent".
	ServiceName string

	// OTLPEndpoint is the address of the OTLP exporter (e.g. "otel-collector:4317").
	// When empty, tracing is disabled (noop TracerProvider).
	OTLPEndpoint string

	// OTLPInsecure determines whether to use insecure connection for OTLP gRPC.
	OTLPInsecure bool

	// SampleRate is the trace sampling probability (0.0 - 1.0). Default: 1.0 when OTLP is configured.
	SampleRate float64
}

Config holds the configuration for observability (tracing) setup.