# CLAUDE.md — obsx

## Commands

```bash
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.25.7, 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