Observability (OpenTelemetry)

Beads exports metrics via OTLP HTTP. Telemetry is disabled by default — zero overhead when no variable is set.

Recommended local stack

# From your personal stack's opentelemetry/ folder
docker compose up -d

Configuration

Telemetry is explicit opt-in. Set BD_OTEL_ENABLED=true and configure the exporter via standard OpenTelemetry SDK environment variables — both go in your shell profile or workspace .env:

export BD_OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:8428/opentelemetry/api/v1/push

A standard OTEL_* variable alone will not turn bd telemetry on — bd won't auto-activate from a machine-global OTEL_* setting that was set for some other instrumented tool.

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_ENABLED=true
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:8428/opentelemetry/api/v1/push

Environment variables

Resource attributes

Every metric and span carries the OTel resource describing the bd process:

Add anything else via OTEL_RESOURCE_ATTRIBUTES.

Local debug mode

BD_OTEL_ENABLED=true OTEL_TRACES_EXPORTER=console OTEL_METRICS_EXPORTER=console bd list

Legacy environment variables (deprecated)

The earlier BD_OTEL_* data variables are honored for backwards compatibility. Setting any of them activates telemetry on its own (no BD_OTEL_ENABLED=true required) and translates to the standard OTLP equivalent — a legacy value wins over a pre-existing OTEL_* value so a machine-global OTEL_* setting cannot silently redirect bd telemetry. Each bd invocation that sees one logs a one-line deprecation warning to stderr:

Verification

bd list   # triggers metrics → visible in VictoriaMetrics

Verification queries in Grafana (VictoriaMetrics datasource):

bd_storage_operations_total                              # raw counter
sum(rate(bd_storage_operations_total[5m]))               # operation rate

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_*)

These metrics are emitted by InstrumentedStorage, the beads SDK wrapper.

Dolt database (bd_db_*)

Issues (bd_issue_*)

status values: open, in_progress, closed, deferred.

AI (bd_ai_*)

Traces (spans)

Spans are only exported when OTEL_TRACES_EXPORTER=console — there is no trace backend in the recommended local stack.

Notable attributes

bd.command.<name>

hook.exec

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()
      ├─ OTEL_TRACES_EXPORTER=console        → TracerProvider stdout
      ├─ OTEL_METRICS_EXPORTER=console       → MeterProvider stdout
      └─ OTEL_EXPORTER_OTLP_METRICS_ENDPOINT → 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 no OpenTelemetry SDK environment variable selects an exporter, telemetry.Init() installs no-op providers: hot paths execute only no-op calls with no memory allocation.