Aleksey Shakhmatov
362267470e
All checks were successful
CI / test (push) Successful in 54s
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
43 lines
1.9 KiB
Markdown
43 lines
1.9 KiB
Markdown
# 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
|