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/.
5.8 KiB
| 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 |
# 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:
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)
# ~/.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
BD_OTEL_STDOUT=true bd list
Verification
bd list # triggers metrics → visible in VictoriaMetrics
Verification query in Grafana (VictoriaMetrics datasource):
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:
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.