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

import "git.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