telemetry

OTel SDK bootstrap — wires up TracerProvider, MeterProvider, and LoggerProvider with OTLP gRPC exporters pointed at Grafana Alloy (→ Tempo / Mimir / Loki).

Tier 5 — import only from application main packages. Never import from framework libraries.

Why Tier 5

Micro-libs use only the OTel API (go.opentelemetry.io/otel) which ships a zero-overhead no-op default. This module activates the real SDK and sets the three OTel globals, so all micro-libs using the global API auto-instrument without knowing about this module.

Installation

require code.nochebuena.dev/go/telemetry v0.1.0

Usage

func main() {
    ctx := context.Background()

    // Bootstrap telemetry before any other component.
    shutdown, err := telemetry.New(ctx, telemetry.Config{
        ServiceName:  "order-service",
        OTLPEndpoint: "alloy:4317",
        OTLPInsecure: true, // dev only
    })
    if err != nil {
        log.Fatalf("telemetry: %v", err)
    }
    defer shutdown(ctx)

    // Start the rest of the application…
}

Config

Field	Env var	Required	Default	Description
ServiceName	OTEL_SERVICE_NAME	✓	—	Service name in traces/metrics/logs
ServiceVersion	OTEL_SERVICE_VERSION		unknown	Deployed version
Environment	OTEL_ENVIRONMENT		development	Deployment environment
OTLPEndpoint	OTEL_EXPORTER_OTLP_ENDPOINT	✓	—	OTLP gRPC address (e.g. alloy:4317)
OTLPInsecure	OTEL_EXPORTER_OTLP_INSECURE		false	Disable TLS (dev only)

What New sets up

Signal	SDK	Exporter	Backend
Traces	sdktrace.TracerProvider	OTLP gRPC	Grafana Alloy → Tempo
Metrics	sdkmetric.MeterProvider	OTLP gRPC	Grafana Alloy → Mimir
Logs	sdklog.LoggerProvider	OTLP gRPC	Grafana Alloy → Loki

Also sets otel.SetTextMapPropagator with W3C TraceContext + Baggage.

Shutdown

The returned func(context.Context) error flushes all pending telemetry and shuts down the three providers. Always call it before process exit.

defer func() {
    shutCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    if err := shutdown(shutCtx); err != nil {
        log.Printf("telemetry shutdown: %v", err)
    }
}()