Claude Code Monitoring: How to Track Token Usage, Errors, and Latency in Production

Claude Code is becoming the default coding agent for engineering teams shipping AI-powered features, but most teams ship it to production with zero observability. This guide shows you exactly what to monitor, how to instrument your agents in under 10 minutes, and how the major observability platforms compare for Claude-specific workloads.

Why Claude Code Monitoring Is Different From Generic LLM Logging

Most LLM observability tools were built for single-shot completions: send a prompt, log the response, calculate cost. Claude Code agents break that model entirely. A single `claude` CLI invocation can spawn 40+ tool calls, read dozens of files, branch into subagents, and consume between 5,000 and 200,000 tokens depending on the task.

Generic dashboards collapse under that complexity. You end up looking at a flat list of API calls with no idea which ones belong to which agent run, which subagent triggered them, or whether the 87,000-token spike at 3:14 AM was a runaway loop or legitimate work.

Claude Code monitoring needs to track:

• Per-session token usage including input, output, cache reads, and cache writes (the four pricing dimensions of Claude's API)
• Tool call traces — which tools fired, in what order, with what arguments
• Subagent hierarchy — Claude Code spawns subagents via the Task tool, and these need to nest under the parent run
• Cache hit ratio — a healthy Claude Code workload reads from cache 70-90% of the time; if you drop below 50%, your bill triples
• Latency by tool — Bash and Edit tools dominate latency in most coding agents, not the model itself

If your monitoring stack doesn't expose all of these, you're flying blind. ClawPulse was built specifically for agent observability, but the principles below apply regardless of which tool you use.

The Four Metrics That Actually Matter

After instrumenting hundreds of Claude Code deployments, four metrics consistently predict production incidents before they happen.

1. Cache Read Ratio

Claude's prompt caching cuts input costs by 90% (from $3/MTok to $0.30/MTok on Sonnet 4.6). A well-tuned Claude Code agent should hit cache on 70-90% of input tokens. When this drops, it's almost always because:

• A non-deterministic field (timestamp, UUID, random user ID) was injected near the top of the system prompt
• The CLAUDE.md or memory files were modified mid-session, invalidating the cache
• The user is on a fresh session with no warm cache yet

Track `cache_read_input_tokens / (cache_read_input_tokens + cache_creation_input_tokens + input_tokens)` and alert when it falls below 0.5 for more than 10 minutes.

2. Tokens Per Resolved Task

A Claude Code task that fixes a typo should cost ~5,000 tokens. A task that refactors a service should cost ~80,000 tokens. When your average climbs above 150,000 tokens per task, you have a runaway loop problem — usually an agent re-reading the same files because it forgot what it found three turns ago.

3. Tool Call Latency P95

The model itself is rarely the bottleneck. Bash commands hitting slow test suites, Edit tools blocked on large file reads, and WebFetch calls timing out are what kill perceived performance. Break out latency by tool name, not by overall request.

4. Error Rate by Error Class

Group errors into four buckets: `rate_limit`, `context_overflow`, `tool_validation`, and `model_refusal`. A spike in any single class points to a different root cause and a different fix.

Instrumenting Claude Code in 10 Minutes

Here's the minimum viable instrumentation for a Python-based agent that wraps the Anthropic SDK directly. The same pattern works whether you're using the official SDK or the Claude Code CLI.

```python

import time

import anthropic

from clawpulse import ClawPulse

cp = ClawPulse(api_key="cp_live_...")

client = anthropic.Anthropic()

def run_agent(task: str, session_id: str):

trace = cp.start_trace(

name="claude-code-session",

session_id=session_id,

metadata={"task": task[:200]}

)

start = time.time()

response = client.messages.create(

model="claude-sonnet-4-6",

max_tokens=8192,

system=[{

"type": "text",

"text": SYSTEM_PROMPT,

"cache_control": {"type": "ephemeral"}

}],

messages=[{"role": "user", "content": task}],

tools=TOOLS,

)

trace.log(

latency_ms=int((time.time() - start) * 1000),

input_tokens=response.usage.input_tokens,

output_tokens=response.usage.output_tokens,

cache_read_tokens=response.usage.cache_read_input_tokens,

cache_creation_tokens=response.usage.cache_creation_input_tokens,

stop_reason=response.stop_reason,

)

return response

```

For the Claude Code CLI specifically, hook into the `Stop` and `PostToolUse` events via settings.json hooks. This captures every tool call without modifying agent code:

```json

{

"hooks": {

"PostToolUse": [{

"matcher": "*",

"hooks": [{

"type": "command",

"command": "curl -X POST https://api.clawpulse.org/v1/events -d @-"

}]

}]

}

}

```

The hook receives a JSON payload with `tool_name`, `tool_input`, `tool_response`, and timing data on stdin. Pipe it into any HTTP endpoint.