Claude Code Observability: Track Tokens, Cost, and Usage per Developer

What observability means for a coding agent

Traditional observability asks whether a service is up. A coding agent is always “up” — it runs on a laptop and talks to a model provider. The question that matters is economic and behavioural: which developer spent what, on which model, doing what, and why did one session cost ten times another. That is token accounting, not health checking, and it is the lens this guide uses. For the billing side of the same coin, see Claude Code Pricing Explained.

The stakes are concrete. A single active developer runs roughly $13 per active day and $150–250 per month, with about 90% of users under $30/day — so the exceptions matter enormously. Without a per-developer view you cannot find the three people in a team of thirty driving most of the invoice, or tell whether they are doing hard work or leaving Opus on by default. Observability turns a surprising total into a list of fixable causes.

What to actually track

Seven signals carry almost all the value. Everything else is derived from them.

Two of these — the model mix and the cache ratio — are also your biggest cost levers, which is why observing them pays for itself. The routing side is covered in Opus vs Sonnet vs Haiku: a cost-vs-capability routing guide, and the caching side in Claude prompt caching: the real cost math.

The token is not one number — it is four

“Tokens used” is a useless aggregate because the four categories are priced wildly differently. On Opus 5.5 the gap is stark: output is five times the price of fresh input, cache writes cost more than fresh input, and cache reads cost a fraction of it. Collapsing them hides exactly the information you need to cut the bill.

A high cache-read ratio is the signal you want: long-lived context reused instead of re-billed at full input price. On a subscription the prompt cache lives about an hour; on the API or a cloud provider it is roughly five minutes, so the ratio to expect differs by setup. If cache reads collapse and fresh input climbs, something broke the cache — and you only notice if the four numbers are tracked separately.

The native options, and where each one stops

Claude Code ships with real visibility — it is just scoped to the individual.

• /usage in the CLI shows the current session's tokens and estimated cost, computed locally at list price. It is accurate for one developer on one machine, and it resets when the session is cleared. It cannot aggregate a team.
• /insights summarises recent sessions on that machine — useful for a developer reflecting on their own patterns, still not a fleet view.
• Subscription analytics (Teams and Enterprise) give an org-level spend report per user and per model, updated daily — good for finance, but not a live, per-request view.
• Cloud-provider usage is invisible to Anthropic's dashboards. Run Claude Code on Amazon Bedrock, Google Vertex or Microsoft Foundry and the native analytics simply do not see it, because the tokens are billed to your cloud account instead.

The pattern is consistent: the native tools answer “what did I just spend,” not “what is the fleet doing right now.” For that, you need the metrics to leave the machine.

OpenTelemetry: getting metrics off the machine

The native way to close the gap is OpenTelemetry. Claude Code can export per-user token and cost metrics over OTLP to your own observability stack, and it works on every setup — subscription, Console API, or any cloud provider. That makes it the one native option that gives near-real-time per-developer numbers regardless of how developers authenticate.

Turning it on

Export is off by default and driven entirely by environment variables, set in the shell profile or a managed-settings file pushed to every machine. A minimal metrics-and-logs setup:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.internal:4318
# optional: tighten the push cadence (milliseconds)
export OTEL_METRIC_EXPORT_INTERVAL=60000
export OTEL_LOGS_EXPORT_INTERVAL=5000

Metrics push on an interval — the default is 60000 ms for metrics, 5000 ms for logs — so “near-real-time” means minute-grained, not per-request. Traces are a separate beta signal gated behind CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 and OTEL_TRACES_EXPORTER=otlp; enable them only with a collector ready to receive spans.

What each signal carries

OpenTelemetry emits three kinds of signal: metrics (the counters you build dashboards on), logs (discrete events), and traces (beta spans for a single interaction). The metrics are where the cost story lives:

Per-user attribution rides on the user.email and account-identifier attributes, included by default. Note that session.id raises cardinality sharply — one series per session — so if your backend charges by series, keep it off for fleet dashboards and attribute by user instead. The event logs (claude_code.user_prompt, claude_code.tool_result, claude_code.api_request) add per-action detail metrics cannot, and can optionally carry prompt or tool content — a privacy decision to make before enabling.

The trade-off is operational: you instrument every machine, keep the variables in place through laptop refreshes and new hires, and run the collector and dashboards yourself. It streams metrics well, but a metric stream is not a request-level audit trail, and it does nothing to enforce a budget — it only reports one. For a deeper treatment of the token accounting itself, see Observability for Claude in production: token accounting and tracing.

Native vs OpenTelemetry vs a gateway

OpenTelemetry and a gateway are not mutually exclusive — a good gateway is OpenTelemetry-compliant and can feed the same stack. The difference is that the gateway also sits in the request path, so it can trace and cap, not just count. OTel is the right answer when you own the fleet, trust every machine to stay instrumented, and only need to report. A gateway is the right answer when machines come and go, when some traffic runs on a cloud provider, and when “see it” has to become “stop it.”

Observability at the TrueFoundry AI Gateway

Route Claude Code through the TrueFoundry AI Gateway and every completion crosses one point you control. That turns observability from something each developer opts into on each laptop into something that simply exists:

• Request traces — each request with the resolved user, the model served, token counts and latency, so you can answer “who sent that, and what did it cost” after the fact.
• Metrics dashboards that aggregate the fleet by user, team and model — the per-developer picture cost tracking for Claude Code walks through.
• One view across tools — Claude Code, Cursor and Codex land in the same place instead of three, as in centralising cost control for AI coding IDEs.
• OpenTelemetry-compliant export at roughly 3–4 ms of added overhead, so the same numbers flow into Grafana, Datadog or Prometheus if you already run them.

Want per-developer Claude Code spend without instrumenting every laptop?

TrueFoundry AI Gateway

What a single request trace records

A gateway answers questions OpenTelemetry metrics cannot because it logs each request as a discrete record, not a minute-bucketed counter. A trace captures the resolved identity, the model served, the four-way token split, the cost at your contracted rate, end-to-end latency in milliseconds, the status, and the routing decision. Because each row is searchable and retained, you can reconstruct a spike: filter to one developer and one hour, and read the actual calls that drove it — the audit trail a metric stream flattens away.

What to alert on, and the dashboards to build

Collecting signals is wasted if nobody looks until the invoice arrives. The point of getting metrics off the machine is to act while they still matter — a small set of alerts and a handful of dashboards, not a wall of graphs. Worthwhile alerts map to a specific, fixable cause:

• Per-developer daily spend crossing a threshold — e.g. sustained above the ~$30/day that already covers about 90% of users. This catches the outlier on the day it starts, not a month later.
• Opus share of tokens above a ceiling — the clearest signal of default-model drift, where routine edits are quietly running on the most expensive model.
• Cache-read ratio falling — a sudden drop means caching regressed and fresh input is being re-billed at full price.
• Latency p95/p99 in ms crossing a bound — surfaces provider degradation and timeout patterns before developers report them as “Claude is slow.”
• Off-hours request volume — scheduled tasks and background work that re-send large context on an interval show up as spend with no human at the keyboard.

The dashboards worth standing up are equally few: fleet cost by developer (top-N), cost by model so the Opus-vs-Sonnet-vs-Haiku mix is visible at a glance, a stacked view of the four token types to watch the cache ratio, cost per repo or team for chargebacks, a latency distribution in milliseconds, and tool-call acceptance. On a gateway these are prebuilt and fed automatically; on OpenTelemetry you assemble them in Grafana or your backend from the metrics above.

A worked example

A platform team has thirty developers on Claude Code, some on the subscription and some on Bedrock. The monthly bill is climbing and nobody can say why. They point every install at the gateway and read the dashboard the next day: three developers account for 60% of token spend, all three because Opus is their default model, and one scheduled task is re-sending a large context every hour. They set a model policy that routes routine edits to Sonnet, fix the task, and the trend line bends — without asking anyone to run a command on their laptop. The observability did not change behaviour; seeing it did.

The honest limit: a gateway shows spend and lets you cap it. It does not rewrite prompts — it makes the waste impossible to miss and gives you the policy lever to act. The enforcement side is covered in Claude Code governance with an AI gateway.

Gotchas worth knowing

• The /usage dollar figure is an estimate computed locally at list price. If your org pays contracted rates it will not match the invoice unless an admin sets the rate override.
• /usage is per machine. A developer who codes on a laptop and a desktop sees two partial pictures; only an off-machine metric (OTel or a gateway) reconciles them.
• Cloud-provider dashboards split the data. On Bedrock, Vertex or Foundry your spend lives in the cloud billing console, and per-user attribution needs OpenTelemetry or a gateway on top.
• Idle sessions still generate requests. Scheduled tasks and background work re-send full context on their interval, so a quiet-looking developer can still accrue cost — you will only see it in a per-request trace.
• Counting is not capping. OpenTelemetry tells you a budget was blown after the fact; only something in the request path can stop the request before it spends.
• session.id is a cardinality trap. Left on for fleet dashboards it creates one metric series per session, which can balloon cost on a usage-priced observability backend — attribute by user instead.
• Agent teams multiply tokens. Multi-agent runs use roughly 7x the tokens of a single session, so adopting them can make spend jump without any individual behaving differently.

Related reading

• Observability for Claude in Production: Token Accounting and Tracing — the token accounting in depth
• Cost Tracking Claude Code with the TrueFoundry AI Gateway — per-developer attribution in practice
• Centralising Cost Control for AI Coding IDEs — one view across Claude Code, Cursor and Codex
• Claude Code Pricing Explained — what the tokens you are observing actually cost
• Claude Code Governance with an AI Gateway — turning observability into enforcement

Conclusion

Claude Code observability is really cost observability with the detail turned up: tokens split four ways, attributed to a developer, a model and a task. The native tools answer it for one person on one machine; OpenTelemetry answers it for the fleet if you instrument every machine; and a gateway answers it for the fleet by default, because every request already passes through it.

Pick the layer that matches how far you need to see. If the answer is “per developer, across every model and provider, with the ability to act on what I find,” the request path is the place to stand.

See every Claude Code request, token and dollar in one place.

Book a demo