telemetry/CLAUDE.md

# telemetry

Bootstraps the full OpenTelemetry SDK (traces, metrics, logs) with OTLP gRPC exporters targeting Grafana Alloy.

## Purpose

Sets the three OTel global providers so that all micro-libs using the OTel global API auto-instrument without any code changes. Returns a shutdown function that flushes all exporters on process exit. This module is the single place in an application where the OTel SDK is wired up.

## Tier & Dependencies

**Tier 5** (application bootstrap only). Must never be imported by framework libraries (Tier 0–4).

Depends on:
- `go.opentelemetry.io/otel` and sub-packages — API and SDK
- `go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc`
- `go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc`
- `go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc`
- `go.opentelemetry.io/otel/sdk/trace`, `.../metric`, `.../log`

No micro-lib dependencies. No `launcher` dependency — telemetry has no Component lifecycle.

## Key Design Decisions

- **Tier 5 / app-only** (ADR-001): Libraries use only the OTel API (no-op default). This module activates the real SDK. Importing it from a library is a mistake.
- **Three-signal OTLP bootstrap** (ADR-002): `New(ctx, cfg)` sets up traces → Tempo, metrics → Mimir, logs → Loki, all over a single OTLP gRPC endpoint. W3C TraceContext + Baggage propagation is set globally.
- **Global provider strategy** (ADR-003): Libraries call `otel.Tracer(...)` / `otel.Meter(...)` / `global.Logger(...)`. After `telemetry.New`, those calls route to the real SDK with no library changes required.
- **No `launcher.Component`**: Telemetry is not a lifecycle component. The caller defers the returned shutdown function directly in `main`. This keeps the module dependency graph minimal and the interface simple.
- **Sequential error rollback**: If any exporter fails to initialize, all previously created providers are shut down before the error is returned. The process never runs with a partial telemetry state.

## Patterns

**Standard application usage:**

```go
func main() {
    ctx := context.Background()
    shutdown, err := telemetry.New(ctx, telemetry.Config{
        ServiceName:    "order-service",
        ServiceVersion: "1.4.2",
        Environment:    "production",
        OTLPEndpoint:   "alloy:4317",
        OTLPInsecure:   false,
    })
    if err != nil {
        log.Fatalf("telemetry: %v", err)
    }
    defer shutdown(ctx)

    // Rest of application wiring...
}
```

**With launcher (wire shutdown into lifecycle):**

```go
shutdown, err := telemetry.New(ctx, cfg)
if err != nil {
    return err
}
lc.BeforeStop(func() error { return shutdown(ctx) })
```

**Config env vars:**

| Variable | Required | Default | Description |
|---|---|---|---|
| `OTEL_SERVICE_NAME` | yes | — | Service name in all signals |
| `OTEL_SERVICE_VERSION` | no | `unknown` | Deployed version |
| `OTEL_ENVIRONMENT` | no | `development` | Deployment environment |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | yes | — | OTLP gRPC collector address (e.g. `alloy:4317`) |
| `OTEL_EXPORTER_OTLP_INSECURE` | no | `false` | Disable TLS (set `true` for local dev) |

## What to Avoid

- Do not import this module from any non-`main` package. Libraries must use only OTel API packages.
- Do not call `telemetry.New` more than once per process. Each call overwrites the global providers.
- Do not omit the `defer shutdown(ctx)`. Without it, buffered spans and metrics are lost on exit.
- Do not use a zero-value `Config`. Both `ServiceName` and `OTLPEndpoint` are required; `New` will return an error if the OTLP connection cannot be established.
- Do not wrap this in a `launcher.Component`. The shutdown function pattern is simpler and avoids adding a `launcher` dependency to this module.

## Testing Notes

- The test file (`telemetry_test.go`) uses a `fakeCollector` that opens a TCP listener but speaks no gRPC protocol. This is sufficient to test that `New` succeeds and returns a callable shutdown function — the fake server accepts connections so the gRPC dial does not get connection-refused.
- Tests that verify global provider replacement (`TestNew_SetsGlobalTracerProvider`, `TestNew_SetsGlobalMeterProvider`) must call `shutdown` in a `t.Cleanup` to restore state for subsequent tests. The short shutdown timeout (200ms) is intentional — the fake server cannot complete a gRPC flush, so errors from `shutdown(ctx)` are expected and ignored.
- `newResource` is tested separately (`TestNewResource_Fields`, `TestNewResource_MergesWithDefault`) as a pure function with no I/O.
- Do not test against a real Alloy or Tempo instance in unit tests. Use the fake collector pattern.