Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.
Coding-Agents Telemetry Convention
This is the strict contract between every coding-agent vendor and OpenLit. Every adapter, every native-telemetry mapping, every query has to match it exactly. Drift in either direction (renaming an attribute, switching units, adding ad-hoc vendor-namespaced keys) breaks the /coding-agents and /agents views in subtle, hard-to-diagnose ways. When in doubt, prefer this document over what any individual vendor's docs claim.
The companion authoring guide is coding-agents-hook.md (failure modes + checklist). This guide is the schema.
1. Canonical schema (single source of truth)
Everything OpenLit reads or rolls up speaks one of two namespaces:
coding_agent.*— OpenLit-owned, defined insdk/go/semconv/coding_agent.go(Go) andcli/gen/semconv.ts(TS mirror). Specific to coding agents — no other product surface uses these.gen_ai.*— OpenTelemetry GenAI semantic conventions (with a few OpenLit-stamped additions insdk/go/semconv/genai.go). Shared with the SDK / LLM observability surface.
Hard rules:
- Adapters MUST stamp
coding_agent.session.idon every span. No exceptions. - Adapters MUST stamp
coding_agent.client(vendor identifier) on every span. Allowed values:cursor,claude-code,codex,opencode,windsurf. Add new values tosdk/go/semconv/coding_agent.goANDsrc/client/src/types/agents.tsAND re-rungo generate. gen_ai.systemMUST be the LLM provider, not the agent vendor:anthropic,openai,google,xai,mistral. Use theinferProvider(model, vendor)helper.- Numeric attributes are emitted as numbers, NEVER as strings. Tokens are
int64. Cost isfloat64in USD. Duration isint64in milliseconds. - Timestamps are RFC3339-with-nanos when stamped as strings, or the OTel span's intrinsic start/end when stamped as span time. NEVER unix seconds, never milliseconds-since-epoch.
- Enums (capture mode, outcome, edit decision, classification) MUST be exactly one of the defined values. Use the
semconv.CodingAgent*constants — never inline a literal.
2. Attribute matrix — what every adapter MUST set
These keys MUST land on every adapter's spans. Where the value is unknown, leave the key off — DO NOT stamp "" or "unknown" (the only exception is coding_agent.user.classification = "unknown", which is a deliberate fallback).
Resource attributes (every span the process emits)
| Attribute | Source | Required | Example |
|---|---|---|---|
coding_agent.client |
Vendor adapter | ✅ | claude-code |
coding_agent.session.id |
Vendor payload | ✅ | UUID string |
coding_agent.agent.parent_id |
Subagent linkage | When subagent | UUID string |
coding_agent.content_capture_mode |
CLI config | ✅ | minimal / metadata_only / full |
coding_agent.hook.cli.version |
CLI build | ✅ | 0.5.3 |
coding_agent.signal_source |
Adapter (see §6) | ✅ | hook / native |
telemetry.distro.name |
CLI emit layer | ✅ | openlit-cli |
telemetry.distro.version |
CLI emit layer | ✅ | 0.5.3 |
code.cwd |
Session probe + os.Getwd() fallback |
✅ | /home/me/repo |
vcs.repository.url.full |
git.Snapshot(cwd) |
When repo | https://github.com/org/repo |
vcs.ref.head.name |
git.Snapshot(cwd) |
When repo | main |
gen_ai.user.name |
Vendor payload or local OS user | ✅ | [email protected] |
gen_ai.request.user |
Mirror of gen_ai.user.name |
✅ | Same as above |
gen_ai.conversation.id |
Vendor's chat-thread id | When known | UUID string |
terminal.type |
resolveTerminalType() |
When known | iTerm.app / vscode / tmux |
host.name |
os.Hostname() |
✅ | alice-mbp |
service.name |
Vendor identifier | ✅ | claude-code |
service.version |
CLI version | ✅ | 0.5.3 |
telemetry.sdk.name |
openlit-go default | ✅ | opentelemetry |
Span attributes per span type
Session-root span (coding_agent.session, only on session END):
| Attribute | Required | Notes |
|---|---|---|
coding_agent.session.outcome |
✅ | One of the CodingAgentSessionOutcome* constants |
coding_agent.session.duration_ms |
✅ | int64, wall-clock |
coding_agent.session.cost_usd |
When known | float64, USD |
coding_agent.session.tool_call_count |
✅ | int64 |
coding_agent.session.subagent_count |
When subagents | int64 |
coding_agent.session.lines.added |
When edits captured | int64. Sum of coding_agent.edit.lines.added across the session's edit-decision spans (any decision). |
coding_agent.session.lines.removed |
When edits captured | int64. Sum of coding_agent.edit.lines.removed across edit-decision spans. |
coding_agent.session.lines.accepted |
When edits captured | int64. Sum of coding_agent.edit.lines.added for edit-decision spans where coding_agent.edit.decision IN ('accept', 'auto_accepted'). |
coding_agent.session.lines.rejected |
When edits captured | int64. Same shape as lines.accepted but for decision = 'reject'. |
coding_agent.session.edit.accept_count |
When edits captured | int64. Count of edit-decision spans with decision = accept / auto_accepted. |
coding_agent.session.edit.reject_count |
When edits captured | int64. Count of edit-decision spans with decision = reject. |
coding_agent.session.commit_count |
When commits detected | int64. Count of coding_agent.git.commit spans the adapter emitted for this session. |
coding_agent.session.pr_count |
When PRs detected | int64. Count of coding_agent.git.pull_request spans. |
gen_ai.usage.input_tokens |
When known | int64 |
gen_ai.usage.output_tokens |
When known | int64 |
gen_ai.usage.total_tokens |
When known | int64 |
gen_ai.usage.cache.read_input_tokens |
When known | int64 |
gen_ai.usage.cache.creation_input_tokens |
When known | int64 |
gen_ai.request.model |
When known | Vendor model string |
coding_agent.user.classification |
✅ | work / personal / unknown |
coding_agent.user.classification.reason |
✅ | Human-readable reason |
coding_agent.policy.permission_mode |
When set | Vendor permission mode |
coding_agent.vcs.dirty |
When repo present | Boolean |
The eight coding_agent.session.{lines,edit,commit,pr}* rollup
attributes are an additive fast path — they let the per-session
listSessions query render code-impact without scanning every
coding_agent.edit.decision / coding_agent.git.* child span.
For sessions where the rollup is missing (Codex never emits a
SessionEnd; in-flight CC / Cursor sessions also lack the rollup),
the query layer falls back to per-event aggregation with the
greatest(rollup, sum) pattern documented in queries.ts.
Non-terminal session snapshot spans (coding_agent.session.snapshot.start, coding_agent.session.snapshot):
These are the narrow exception for a vendor such as OpenCode that has no true session-end signal. They are allowed only in minimal capture mode. The start snapshot establishes visibility; each idle snapshot carries per-snapshot token/cost deltas and cumulative duration/tool-call count. Readers sum the deltas and take the numeric maximum of cumulative values. A snapshot MUST NOT carry coding_agent.session.outcome and MUST NOT be treated as a terminal coding_agent.session root.
LLM turn span (coding_agent.llm.turn):
| Attribute | Required | Notes |
|---|---|---|
gen_ai.operation.name |
✅ | chat |
gen_ai.system |
✅ | Provider — anthropic, openai, ... |
gen_ai.request.model |
✅ | Model string |
gen_ai.response.model |
When known | Often equal to request |
gen_ai.usage.input_tokens |
When known | int64 |
gen_ai.usage.output_tokens |
When known | int64 |
gen_ai.usage.reasoning_tokens |
When known | int64 |
gen_ai.usage.total_tokens |
When known | int64 |
gen_ai.usage.cost |
When known | float64, USD |
gen_ai.response.id |
When known | Vendor request id |
gen_ai.response.finish_reasons |
When known | String array — [end_turn], [tool_use], etc. |
gen_ai.input.messages |
Capture-mode full |
JSON-stringified messages |
gen_ai.output.messages |
Capture-mode full |
JSON-stringified messages |
coding_agent.llm.thought.text |
Capture-mode full |
Reasoning / extended-thinking text |
coding_agent.llm.thought.duration_ms |
When known | int64 |
coding_agent.llm.turn.kind |
✅ | prompt / response / thought |
Tool call span (coding_agent.tool.call):
| Attribute | Required | Notes |
|---|---|---|
gen_ai.tool.name |
✅ | Vendor's tool name |
gen_ai.tool.call.id |
✅ | Vendor's tool_use_id |
coding_agent.tool.duration_ms |
✅ | int64 |
coding_agent.tool.errored |
✅ | Boolean |
coding_agent.tool.error_message |
When errored, gated | String — only in full mode |
coding_agent.tool.iteration |
When known | int64, 1-based |
coding_agent.tool.group.id |
When known | Vendor's tool-group id |
coding_agent.tool.triggering_llm_request_id |
When known | LLM turn id that issued the call |
coding_agent.mcp.server.name |
MCP tools only | String |
coding_agent.mcp.scope |
MCP tools only | user / project / local |
coding_agent.mcp.transport |
MCP tools only | stdio / sse / http |
coding_agent.tool.sandboxed |
When known | Boolean |
coding_agent.tool.command |
Shell tools, gated | metadata_only+ strips args, full keeps full string |
gen_ai.tool.call.arguments |
Capture-mode full |
JSON-stringified args |
gen_ai.tool.call.result |
Capture-mode full |
JSON-stringified result |
Edit decision span (coding_agent.edit.decision):
| Attribute | Required | Notes |
|---|---|---|
coding_agent.edit.decision |
✅ | accept / reject / auto_accept / revert |
coding_agent.edit.decision.source |
✅ | user_interactive / policy / hook |
coding_agent.edit.tool.name |
✅ | Vendor's edit tool name (Edit, Write, MultiEdit, …) |
coding_agent.edit.language |
When known | Programming language guess |
coding_agent.edit.lines.added |
When known | int64 |
coding_agent.edit.lines.removed |
When known | int64 |
code.file.path |
When known | Repo-relative path |
Subagent span (coding_agent.subagent):
| Attribute | Required | Notes |
|---|---|---|
coding_agent.subagent.type |
✅ | Vendor's subagent type label |
coding_agent.agent.parent_id |
✅ | Parent chat id (also as resource attr) |
gen_ai.tool.call.id |
When spawned by Task tool | Tool use id that spawned it |
Git commit span (coding_agent.git.commit):
Detected by parsing git commit invocations out of the Bash /
shell / local_shell tool's command + stdout (see
cli/internal/coding/detect/detect.go).
| Attribute | Required | Notes |
|---|---|---|
coding_agent.git.commit.sha |
When stdout has it | Hex SHA from git commit stdout. Gated by capture mode (stripped in metadata_only). |
coding_agent.git.commit.message |
When command has it | First line of -m '…'. Gated. |
coding_agent.tool.name |
✅ | Originating tool — Bash, local_shell, shell. |
coding_agent.tool.working_dir |
When known | Repo cwd. |
Git pull-request span (coding_agent.git.pull_request):
Detected by parsing gh pr create / gh pr new invocations.
| Attribute | Required | Notes |
|---|---|---|
coding_agent.git.pr.url |
When stdout has it | PR URL from gh pr stdout. Gated. |
coding_agent.git.pr.number |
When URL has it | Numeric ID parsed out of the URL. |
coding_agent.git.pr.title |
When command has it | --title '…'. Gated. |
coding_agent.tool.name |
✅ | Originating tool — Bash, local_shell, shell. |
coding_agent.tool.working_dir |
When known | Repo cwd. |
3. Inbound mapping — Cursor → canonical
Cursor sends payloads to our hook subcommand; we own the mapping. For full reference see cli/internal/coding/hook/cursor/handle.go.
| Cursor payload key | Canonical attribute | Notes |
|---|---|---|
session_id |
coding_agent.session.id |
|
conversation_id |
gen_ai.conversation.id |
|
parent_conversation_id |
coding_agent.agent.parent_id |
resource attribute |
user_email |
gen_ai.user.name + gen_ai.request.user |
resource attribute, cached |
cwd / workspace_roots[0] |
code.cwd |
resource attribute, cached |
composer_mode |
coding_agent.policy.permission_mode |
resource attribute |
model |
gen_ai.request.model |
|
cursor_version |
coding_agent.client.version |
not always present |
is_background_agent / is_parallel_worker |
coding_agent.session.is_subagent |
boolean string |
prompt |
gen_ai.input.messages |
full mode only |
text (assistant response) |
gen_ai.output.messages |
full mode only |
text (thought) |
coding_agent.llm.thought.text |
full mode only |
duration_ms |
coding_agent.llm.thought.duration_ms |
for thoughts |
input_tokens / output_tokens / cache_*_tokens (on stop) |
gen_ai.usage.*_tokens |
Real counters only; stamp on stop + drain to session root at sessionEnd. Never invent from text. Cursor does not send USD — leave cost unset. |
tool_name |
gen_ai.tool.name |
|
tool_use_id |
gen_ai.tool.call.id |
|
tool_input |
gen_ai.tool.call.arguments |
full mode only |
tool_response |
gen_ai.tool.call.result |
full mode only |
attachments[].file_path |
coding_agent.llm.turn.attachment.paths |
array |
4. Inbound mapping — Claude Code → canonical
Claude Code has two telemetry paths:
- Path A (Hook) — our CLI plugin sits in
~/.claude/plugins/openlit-cc/and is invoked on every PreToolUse / PostToolUse / SessionStart / SessionEnd / UserPromptSubmit / Stop / SubagentStop hook event. We emitcoding_agent.*spans the same way we do for Cursor. - Path B (Native) — Claude Code's
CLAUDE_CODE_ENABLE_TELEMETRY=1makes Claude Code itself emit OTel metrics + events + (withCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1) spans, all underclaude_code.*andservice.name=claude-code.
OpenLit accepts both. The query layer coalesces. The hard rule on attribute mapping:
Path A: hook adapter (cli/internal/coding/hook/claudecode/handle.go)
| Claude Code hook payload key | Canonical attribute | Notes |
|---|---|---|
session_id |
coding_agent.session.id |
|
transcript_path |
claude_code.transcript.path (extras) |
so we can re-tail in the UI later |
cwd |
code.cwd |
resource attribute, cached |
hook_event_name |
coding_agent.hook.event |
|
permission_mode |
coding_agent.policy.permission_mode |
resource attribute |
tool_name |
gen_ai.tool.name |
|
tool_use_id |
gen_ai.tool.call.id |
|
tool_input |
gen_ai.tool.call.arguments |
full mode only |
tool_response |
gen_ai.tool.call.result |
full mode only |
source (SessionStart) |
claude_code.session.source (extras) |
startup / resume / continue |
reason (SessionEnd) |
maps to outcome enum (see §7) | |
| Transcript tail (last N KB) | session token + cost totals | bounded by tailfile.Tail |
The hook adapter MUST stamp coding_agent.signal_source = "hook" on every span it emits.
Path B: native Claude Code telemetry
Claude Code emits its own OTel signals with service.name = "claude-code". We accept it raw. The query layer coalesces both schemas. For symmetry, the canonical equivalents are:
| Claude Code native attribute | Canonical attribute | Notes |
|---|---|---|
session.id |
coding_agent.session.id |
also: OTEL_METRICS_INCLUDE_SESSION_ID=1 |
app.version |
coding_agent.client.version |
enable with OTEL_METRICS_INCLUDE_VERSION=1 |
user.email |
gen_ai.user.name + gen_ai.request.user |
resource-level |
user.account_uuid |
not mapped — kept as Anthropic identifier | |
organization.id |
mapped to gen_ai.organization.id if set |
for org filtering |
terminal.type |
terminal.type |
already aligned |
model (cost metric) |
gen_ai.request.model |
|
claude_code.cost.usage (metric) |
coding_agent.session.cost_usd (on session span) |
metric-to-attribute mapped at query time |
claude_code.token.usage (metric, by type) |
gen_ai.usage.input_tokens / output_tokens / cache.read_input_tokens / cache.creation_input_tokens |
|
claude_code.session.count (metric) |
session count rollup | derived |
claude_code.lines_of_code.count (metric) |
coding_agent.edit.lines.added / removed |
summed per session |
claude_code.commit.count (metric) |
derived UI counter | no canonical attr — gen_ai.user.commit_count? Out of scope for v1. |
claude_code.pull_request.count (metric) |
derived UI counter | same |
claude_code.active_time.total (metric) |
coding_agent.session.active_time_seconds (future) |
not yet wired |
claude_code.user_prompt event |
coding_agent.llm.turn span, kind=prompt |
|
claude_code.tool_result event |
coding_agent.tool.call span |
|
claude_code.api_request event |
coding_agent.llm.turn span, kind=response |
carries cost/tokens |
claude_code.api_error event |
coding_agent.llm.turn span, errored=true |
|
claude_code.tool_decision event |
coding_agent.edit.decision span when tool ∈ {Edit, Write, NotebookEdit, MultiEdit} |
otherwise dropped |
claude_code.permission_mode_changed event |
coding_agent.session.permission_mode_changed event |
|
claude_code.compaction event |
coding_agent.session.loop.compact event |
|
claude_code.api_retries_exhausted event |
coding_agent.llm.turn.retry_exhausted event |
|
claude_code.mcp_server_connection event |
coding_agent.mcp.connection event |
|
claude_code.skill_activated event |
coding_agent.skill.activated event |
|
claude_code.plugin_loaded / plugin_installed event |
dropped at v1 | not modelled |
claude_code.auth event |
dropped at v1 | not relevant to coding-agent analytics |
claude_code.feedback_survey event |
dropped at v1 | |
claude_code.internal_error event |
dropped at v1 | not user-actionable |
Native spans (when traces beta is on) are accepted as-is and joined into our model via the inbound coalesce in the query layer (§5). We do NOT rewrite spans at the collector.
The native path's signal_source is native. We infer this in the query layer:
multiIf(
SpanAttributes['coding_agent.signal_source'] = 'hook', 'hook',
ResourceAttributes['coding_agent.signal_source'] = 'hook', 'hook',
SpanName LIKE 'claude_code.%' OR ResourceAttributes['service.name'] = 'claude-code', 'native',
ResourceAttributes['service.name'] = 'cursor' AND mapContains(ResourceAttributes, 'coding_agent.session.id'), 'hook',
''
) AS signal_source
5. Query-layer coalesce — the dual-path rule
When both paths are active for the same Claude Code session, we get two writers landing telemetry under the same session.id. We dedupe at read time:
Session-level rollup (cost, tokens, model)
authoritative_cost = coalesce(
native sum(claude_code.cost.usage),
hook session.cost_usd -- from transcript-tail estimate
)
authoritative_tokens = coalesce(
native sum(claude_code.token.usage),
hook session.{input,output}_tokens
)
model = coalesce(
native gen_ai.request.model (from claude_code.api_request),
hook gen_ai.request.model (from transcript tail)
)
Native always wins when present. Anthropic counts tokens authoritatively from the API response; our hook estimates from a bounded transcript tail. Both estimates may exist for the same session — coalesce(native, hook) picks the truthful one.
Identity (user, cwd, repo)
Hook always wins. The native path doesn't see the developer's repo or cwd; it only sees what Claude Code chose to expose. Our hook stamps code.cwd, vcs.repository.url.full, vcs.ref.head.name as resource attributes from git.Snapshot(cwd).
Tool calls
Coalesce by gen_ai.tool.call.id:
- If both paths emitted for the same tool call: keep the native span (it has authoritative duration, retry count, MCP scope) but enrich it with
code.cwd+vcs.*from the hook session's resource bundle. - If only one side emitted: keep that one as-is.
Edit decisions
Hook always wins — the hook sees the actual file diff context; native only sees the decision and language.
Anti-double-count rule
session_count, tool_call_count, and subagent_count are rolled up per session.id, never per span. As long as the chat_id rollup folds both paths into the same chat_id, we don't double-count. The materializer's discovery query (discoverCodingAgents) already does this — confirm with:
SELECT
coalesce(
nullIf(ResourceAttributes['coding_agent.agent.parent_id'], ''),
nullIf(SpanAttributes['coding_agent.agent.parent_id'], ''),
SpanAttributes['coding_agent.session.id'],
SpanAttributes['session.id'] -- Claude Code native
) AS chat_id,
count() AS spans, uniqExact(coalesce(...)) AS distinct_sessions
FROM otel_traces
WHERE Timestamp >= now() - INTERVAL 24 HOUR
GROUP BY chat_id;
If distinct_sessions > 1 for one chat_id, we have a dedupe leak. Fix by widening the coalesce in CHAT_ID_EXPR.
Is coalesce good enough at scale?
Honest answer:
- Under ~1M spans/day per tenant: coalesce in queries is fine. ClickHouse evaluates the per-row coalesce in a few milliseconds; the query bottleneck is usually the wider session scan, not the attribute lookup.
- Over ~1M spans/day per tenant: we want a materialized view (
coding_agent_sessions) that normalizesclaude_code.*andcoding_agent.*into one canonical row at ingest time. The view exists as a comment marker inqueries.ts(the E1 deferral note). When we ship it, the change is single-file: pointOTEL_TRACES_TABLEat the MV; the chat-id rollup logic stays the same.
Until then, every new attribute MUST be added to the coalesce expression in queries.ts so reads still work for both paths.
6. The coding_agent.signal_source marker
Every span MUST carry this attribute (resource-level, set by the adapter or inferred from service.name at query time). Values:
| Value | When |
|---|---|
hook |
OpenLit CLI emitted this span from a vendor hook event |
native |
The vendor's own OTel exporter emitted this span (e.g. Claude Code with CLAUDE_CODE_ENABLE_TELEMETRY=1) |
sdk |
A regular OpenLit Go/Python SDK process (NOT a coding agent) |
Adapters MUST stamp hook explicitly. The query layer infers native from service.name = 'claude-code' AND absence of coding_agent.signal_source. The materializer's SDK discovery excludes anything that isn't sdk (a positive value of hook or native keeps the row off the SDK side).
7. Outcome enum mapping
Both vendors map onto the same six-value enum from sdk/go/semconv/coding_agent.go:
| Outcome | When (Cursor) | When (Claude Code hook) | When (Claude Code native) |
|---|---|---|---|
completed |
outcome=completed on sessionEnd |
n/a (no equivalent signal) | n/a |
merged |
(no signal yet) | (no signal yet) | (no signal yet) |
committed |
(no signal yet) | (no signal yet) | (no signal yet) |
abandoned_no_change |
outcome=abandoned AND !vcs.dirty |
SessionEnd reason in [exit, logout] AND !vcs.dirty |
SessionEnd metric AND no recent commit AND clean tree |
abandoned_with_change |
outcome=abandoned AND vcs.dirty |
SessionEnd reason in [exit, logout] AND vcs.dirty |
SessionEnd metric AND dirty tree |
cancelled |
outcome=cancelled |
SessionEnd reason=clear |
(no signal yet) |
Never invent a new outcome value. Never leave outcome empty on a session-root span.
8. Capture-mode contract
Three modes apply identically across vendors. The matrix in coding-agents-hook.md §4 governs which attributes are allowed in each mode. Vendors do not get to widen capture beyond the global setting.
Special note on bodies:
gen_ai.input.messages/gen_ai.output.messages/gen_ai.tool.call.arguments/gen_ai.tool.call.result/coding_agent.llm.thought.text/coding_agent.tool.command(full command) are body-bearing. They MUST be gated bybodyAllowed(mode)fromcli/internal/otlp/attrs.go. Adapters that bypass this gate are bugs.
When Claude Code is configured to send native OTEL_LOG_RAW_API_BODIES, those bodies arrive under claude_code.api_request_body.body / claude_code.api_response_body.body. The query layer drops them in minimal and metadata_only modes via a WHERE filter — we trust the deployer's CLI config over what the vendor's native exporter chose to send.
9. Identity / privacy guardrails
These guardrails are absolute. No vendor adapter and no native-telemetry mapping may relax them.
- Cohort floor. Per-user breakdowns suppress users with fewer than
COHORT_K_FLOOR(default 5) sessions in the working window, unless the viewer is an admin. Apply this at query time inqueries.ts, NEVER in the materializer. - Email visibility.
gen_ai.user.nameis the developer's email when OAuth is configured. It MUST be queryable for admins and MUST be masked behind the cohort floor for non-admins. - Dispute trail. Classification labels can be disputed via
POST /api/coding-agents/classification/dispute. Disputed sessions are flagged but not deleted. Never re-classify a disputed session automatically — defer to the human reviewer. - Body retention. When
OPENLIT_CODING_CONTENT_CAPTURE != "full", no prompt body / tool result / file diff may land inotel_traces. The collector does not redact post-hoc; the adapter MUST gate at emit time. - Cross-account leakage. The
whereScopehelper inqueries.tsenforcesorganization.idmatching whenOPENLIT_REQUIRE_ORG_FILTERis set. New queries MUST go throughwhereScope.
10. Adding a new vendor (worked example: opencode)
If we add OpenCode (or any other vendor):
- semconv — add the vendor identifier to
sdk/go/semconv/coding_agent.go's vendor list AND tosrc/client/src/types/agents.ts'sCodingAgentVendorunion. Rungo generate ./cli/...to regeneratecli/gen/semconv.ts. - Adapter — create
cli/internal/coding/hook/opencode/handle.go. Mirror the structure ofcursor/handle.goorclaudecode/handle.go. Map every payload key to the canonical attribute matrix in §2 — DO NOT introduce a newopencode.*namespace for facts that already have a canonical key. peekContext—cli/internal/coding/hook/hook.go. Add the vendor's payload key names topickString. The function MUST resolvesession_id,user,cwd,permission_mode,model, and (when applicable)parent_conversation_idfrom this vendor's payload format.- Plugin manifest —
plugins/opencode/. Keep the distributable source in sync with the embedded installer copy. The plugin invokesopenlit coding hook --vendor=opencode --event=<EventName>with a strictly projected payload. - Native telemetry mapping — if the vendor ships its own OTel signals, write §4's equivalent for it. Add the inbound coalesce to
queries.tsand document the dual-path rules. - Icon — add a tiny inline SVG component to
src/client/src/components/svg/coding-agents.tsxand wirecase "opencode":intoCodingAgentVendorIcon. The hard-coded=== "cursor"checks incoding-agents-table.tsx,signal-records.tsx, andtrace-detail-page.tsxshould be replaced with a "ask the icon component, fall back to Bot" pattern so new vendors pick up icons automatically. - Onboarding doc —
docs/latest/openlit/coding-agents/setup-and-configure.mdx. Add a tab for the vendor. - Sanity check — run one session end to end (or through the vendor's strongest available lifecycle boundary), then run the verification SQL in
coding-agents-hook.md§9.
11. Things the convention WILL bite you on
These are the rules that, when violated, make the UI silently render 0 / blank / wrong:
- Stamping cost as a string (
"0.15"instead of0.15). The UI's(row.cost ?? 0).toFixed(2)returns"NaN"and we render$NaN. - Stamping cost in cents (
15for $0.15). Multiplies the dashboard total by 100. - Stamping
gen_ai.system = "claude-code". The provider rollup over-counts Anthropic + misses correct provider attribution. Useanthropic. - Stamping
coding_agent.session.outcome = "". The session-list query filters on outcome being one of the enum values; empty becomes "unknown" in the UI but breaks DORA-style queries. - Forgetting to stamp
coding_agent.signal_sourceANDtelemetry.distro.name = "openlit-cli". The materializer's SDK discovery picks the spans up as SDK telemetry and the agent detail page flips between layouts on refresh. Both stamps are mandatory and live incli/internal/otlp/exporter.go. Seecoding-agents-hook.md§10 for the full three-barrier exclusion chain. - Adding a vendor-namespaced attribute (
claude_code.foo) that duplicates a canonical attribute (coding_agent.foo). The query layer reads canonical, the row will look empty even though the data is there. - Inventing new outcome / decision / classification values. The UI checks are explicit enum comparisons; new values render as blank.
- Stamping ResourceAttributes with
service.name = "openlit-cli". Use the vendor identifier so the materializer's coding discovery picks it up. (Theopenlit-clivalue goes ontelemetry.distro.name, not onservice.name.) ORDER BY agent_keydedup trap.openlit_agents_summaryis aReplacingMergeTree(updated_at) ORDER BY agent_key. Once a phantom row exists for the same agent_key but a differentsourcevalue, FINAL picks whichever has the higherupdated_at— which can flip back and forth across materialize ticks. The mitigation lives at the write side (three barriers indiscoverAgents, see hook rule §10); the long-term schema fix is widening the ORDER BY to(agent_key, source)so SDK and coding rows can coexist for the same service.
12. Documented limitations (vendor data doesn't let us fold)
These are known limits where the data the vendor sends prevents perfect rollup. Do not pretend they're fixed; surface them to the operator instead.
- Cursor: no stable chat-thread id across CLI processes. When the user suspends a chat (laptop sleep, IDE restart) and resumes, Cursor spawns a fresh CLI process with a fresh
session_idAND a freshconversation_id. There is no field in the hook payload that links the new session to the previous one. Result: one user-perceived chat shows as N sessions in the OpenLit UI. The chat rollup is doing the right thing per the data it received; the limitation is upstream. Possible future fixes (in order of robustness): Cursor adds acomposer_thread_idfield to the payload, OR we read Cursor's local SQLite at~/Library/Application Support/Cursor/User/globalStorage/state.vscdbto map session_id → thread_id (version-fragile, not recommended without coordination with Cursor). - Claude Code: no
cwd/repoin native OTel telemetry. The native exporter only knows what Claude Code itself sees. When the user runs Claude Code outside a Git repo, or whenCLAUDE_PROJECT_DIRisn't set, those resource attributes will be empty even in the dual-path scenario. - OpenCode: no terminal session-end event.
session.idlefires at run-loop boundaries and may follow errors or cancellation, whilesession.deletedmeans persisted conversation deletion rather than successful completion. The adapter therefore leaves outcome unknown instead of fabricating success. Minimal capture uses the non-terminal snapshot contract above; metadata/full retain ordinary child and lifecycle spans. A session row can keep updating whenever the conversation resumes.
When in doubt: grep for the canonical attribute name in queries.ts and materialize.ts. If a reader doesn't already coalesce your new key, your data will be invisible to the UI no matter how cleanly it lands in ClickHouse.