88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# AGENTS.md — obsx
|
|
|
|
Universal guide for AI coding agents working with this codebase.
|
|
|
|
## Overview
|
|
|
|
`git.codelab.vc/pkg/obsx` is a Go observability library providing Prometheus metrics and OpenTelemetry tracing setup with consistent defaults and isolated registries.
|
|
|
|
## Package map
|
|
|
|
```
|
|
obsx/ Root — tracing, metrics, config
|
|
├── doc.go Package documentation
|
|
├── tracer.go SetupTracer, StartSpan, TracerConfig
|
|
├── metrics.go Metrics factory, NewMetrics, Counter/Histogram/Gauge, Handler
|
|
└── config.go (empty — configs are co-located with their components)
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌──────────────────────┐
|
|
│ obsx │
|
|
└──────────┬───────────┘
|
|
│
|
|
┌───────────────┴───────────────┐
|
|
│ │
|
|
┌──────┴──────┐ ┌──────┴──────┐
|
|
│ Tracing │ │ Metrics │
|
|
└──────┬──────┘ └──────┬──────┘
|
|
│ │
|
|
SetupTracer() NewMetrics()
|
|
│ │
|
|
▼ ▼
|
|
OTLP gRPC exporter prometheus.Registry
|
|
TracerProvider (process + Go collectors)
|
|
(global via otel.Set) │
|
|
│ Counter / Histogram / Gauge
|
|
▼ │
|
|
StartSpan() Handler() → /metrics
|
|
```
|
|
|
|
## Common tasks
|
|
|
|
### Add a new metric type (e.g., Summary)
|
|
|
|
1. Add a method to `Metrics` struct in `metrics.go`
|
|
2. Create the Prometheus collector with `m.cfg.Namespace` / `m.cfg.Subsystem`
|
|
3. Register via `m.registry.MustRegister()`
|
|
4. Return the collector
|
|
|
|
### Change the trace exporter (e.g., HTTP instead of gRPC)
|
|
|
|
1. Replace `otlptracegrpc.New` in `SetupTracer` with the desired exporter
|
|
2. Update `TracerConfig` fields if the new exporter needs different options
|
|
3. Keep the same return signature (`shutdown func(context.Context) error`)
|
|
|
|
### Add custom resource attributes to traces
|
|
|
|
1. Append additional `resource.WithAttributes(...)` options to the `attrs` slice in `SetupTracer`
|
|
2. Use `semconv` constants where possible
|
|
|
|
## Gotchas
|
|
|
|
- **SetupTracer sets the global provider**: calling it multiple times overwrites the previous provider; the old provider is not shut down automatically
|
|
- **Isolated registry**: `NewMetrics` creates its own `prometheus.Registry`, not the global default. Metrics registered here will not appear in `promhttp.Handler()` — use `m.Handler()` instead
|
|
- **Sampler default**: if `TracerConfig.Sampler` is 0 or negative, it defaults to 1.0 (sample everything), not 0
|
|
- **Insecure gRPC**: `SetupTracer` always uses `otlptracegrpc.WithInsecure()` — no TLS for the OTLP endpoint
|
|
- **StartSpan tracer name**: uses the hardcoded tracer name `"obsx"` — all spans created via this helper share the same instrumentation scope
|
|
|
|
## 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
|
|
```
|
|
|
|
## Conventions
|
|
|
|
- **Struct-based Config** with `defaults()` method for zero-value defaults
|
|
- **Isolated Prometheus registry** — each `Metrics` instance has its own registry
|
|
- **stdlib only** testing — no testify, no gomock
|
|
- **No functional options** — direct struct configuration
|
|
- **Shutdown function** — `SetupTracer` returns a shutdown callback, caller is responsible for calling it
|