Rene Nochebuena
ed4e9ef161
Single-call OTel SDK bootstrap setting all three global providers (traces → Tempo, metrics → Mimir, logs → Loki) over OTLP gRPC. What's included: - New(ctx, Config): bootstraps TracerProvider, MeterProvider, and LoggerProvider with OTLP gRPC exporters; sets OTel globals - W3C TraceContext + Baggage propagation set globally - Resource tagging: service.name, service.version, deployment.environment merged with SDK defaults - OTLPInsecure bool for development environments without TLS - Sequential rollback on partial initialization failure — no dangling exporters on error - Returns shutdown func(context.Context) error; caller defers in main or wires into launcher BeforeStop - Tier 5 module: must be imported only by application main packages; zero micro-lib dependencies Tested-via: todo-api POC integration Reviewed-against: docs/adr/
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)
}
}()