Add obsx library

CLAUDE.md

@@ -0,0 +1,42 @@
+# 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.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