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/
71 lines
2.3 KiB
Markdown
71 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```go
|
|
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.
|
|
|
|
```go
|
|
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)
|
|
}
|
|
}()
|
|
```
|