Signals¶

All three signals derive from the same unified model. internal/attr owns every name below and is the single source of truth; the dashboard generator validates its queries against it.

OTLP-to-Prometheus translation replaces dots with underscores and adds counter and unit suffixes. Query the translated names, not the dotted ones.

Where a field is allowed to go¶

A field's destination is a property of the field. Nothing from AttrRecord or Content may become a metric attribute, and that is the only cardinality rule.

Specifically never a metric attribute: session.id, turn.id, response.id, call.id, trace.id, cwd, file paths, command text, git branch, agent thread id, instructions hash.

Bounded and therefore allowed: codingagent.tool (claude-code | codex), namespace, gen_ai.request.model, effort, entrypoint, thread_source, permission_mode, sandbox_mode, approval_policy, tool.name, item.kind, outcome, stop_reason, exit_class, codingagent.repo (allowlisted, other overflow), codingagent.machine, codingagent.duration_source.

Metric namespace¶

Everything is under codingagent.. Never emit under claude_code. or any vendor prefix: those belong to the clients' own exporters and a collision makes both unreadable.

Native OTel overlap¶

Both CLIs already export OTLP to the same collector. Do not emit a second series with the same meaning under a different name. The table was checked against the m7kni Mimir and Loki tenants at 2026-09-22T12:05:13Z: its quoted Mimir results use a 30-day range because an instant-vector absence only means that a series is stale at that instant.

Every metric point has the bounded codingagent.backfill dimension: false for the normal tail and true for a ranged historical run. It keeps a backfill's overlap window queryable instead of silently adding it to native live data. The bounded-run wiring must construct the metric sink with otlpmetric.Config{Backfill: true}.

Dashboard preference¶

Use claude_code_cost_usage_USD_total, claude_code_token_usage_tokens_total, and claude_code_lines_of_code_count_total for live Claude cost, token totals, and lines of code. Use the service metrics for Codex and transcript-only decomposition; select codingagent_backfill="true" when intentionally plotting historical backfill. Never add a native Claude series to the corresponding codingagent series without first separating the backfill range.

Metrics¶

Every dimensions cell below also includes codingagent.backfill; it is omitted where redundant.

Turns and responses¶

codingagent.duration_source is mandatory on every duration instrument. Claude Code has no measured TTFT; a derived value must never be emitted into codingagent.ttft.

Tokens and cost¶

codingagent.cost_usd is a gauge because cost-state is cumulative for the session. Summing it across records multiplies one session's cost by however many times it was observed.

gen_ai.token.type values are input, output, reasoning, cache_read, cache_write. The last three are breakdowns of the first two and must not be added to their parents. Claude's ephemeral_1h / ephemeral_5m split rides as cache_ttl on codingagent.tokens only.

Tools and items¶

exit_class is ok, error, signal, timeout, absent - never the raw exit code, which is unbounded. The raw code is an AttrRecord field.

Agents¶

Agent names and paths are unbounded and are AttrRecord fields, not dimensions.

Compaction and limits¶

Code churn¶

repo comes from the repo_allowlist mapping of cwd. cwd itself never appears.

Self-observability¶

Log records¶

One record per content kind, gated by logs.record_types. Every record carries AttrRecord identifiers as OTLP log attributes, which land as structured metadata rather than indexed labels.

Listing only turn, session, error, compaction and subagent gives an event timeline with no bodies. Empty means all of them.

Timestamps: an input-side record (prompt, tool result, file change) takes the input timestamp; a model-side record (message, tool call) takes the output timestamp. Ties sort by ordinal.

Spans¶

session
└── turn                        (Codex: native trace_id; Claude: derived from session id)
    ├── response                (model call)
    ├── tool_call               (linked to tool_result by call id)
    ├── file_change
    ├── compaction
    └── subagent turn           (child thread, linked by agent thread id)

Every span carries codingagent.duration_source. Codex spans have real boundaries from item_completed. Claude spans are bounded by record write times and are approximate; do not put an SLO on one.

codingagent.trace_id_source is native or derived.