Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
176 lines
5.8 KiB
Markdown
176 lines
5.8 KiB
Markdown
---
|
|
title: Observability (OpenTelemetry)
|
|
---
|
|
|
|
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.
|