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 "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))

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

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