otelsetup/CLAUDE.md

# otelsetup

Shared Go library for OpenTelemetry setup across all microservices.

## Shared Documentation

@../docs/claude/architecture.md
@../docs/claude/go-services.md
@../docs/claude/conventions.md

## Library Information

### Purpose

Provides standardized OpenTelemetry configuration for tracing, metrics, and logging. Used by all Go microservices to enable observability.

### Usage

```go
import "gitea.unbound.se/shiny/otelsetup"

// Bootstrap OpenTelemetry SDK
shutdown, err := otelsetup.SetupOTelSDK(ctx, enabled, serviceName, buildVersion, environment)
if err != nil {
    log.Fatal(err)
}
defer shutdown(ctx)

// Wrap HTTP handlers with tracing
http.Handle("/", otelsetup.Handler(myHandler))

// gqlgen server hooks
srv.AroundOperations(otelsetup.AroundOperations)
srv.AroundRootFields(otelsetup.AroundRootFields)
srv.AroundFields(otelsetup.AroundFields)
srv.SetRecoverFunc(otelsetup.Recover)
```

### Features

- **Tracing** - OTLP HTTP exporter with batch processing
- **Metrics** - OTLP HTTP exporter with periodic reader
- **Logging** - Stdout log exporter
- **Propagation** - TraceContext and Baggage propagation
- **HTTP Handler** - Middleware for automatic span creation
- **gqlgen hooks** - Spans per operation, root field and resolver field
- **gqlgen recover** - `Recover` logs a resolver panic as one ERROR record via `slog.Default()` (attributes `panic`, `stack`, `path`), records it on the active span with status Error, and returns the generic "internal system error" to the client (gqlgen's default prints the stack to stderr line by line)

### Environment Variables

- `OTEL_RESOURCE_ATTRIBUTES` - Auto-set if not provided (service.name, service.version, service.environment)
- Standard OTLP environment variables for endpoint configuration
- The trace and metric exporters use our own HTTP client (idle connections closed after 30s, before the collector's 1m idle timeout), so `OTEL_EXPORTER_OTLP_*TIMEOUT` and the `OTEL_EXPORTER_OTLP_*CERTIFICATE` / `*CLIENT_*` TLS variables are ignored