beads/docs/reference/observability.md
Chris Sells 69e33099b8 docs: apply PR #4722 review feedback to user docs
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
  IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
  correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
  body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
  route spaces (1.0.0, 1.0.4, 1.0.5)
2026-07-12 11:06:57 -07:00

177 lines
6 KiB
Markdown

---
title: Observability (OpenTelemetry)
description: Exporting bd metrics and traces over OpenTelemetry (OTLP), with a local VictoriaMetrics and Grafana stack, env vars, and a metric reference.
---
Beads exports metrics via OTLP HTTP. Telemetry is **disabled by default** — zero overhead when no variable is set.
## Recommended local stack
| Service | Port | Role |
|---------|------|------|
| VictoriaMetrics | 8428 | OTLP metrics storage |
| VictoriaLogs | 9428 | Reserved for future OTLP log storage |
| Grafana | 9429 | Dashboards |
```bash
# From your personal stack's opentelemetry/ folder
docker compose up -d
```
## Configuration
One variable is enough. Add it to your shell profile or workspace `.env`:
```bash
export BD_OTEL_METRICS_URL=http://localhost:8428/opentelemetry/api/v1/push
```
Every `bd` command will then automatically push its metrics.
Log export is not implemented yet. `BD_OTEL_LOGS_URL` is reserved for a future
VictoriaLogs exporter and does not activate telemetry today.
### Shell profile (recommended)
```bash
# ~/.zshrc or ~/.bashrc
export BD_OTEL_METRICS_URL=http://localhost:8428/opentelemetry/api/v1/push
```
### Environment variables
| Variable | Example | Description |
|----------|---------|-------------|
| `BD_OTEL_METRICS_URL` | `http://localhost:8428/opentelemetry/api/v1/push` | Push metrics to VictoriaMetrics. Activates telemetry. |
| `BD_OTEL_LOGS_URL` | `http://localhost:9428/insert/opentelemetry/v1/logs` | Reserved for future log export. Does not activate telemetry today. |
| `BD_OTEL_STDOUT` | `true` | Write spans and metrics to stderr (dev/debug). Also activates telemetry. |
### Local debug mode
```bash
BD_OTEL_STDOUT=true bd list
```
## Verification
```bash
bd list # triggers metrics → visible in VictoriaMetrics
```
Verification query in Grafana (VictoriaMetrics datasource):
```promql
bd_storage_operations_total
```
### Confirm storage instrumentation locally
To verify the storage decorator chain is wired up without standing up a
collector, run `bd` with stdout exporters and look for `bd.storage.*`
records on stderr:
```bash
BD_OTEL_STDOUT=true bd list 2>&1 | grep -F bd.storage.operations
```
Expect at least one line per storage call (`GetReadyWork`, `GetIssue`, …).
If `bd.storage.*` and `bd.issue.count` are absent but `bd.db.pool_*` is
present, the storage decorator is not in the chain — check
`wireStorageDecorators` in `cmd/bd/storage_chain.go`.
---
## Metrics
### Storage (`bd_storage_*`)
| Metric | Type | Attributes | Description |
|--------|------|------------|-------------|
| `bd_storage_operations_total` | Counter | `db.operation` | Storage operations executed |
| `bd_storage_operation_duration_ms` | Histogram | `db.operation` | Operation duration (ms) |
| `bd_storage_errors_total` | Counter | `db.operation` | Storage errors |
> These metrics are emitted by `InstrumentedStorage`, the beads SDK wrapper.
### Dolt database (`bd_db_*`)
| Metric | Type | Attributes | Description |
|--------|------|------------|-------------|
| `bd_db_retry_count_total` | Counter | — | SQL retries in server mode |
| `bd_db_lock_wait_ms` | Histogram | `dolt_lock_exclusive` | Wait time to acquire database locks |
### Issues (`bd_issue_*`)
| Metric | Type | Attributes | Description |
|--------|------|------------|-------------|
| `bd_issue_count` | Gauge | `status` | Number of issues by status |
`status` values: `open`, `in_progress`, `closed`, `deferred`.
### AI (`bd_ai_*`)
| Metric | Type | Attributes | Description |
|--------|------|------------|-------------|
| `bd_ai_input_tokens_total` | Counter | `bd_ai_model` | Anthropic input tokens |
| `bd_ai_output_tokens_total` | Counter | `bd_ai_model` | Anthropic output tokens |
| `bd_ai_request_duration_ms` | Histogram | `bd_ai_model` | API call latency |
---
## Traces (spans)
Spans are only exported when `BD_OTEL_STDOUT=true` — there is no trace backend in the recommended local stack.
| Span | Source | Description |
|------|--------|-------------|
| `bd.command.<name>` | CLI | Total duration of the command |
| `dolt.exec` / `dolt.query` / `dolt.query_row` | SQL | Each SQL operation |
| `dolt.commit` / `dolt.push` / `dolt.pull` / `dolt.merge` | Dolt VC | Version control procedures |
| `ephemeral.count` / `ephemeral.nuke` | SQLite | Ephemeral store operations |
| `hook.exec` | Hooks | Hook execution (root span, fire-and-forget) |
| `tracker.sync` / `tracker.pull` / `tracker.push` | Sync | Tracker sync phases |
| `anthropic.messages.new` | AI | Claude API calls |
### Notable attributes
**`bd.command.<name>`**
| Attribute | Description |
|-----------|-------------|
| `bd.command` | Subcommand name (`list`, `create`, ...) |
| `bd.version` | bd version |
| `bd.args` | Raw arguments passed to the command (e.g. "create 'title' -p 2") |
| `bd.actor` | Actor (resolved from git config / env) |
**`hook.exec`**
| Attribute / Event | Description |
|-------------------|-------------|
| `hook.event` | Event type (`create`, `update`, `close`) |
| `hook.path` | Absolute path to the script |
| `bd.issue_id` | ID of the triggering issue |
| event `hook.stdout` | Script standard output (truncated to 1 024 bytes) |
| event `hook.stderr` | Script error output (truncated to 1 024 bytes) |
The `hook.stdout` / `hook.stderr` events carry two attributes: `output` (the text) and `bytes` (original size before truncation).
---
## Architecture
```
cmd/bd/main.go
└─ telemetry.Init()
├─ BD_OTEL_STDOUT=true → TracerProvider stdout + MeterProvider stdout
└─ BD_OTEL_METRICS_URL → MeterProvider HTTP → VictoriaMetrics
internal/storage/dolt/ → bd_db_* metrics + dolt.* spans
internal/storage/ephemeral/ → ephemeral.* spans
internal/hooks/ → hook.exec span
internal/tracker/ → tracker.* spans
internal/compact/ → bd_ai_* metrics + anthropic.* spans
internal/telemetry/storage.go → bd_storage_* metrics (SDK wrapper)
```
When neither variable is set, `telemetry.Init()` installs **no-op** providers:
hot paths execute only no-op calls with no memory allocation.