Claude Code Observability: Every Session, Tool Call, and Dollar

Why Trace Claude Code? Lessons From Real Incidents

Claude Code is not autocomplete. It runs in your terminal, reads your repo, runs shell commands, edits files, spawns subagents, and keeps going until the task is done. One prompt can turn into dozens of model calls and tool runs. Three public incidents show why that activity deserves a record. Each one ends with what a trace adds.

1. Malware can drive the agent you installed

On August 26, 2025, malicious releases of the Nx build tool were published to npm. Wiz reported that the payload looked for installed AI coding CLIs, including Claude Code, and ran them with flags such as --dangerously-skip-permissions to search the machine for secrets and wallet files. The stolen data was pushed to public GitHub repositories named s1ngularity-repository.

2. Approval prompts have had bugs

In August 2025, Cymulate disclosed two Claude Code vulnerabilities. CVE-2025-54794 was a path restriction bypass, fixed in 0.2.111. CVE-2025-54795 let a crafted command run without the approval prompt, fixed in 1.0.20. Both needed untrusted content, such as a malicious file, to reach Claude Code's context.

3. Autonomous runs look different from human ones

In November 2025, Anthropic reported a state-sponsored group that used Claude Code as an autonomous orchestrator against about 30 targets, with the AI performing an estimated 80 to 90 percent of the tactical work. Anthropic caught it on its side. On your side, the same pattern shows up as volume: far more tool calls per session than a person at a keyboard produces.

Questions every team should answer

How Claude Code Telemetry Reaches Traccia

Claude Code sends OTLP traces, metrics, and logs to Traccia's ingestion endpoint. Traccia normalizes the claude_code.* spans, stitches prompts into sessions on session.id, and attaches the cost estimate from Claude Code's api_request log events. The result shows up on the Traces page like any other agent.

Setup in Four Steps

Step 1: Create an ingestion key

Sign in at app.traccia.ai, open Settings → API Keys, and create an ingestion key.

Step 2: Configure Claude Code

Add an env block to ~/.claude/settings.json. Over HTTP (protobuf):

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": "https://api.traccia.ai/v2/traces",
    "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "https://api.traccia.ai/v2/metrics",
    "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://api.traccia.ai/v2/logs",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer YOUR_TRACCIA_API_KEY",
    "OTEL_SERVICE_NAME": "claude-code",
    "OTEL_RESOURCE_ATTRIBUTES": "agent.id=claude-code,agent.name=claude-code,env=production"
  }
}

Or over gRPC, with one endpoint for all three signals:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://api.traccia.ai:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer YOUR_TRACCIA_API_KEY",
    "OTEL_SERVICE_NAME": "claude-code",
    "OTEL_RESOURCE_ATTRIBUTES": "agent.id=claude-code,agent.name=claude-code,env=production"
  }
}

Every line matters. Leave out the exporter lines and Claude Code sends nothing, even with telemetry enabled:

Step 3: Run Claude Code

claude

Do real work: read files, run tests, iterate. Telemetry exports every few seconds and flushes when you exit with /exit.

Step 4: Open Traces in Traccia

Each prompt is its own trace under the claude-code agent, with tokens, cost estimate, duration, and outcome.

What Gets Sent, and What Stays Redacted

The setup above sends metadata only. Claude Code redacts the text of your prompts and the details of tool calls unless you opt in. That default is safe for a first rollout, and it is enough for sessions, timelines, tokens, cost, and tool failure rates.

To audit what the agent was asked and which commands it ran, add the first two to the same env block:

{
  "env": {
    "OTEL_LOG_USER_PROMPTS": "1",
    "OTEL_LOG_TOOL_DETAILS": "1"
  }
}

Sessions: One Conversation, One Row

Claude Code gives every conversation a stable session.id. Each new prompt is a new interaction that shares it. Turn on Group by session and the conversation collapses into one row with totals for tokens, duration, and cost. Expand it to see each prompt, or click Open for the session detail page.

This answers "what did this coding session cost?" without adding up traces by hand.

Inside a Trace

Open an interaction to see the summary cards (duration, cost, LLM calls, total tokens, tool calls, status) and the Execution Timeline. The root claude_code.interaction span is the agent turn. claude_code.llm_request spans are model calls. claude_code.tool spans are Bash, Read, Edit, Grep, and subagent runs.

Click any span to open its drawer with model, tokens, cost, and attributes.

A failed tool call does not fail the turn

Say Claude Code runs your tests, pytest exits 1, and it edits the code and runs them again. Traccia keeps the error on the first tool span, adds a Tool retry badge to the interaction, and keeps the outcome as Success. You see how the agent recovered without a false alarm, and the badge is your cue to open the turn.

Under the Hood

Before anything is stored, Traccia's ingestion service runs Claude Code spans through a dedicated normalizer. These excerpts come straight from that code.

Span typing

Each claude_code.* span gets a Traccia span type, and token counts are mapped to standard fields:

if name == "claude_code.llm_request":
    attrs["span.type"] = "llm"
    ...
    input_tokens = _coerce_int(attrs.get("input_tokens") or attrs.get("gen_ai.usage.input_tokens"))
    output_tokens = _coerce_int(attrs.get("output_tokens") or attrs.get("gen_ai.usage.output_tokens"))
    if input_tokens:
        attrs["llm.usage.prompt_tokens"] = input_tokens
    if output_tokens:
        attrs["llm.usage.completion_tokens"] = output_tokens

elif name.startswith("claude_code.tool"):
    attrs["span.type"] = "tool"
    tool_name = attrs.get("tool_name") or attrs.get("tool.name")
    if tool_name:
        attrs["tool.name"] = tool_name

elif name == "claude_code.interaction":
    attrs["span.type"] = "agent"

Subagents stay inside the parent agent

A subagent's tool span carries its own agent_id. Left alone, every subagent run would appear as a new agent in your inventory. Traccia keeps it as metadata instead:

subagent_id = attrs.get("agent_id") or attrs.get("agent.id")
if subagent_id:
    attrs["claude.subagent_id"] = str(subagent_id)
    attrs.pop("agent.id", None)
    attrs.pop("agent_id", None)
parent_agent = attrs.get("parent_agent_id")
if parent_agent:
    attrs["agent.parent_id"] = parent_agent

Honest timelines

Claude Code can leave child spans open until the exporter flushes, which would make a five-second tool call look like a minute. Traccia caps child spans to the interaction window:

def _cap_claude_code_span_ends(payload):
    """Cap child span end times to the interaction window (CC leaves spans open until flush)."""
    ...
    if start and int(start) > cap_ns:
        span["startTimeUnixNano"] = cap_ns
        span["endTimeUnixNano"] = cap_ns
    elif end_ns and int(end_ns) > cap_ns:
        span["endTimeUnixNano"] = cap_ns

Stable agent identity

Model-suffixed IDs like claude-code-minimax collapse to claude-code, while deliberate team splits stay separate:

_TEAM_AGENT_SUFFIXES = frozenset({"backend", "frontend", "infra", "data", "mobile", "web"})

def normalize_agent_id(agent_id):
    """Collapse legacy model-suffixed CC agent ids (e.g. claude-code-minimax) to claude-code."""
    ...
    suffix = agent_id[len("claude-code-"):]
    if suffix in _TEAM_AGENT_SUFFIXES:
        return agent_id
    return "claude-code"

Metrics that fit existing dashboards

def alias_claude_code_metric_name(name: str) -> str:
    """Map CC metric names to gen_ai.client.* for dashboard compatibility."""
    if name.startswith("claude_code."):
        suffix = name[len("claude_code."):]
        return f"gen_ai.client.{suffix}"
    return name

Cost: Claude Code's Own Estimate

For runs against the Anthropic API, Traccia does not re-price tokens. It shows the cost_usd Claude Code reports on each api_request event. Anthropic documents that field as an estimated cost, so treat it as Claude Code's reported cost estimate, not your invoice.

Traccia also labels the figure by where Claude Code is routed:

def _ollama_billing_context(model, resource_attrs):
    if not model_str or _is_anthropic_model(model_str):
        return None
    if ":cloud" in model_str.lower():
        return "ollama_cloud"
    env = str(resource_attrs.get("env") or resource_attrs.get("deployment.environment") or "")
    if env in ("local", "dev"):
        return "ollama_local"
    return None

Peak context vs cumulative tokens. Traccia shows peak context (the largest single request, like /context in Claude Code) separately from cumulative usage (every API call added up). A long session can have high cumulative tokens and a modest peak. Both are correct.

Alert on Claude Code Usage, and What Traccia Does Not Do

After Run policies check traces once they land, so they can watch Claude Code with no change on the developer's machine. Scope each one to the agent ID claude-code, or to your team IDs. Four templates fit well; start from your own baseline before you rely on them:

• Cost Spike Alert. The sum of cost over a window, starting at $100 a day. It sums Claude Code's estimates, and $0 Ollama runs add nothing.
• Tool Storm Alert. Too many tool calls in one run, starting at 25. Long agentic tasks can pass that on their own, so size it for your team.
• Input Token Limit. Average input tokens past a budget, starting at 8,000. Claude Code sends large contexts by design, so raise this to fit.
• Unapproved Model Alert. A run used a model outside your list. The template allows only gpt-4o and gpt-4o-mini, so replace the list with the Claude models your team uses.

On the Review step, run Simulate Last 7 Days to replay the draft against last week's traces and see how many would have matched, then turn on email alerts and activate it.

Rolling Out to a Team

• Push the same env block to every developer with Claude Code managed settings, so nobody has to edit their own file.
• Give each team its own Traccia workspace and a workspace-scoped ingestion key so traces stay isolated.
• Decide on content capture once, in managed settings: metadata only, or with OTEL_LOG_USER_PROMPTS and OTEL_LOG_TOOL_DETAILS for a full audit trail.
• Split profiles with distinct agent IDs:

OTEL_RESOURCE_ATTRIBUTES="agent.id=claude-code-backend,agent.name=claude-code-backend,env=production"

Claude Code log events (tool decisions, API requests, and prompts when you opt in) also feed Traccia's audit pipeline. See the Compliance Hub. For the broader picture, read What Is AI Agent Observability?

Troubleshooting Claude Code Tracing

Frequently Asked Questions