obsx

Observability library for Go providing metrics (Prometheus) and tracing (OpenTelemetry) setup with consistent defaults. Creates a Prometheus registry with process/Go collectors, a metrics factory with namespace/subsystem scoping, and an OTLP gRPC tracer provider with configurable sampling.

go get git.codelab.vc/pkg/obsx

Quick start

// Tracing
shutdown, err := obsx.SetupTracer(ctx, obsx.TracerConfig{
    ServiceName:    "my-service",
    ServiceVersion: "1.0.0",
    Endpoint:       "localhost:4317",
    Sampler:        1.0, // sample everything
})
if err != nil {
    log.Fatal(err)
}
defer shutdown(ctx)

// Metrics
metrics := obsx.NewMetrics(obsx.MetricsConfig{
    Namespace: "myapp",
    Subsystem: "http",
})
reqCounter := metrics.Counter("requests_total", "Total HTTP requests", "method", "status")
latency := metrics.Histogram("request_duration_seconds", "Request latency", nil, "method")

http.Handle("/metrics", metrics.Handler())

Components

Component	What it does
SetupTracer	Initializes an OpenTelemetry tracer provider with OTLP gRPC exporter, sets it as the global provider.
StartSpan	Convenience wrapper that starts a span using the global tracer provider.
Metrics	Factory for creating Prometheus metrics with consistent namespace/subsystem naming.
TracerConfig	Configures the tracer: service name, version, OTLP endpoint, sampling ratio.
MetricsConfig	Configures the metrics factory: namespace and subsystem.

Tracing

SetupTracer creates an OTLP gRPC exporter, builds a tracer provider with batched span export and ratio-based sampling, and registers it as the global otel.TracerProvider. Returns a shutdown function that must be called on application exit.

shutdown, err := obsx.SetupTracer(ctx, obsx.TracerConfig{
    ServiceName: "orders-api",
    Endpoint:    "jaeger:4317",
    Sampler:     0.1, // sample 10%
})
defer shutdown(ctx)

Start spans with the convenience helper:

ctx, span := obsx.StartSpan(ctx, "process-order")
defer span.End()

Metrics

NewMetrics creates a fresh Prometheus registry (isolated from the global default) pre-loaded with process and Go runtime collectors. All metrics created through the factory inherit the configured namespace and subsystem.

m := obsx.NewMetrics(obsx.MetricsConfig{Namespace: "myapp", Subsystem: "db"})

// Counter
queries := m.Counter("queries_total", "Total queries executed", "operation")
queries.WithLabelValues("select").Inc()

// Histogram (nil buckets = prometheus.DefBuckets)
latency := m.Histogram("query_duration_seconds", "Query latency", nil, "operation")

// Gauge
conns := m.Gauge("connections_active", "Active connections", "pool")

// HTTP handler for /metrics endpoint
http.Handle("/metrics", m.Handler())

Access the underlying registry directly:

registry := m.Registry()

Requirements

Go 1.24+, OpenTelemetry Go, Prometheus client_golang.