Cost Controls and Usage Monitoring

One developer runs a massive refactor over the weekend. Monday morning, the bill is four figures. Nobody set a budget. Nobody got an alert.

This happens more often than you'd think.

When you go from one developer using Claude Code to twenty, cost visibility stops being optional. You need dashboards. Alerts. Hard limits. Claude Code gives you all of this through OpenTelemetry.

The OpenTelemetry Pipeline

Claude Code has built-in OTel support. Metrics, logs, and events pipe into whatever observability backend you already run: Prometheus, Datadog, Honeycomb, ClickHouse.

Enable it with a few environment variables:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

You can also use prometheus or console as exporters. Console works well for debugging. Prometheus if you've already got a Grafana stack.

Once enabled, Claude Code emits structured data about every session, every API call, every tool invocation. No instrumentation on your end.

Metrics That Matter

Most OTel metrics are noise. These actually matter for cost management:

claude_code.cost.usage is the big one. Cost in USD, broken down by model. Tells you exactly how much each session, user, and model costs. Start here.

claude_code.token.usage reports tokens consumed by type: input, output, cacheRead, cacheCreation. Output tokens are the expensive ones. If a developer's output count is consistently high relative to input, their prompts are too vague. That's your signal.

claude_code.session.count tracks session starts. A sudden spike from one user? Probably a runaway automation or someone restarting instead of using /compact.

claude_code.active_time.total measures active time in seconds, split between interactive and headless usage. Your denominator for ROI calculations.

Claude Code also emits events: claude_code.user_prompt on prompt submission, claude_code.tool_result on tool completion, claude_code.api_request for each API call (includes cost_usd, duration_ms, token counts). All segmentable by user, org, session, model, and app version.

Tagging for Multi-Team Visibility

Multiple teams? Raw metrics aren't enough. You need to know which team is spending what. Tag with OTEL_RESOURCE_ATTRIBUTES:

export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

Every metric from that developer now carries team context. Dashboards group by team.id or cost_center. Finance gets the breakdown they want.

Managed Settings for Org-Wide Control

Don't let each developer configure telemetry manually. That guarantees inconsistency. Push OTel settings through managed settings files. Set endpoint, protocol, and resource attributes once. Everyone picks up the same config. No setup docs to maintain, no "I forgot to enable telemetry" conversations.

Setting Budgets and Alerts

Metrics without alerts are just numbers. Set these up:

Cost spike alerts. Trigger when any user's claude_code.cost.usage exceeds a threshold in a rolling window. $50/day per developer is a reasonable starting point. Adjust once you know your team's baseline.

Token anomaly alerts. Flag sessions where output token usage exceeds 3x the team average. Catches runaway prompts and infinite loops before they get expensive.

Session volume alerts. 50 sessions in an hour from one user? They're scripting something without a budget cap. You want to know about that.

For automated workflows, always set --max-budget-usd:

claude -p --max-budget-usd 10.00 "Review all pull requests from this week"

Hard cap. Claude stops when the budget is hit. No exceptions, no overruns.

Per-Developer Limits and Plan Rate Limits

Different Anthropic plans have different rate limits. Pro plan triggers temporary limiting under heavy use. Max plan (formerly Team) has significantly higher limits. Run /usage to check your current status.

If your team keeps hitting rate limits, check token output ratios before upgrading the plan. Often the problem is vague prompts generating massive output, not an actual need for a higher tier.

Try It: Build a Cost Dashboard

Start with console export to see what data Claude Code actually produces:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_LOGS_EXPORTER=console

Run a Claude Code session, do some work, watch the console output. Structured JSON for every metric and event. Look for claude_code.cost.usage and claude_code.token.usage. Note the attributes on each data point.

Once you understand the data shape, swap console for otlp and point at a real collector. The claude-code-monitoring-guide GitHub repo has Docker Compose configs with Prometheus, Grafana, and OTel Collector pre-configured. Working dashboard in under fifteen minutes.

Cost Optimization at Team Scale

Individual cost tips multiply when you've got twenty people on the tool.

Context window discipline. Biggest lever by far. Every token in the context window gets re-sent with every message. A developer who never clears and runs 50-message conversations pays exponentially more than one who clears between tasks. Make /clear between unrelated tasks a team norm.

Subagent delegation. Subagents run in their own context window and return summaries. Keeps the main session lean and cheap.

Model selection. If your team defaults to Opus for everything, costs run 5-10x higher than Sonnet for comparable results on routine tasks. Set the default to Sonnet in managed settings. Save Opus for genuinely hard problems.

Prompt scoping. "Refactor the auth module" generates far fewer tokens than "improve the codebase." The cost difference is staggering.

Measuring ROI

Cost without context is meaningless. A developer spending $400/month who ships 3x more code with 50% fewer bugs? That's a bargain. Use OTel metrics to build the full picture:

• claude_code.lines_of_code.count shows lines modified (added and removed)
• claude_code.commit.count tracks commits created
• claude_code.pull_request.count counts PRs created
• claude_code.active_time.total gives you time spent

Divide output (commits, PRs, lines changed) by cost. Track per developer and per team over time. The goal isn't minimizing cost. It's maximizing output per dollar. Those are very different conversations to have with your manager.

One caveat: OTel cost metrics are approximations. For official billing, check the Anthropic Console, AWS Bedrock, or Google Cloud Vertex directly.

Bottom line: turn on telemetry (CLAUDE_CODE_ENABLE_TELEMETRY=1), pipe it to your existing observability stack, and alert on claude_code.cost.usage before someone surprises you on Monday morning. Always use --max-budget-usd on automated workflows. And make /clear between tasks a team-wide habit. That single behavior change will save more money than anything else on this page.