OpenTelemetry Data Model

Last reviewed: 2026-08-07

Freshness source: internal/telemetry/, internal/storage/dolt/store.go, internal/compact/haiku.go, cmd/bd/find_duplicates.go, and hook execution code under internal/hooks/.

Complete schema of all telemetry events emitted by Beads. Each event consists of:

1. Span (→ stdout/console only, when OTEL_TRACES_EXPORTER=console; the legacy BD_OTEL_STDOUT=true translates to that — no remote/OTLP trace backend is wired) with full structured attributes
2. Metric counter/histogram (→ any OTLP v1.x+ backend, defaults to VictoriaMetrics) for aggregation

Telemetry is hard opt-in: nothing is emitted unless BD_OTEL_ENABLED=true is set (a legacy BD_OTEL_* variable also activates it); standard OTEL_* variables on their own do not.

All command spans automatically carry bd.command, bd.version, bd.args from startup context; bd.actor is added after actor resolution.

Metric Naming Convention

OTel SDK names use dot notation internally. Prometheus-compatible backends (VictoriaMetrics, Prometheus) export these as underscore-separated names, appending type suffixes:

Event Index

1. Identity Hierarchy

1.1 Instance

The outermost grouping. Derived at command startup time from the machine hostname and the working directory.

1.2 Command

Each bd command execution generates a span with full context.

2. CLI Command Events

bd.command.<name>

Emitted once per bd subcommand execution. Anchors all subsequent events for that command. The span name is bd.command. + command name (e.g. bd.command.create).

3. Storage Events

Every storage.DoltStorage method AND every issueops role method is instrumented: the facade wave's role decorators in internal/telemetry/ emit storage.<Method> and storage.<Role>.<Method> spans (e.g. storage.IssueReader.Ready, storage.ReadyClaimer.ClaimNext, storage.Sweeper.Sweep), all feeding the same bd.storage.* metrics with db.operation as the label. The tables below are representative examples, not an exhaustive enumeration.

storage.CreateIssue

Emitted when an issue is created.

storage.UpdateIssue

Emitted when an issue is updated.

storage.GetIssue

Emitted when an issue is retrieved.

storage.SearchIssues

Emitted when searching for issues.

storage.GetReadyWork

Emitted when querying for ready work.

storage.GetBlockedIssues

Emitted when querying for blocked issues.

storage.RunInTransaction

Emitted when executing a transaction.

Naming rule and complete inventory

Every storage span is named storage. + the operation name, and carries that same bare name in the db.operation attribute (internal/telemetry/storage.go, InstrumentedStorage.op). The sections above detail the highest-traffic spans; the rest follow the identical shape, so they are inventoried here rather than repeated.

There are two families.

Direct storage operations — storage.<Method>, one per storage method (72 spans):

AddDependency AddIssueComment AddLabel CloseIssue CloseIssueChecked
CountDependencies CountDependents CountEvents CountIssueComments CountIssues
CountIssuesByGroup CreateIssue CreateIssues DeleteIssue GetAllConfig
GetAllEventsSince GetBlockedIssues GetConfig GetDependencies
GetDependenciesWithMetadata GetDependencyTree GetDependents
GetDependentsWithMetadata GetEpicsEligibleForClosure GetEvents GetIssue
GetIssueByExternalRef GetIssueComments GetIssueCommentsPage GetIssuesByIDs
GetIssuesByLabel GetLabels GetLocalMetadata GetProvenanceByRef
GetProvenanceEvents GetReadyWork GetReadyWorkWithCounts GetStatistics
IterAllEventsSince IterBlockedIssues IterDependenciesWithMetadata
IterDependentsWithMetadata IterEvents IterIssueComments IterIssues
IterReadyWork IterWisps ListWisps MergeMetadata MergeSlotAcquire
MergeSlotCheck MergeSlotCreate MergeSlotRelease RecordProvenanceEvent
RemoveDependency RemoveLabel ReopenIssue RunInIssueLifecycleTransaction
RunInTransaction SearchIssueIDs SearchIssues SearchIssuesWithCounts SetConfig
SetLocalMetadata SlotClear SlotGet SlotSet UnclaimIssue UnclaimIssueIfAssignee
UpdateIssue UpdateIssueChecked UpdateIssueType

Issueops role operations — storage.<Role>.<Method>, emitted when a caller goes through the guarded issueops surface instead of calling storage directly (39 spans):

BatchCloser.CloseBatch BatchCreator.CreateBatch
BlockingAnnotator.AnnotateBlocking Bootstrapper.Bootstrap Commenter.AddComment
Counter.Count Counter.CountByGroup CycleDetector.DetectCycles Deleter.Delete
DependencyEditor.AddDependencies DependencyEditor.RemoveDependency
EdgeReader.ReadEdges InitVerifier.VerifyIdentity IssueClaimer.Claim
IssueOperations.Close IssueOperations.Create IssueOperations.Reopen
IssueOperations.Update IssueReader.Get IssueReader.List IssueReader.Ready
IssueRelations.Related Memories.Forget Memories.List Memories.Recall
Memories.Remember Querier.Query ReadyClaimer.ClaimNext ReadyCounter.CountReady
StatsReporter.AssigneeStats StatsReporter.Stats Sweeper.Sweep
TreeWalker.WalkTree VersionReconciler.ReconcileVersion
VersionReconciler.RecordedVersion WorkspaceConfig.GetSetting
WorkspaceConfig.ListSettings WorkspaceConfig.SetSetting
WorkspaceConfig.UnsetSetting

The two families do not double-count. The role decorators wrap the uninstrumented store (InstrumentedStorage.IssueLifecycle calls Unwrap() before wrapping), so one logical operation through the issueops front door emits its role span only — not a second storage.<Method> span beneath it. A create via issueops is one storage.IssueOperations.Create; a create via direct storage is one storage.CreateIssue. Counters and duration histograms are therefore comparable across both paths.

4. Dolt Backend Events

Shared attributes: every dolt.* SQL span carries the fixed attribute set from doltSpanAttrs() — db.system (string, "dolt"), db.readonly (bool, whether the store is read-only), and db.server_mode (bool, currently always true). The tables below list only each span's additional attributes.

dolt.query

Emitted for each SQL read query via queryContext().

dolt.exec

Emitted for each SQL write statement via execContext().

dolt.query_row

Emitted for single-row queries via queryRowContext().

dolt.commit

Emitted for DOLT_COMMIT operations. Carries only the shared doltSpanAttrs() (see the note at the top of this section) — the commit message no longer appears on this span. It survives only as db.commit_msg on the storage.RunInTransaction / storage.RunInIssueLifecycleTransaction spans (internal/telemetry/storage.go:556,564).

dolt.push

Emitted for DOLT_PUSH operations. The span name is dolt.push, or dolt.force_push for force pushes.

dolt.pull

Emitted for DOLT_PULL operations.

dolt.merge

Emitted for DOLT_MERGE operations.

dolt.merge_with_strategy

Emitted for bd vc merge --strategy merges (pinned-connection merge/resolve/commit sequence).

dolt.branch

Emitted for DOLT_BRANCH operations.

dolt.checkout

Emitted for DOLT_CHECKOUT operations.

5. Dolt Server Events (Roadmap — not yet implemented)

internal/doltserver/ has no OTel imports. The events below are planned for Tier 1.

doltserver.start (planned)

doltserver.stop (planned)

6. Hooks Events

hook.exec

Emitted for hook execution. Span only — no metric counters or histograms exist for hooks. Duration aggregation is a Tier 3 roadmap item.

Stdout/stderr are added as span events (not attributes):

• hook.stdout event: output (string, truncated), bytes (int, original size)
• hook.stderr event: output (string, truncated), bytes (int, original size)

7. AI Events

Emitted by the compaction engine (bd compact) via internal/compact/haiku.go, and by duplicate detection (bd find-duplicates --method ai) via cmd/bd/find_duplicates.go. Both use the Anthropic SDK with Anthropic-compatible credentials from ANTHROPIC_API_KEY, MINIMAX_API_KEY, or ai.api_key.

Note: Only compact/haiku.go records to the bd.ai.* OTel metric instruments. find_duplicates.go records token counts and duration as span attributes only.

anthropic.messages.new

One span per Anthropic API call. The bd.ai.operation attribute distinguishes the two callers.

Retry policy (compact only; find_duplicates makes a single unretried call): exponential backoff, up to 4 attempts (1 initial + up to 3 retries, maxRetries = 3), on HTTP 429, 5xx, and network timeout errors.

8. Metrics Reference

9. Recommended Indexed Attributes

host, os, bd.command, bd.version, bd.actor, db.operation, db.statement,
bd.issue.id, bd.issue.type, hook.event, hook.path, bd.ai.model, bd.ai.operation

10. Configuration and Backend

Environment variables, backend compatibility, Dolt system tables, and roadmap are documented in otel-architecture.md to avoid duplication.

Key variables: BD_OTEL_ENABLED=true (master switch) plus the standard SDK vars — OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_TRACES_EXPORTER/OTEL_METRICS_EXPORTER=console, OTEL_SDK_DISABLED. The legacy BD_OTEL_METRICS_URL/BD_OTEL_LOGS_URL/BD_OTEL_STDOUT trio is deprecated but still honored: each is translated to its OTEL_* equivalent with a stderr deprecation warning (commit 1cf7490c7, #3859).

Appendix: Source Reference Audit

Audited against main @ 5eb7c25dd. All line numbers below refer to that commit.

Every metric name, span name, and attribute listed in this document is backed by a specific source location. This table exists to prevent documentation drift and to make re-verification straightforward after code changes.

Metrics (internal/telemetry/storage.go, internal/storage/dolt/store.go, internal/compact/haiku.go)

Spans and attributes