obsx/CLAUDE.md

CLAUDE.md — obsx

Commands

go build ./...                          # compile
go test ./...                           # all tests
go test -race ./...                     # tests with race detector
go test -v -run TestName ./...          # single test
go vet ./...                            # static analysis

Architecture

• Module: git.codelab.vc/pkg/obsx, Go 1.24, depends on OpenTelemetry and Prometheus client_golang
• Single package obsx

Core patterns

• SetupTracer — creates OTLP gRPC exporter, builds sdktrace.TracerProvider with batcher and ratio sampler, sets it as global otel.TracerProvider
• StartSpan — convenience function using otel.Tracer("obsx") to start spans via the global provider
• TracerConfig — service name, version, OTLP endpoint, sampling ratio; defaults() sets Sampler to 1.0 if unset
• Metrics — factory that creates Prometheus CounterVec, HistogramVec, GaugeVec with consistent namespace/subsystem
• NewMetrics — creates an isolated prometheus.Registry pre-loaded with process and Go collectors
• Handler() — returns promhttp.HandlerFor using the isolated registry
• Registry() — exposes the underlying *prometheus.Registry for direct access

Tracer lifecycle

• SetupTracer returns shutdown func(context.Context) error — must be called to flush pending spans
• Shutdown is the TracerProvider.Shutdown method directly

Conventions

• Struct-based configs (TracerConfig, MetricsConfig) with defaults() methods
• Isolated Prometheus registry — not the global default, avoids conflicts in tests and multi-tenant setups
• nil buckets in Histogram() defaults to prometheus.DefBuckets
• No functional options — direct struct configuration only

See also

• AGENTS.md — universal AI agent guide with package map and common tasks