Claude Code OpenTelemetry: Track Usage and Cost (Setup)

Claude Code OpenTelemetry export sends usage data from every session to a collector you run. Metrics arrive as time series: sessions, lines changed, commits, pull requests, tokens, estimated cost and active time. Events arrive through the logs protocol: each prompt, API request, API error, tool result and permission decision. Traces are available as a beta. Nothing is exported until someone turns it on.

Team and Enterprise plans already get an analytics dashboard with active users, sessions, accept rates and contribution metrics. That covers adoption. OpenTelemetry is what you add when you need per-user token counts and cost estimates in your own monitoring stack, alerts on spend spikes, or a breakdown by team, cost center, skill or model that the dashboard does not give you. My take: if you are paying for Claude Code across more than a handful of people, you want this on before the first surprise bill, not after.

Test on your own machine before you roll anything out. You need a collector that accepts OTLP, running locally or somewhere your laptop can reach. Then set these variables in your shell or in the env block of ~/.claude/settings.json:

Metrics export every 60 seconds by default and logs every 5 seconds. While testing, drop OTEL_METRIC_EXPORT_INTERVAL to 10000 so you are not waiting a minute for each check, then set it back for production. Start a session in the desktop app or the terminal and look for claude_code.session.count in your backend. For a logs-only setup, send a prompt and look for the claude_code.user_prompt event.

For a company, do not ask every developer to edit their shell. Put the same variables in the env block of your managed settings file and push it with your device management. The desktop app's Code tab reads managed settings too, so desktop users are covered alongside terminal users. The settings.json guide covers where each settings file lives and which one wins.

Managed settings also lock the destination. When you set OTEL_EXPORTER_OTLP_ENDPOINT there, Claude Code removes any per-signal endpoint a developer set, so nobody can quietly send one signal to a different collector. Setting headers or client certificates there removes developer-set endpoints too, because your credentials should only ever reach the collector you chose. The exporter selectors are the exception: a developer can still switch a signal to none or console unless you set OTEL_METRICS_EXPORTER and OTEL_LOGS_EXPORTER in managed settings as well. Set all of them.

Repositories cannot interfere in the other direction. Claude Code ignores the OpenTelemetry exporter variables in a repo's .claude/settings.json and .claude/settings.local.json, so a cloned project cannot switch telemetry on, choose where it goes or capture content. A repo can only turn a signal off by setting its exporter to none, and only when managed settings have not already set that variable.

The cost metric is an estimate. For billing, your API provider's own records are the source of truth. Use claude_code.cost.usage for trends and alerts, not for invoices. The useful part is the breakdown: cost and token metrics carry model, effort level and query_source, which tells you whether spend came from the main conversation, subagents or background requests.

The three alerts I would set first are a cost spike per user per day, unusual token volume, and a jump in session count from one account. All three come straight from these metrics. If you are trying to bring spend down after you see it, how to cut Claude Code token usage and the effort levels guide are the two levers that move it most.

Every metric and event already carries a session ID, your organization ID, account identifiers and, when signed in, the user's email. To add your own grouping, set OTEL_RESOURCE_ATTRIBUTES with comma-separated key=value pairs, for example department=engineering,team.id=platform,cost_center=eng-123. Those keys become labels on every metric and event, so you can build a dashboard per team or charge spend back to a cost center.

This is the question every security team asks first, and the defaults are sensible. Raw file contents and code snippets are never in metrics or events. Prompt text is not collected, only prompt length. Response text is not collected, only its length. Tool arguments like Bash commands and file paths are not logged. All of it goes only to the endpoint you configure.

My advice: leave the content flags off for the first rollout. Usage and cost answer most of what a team lead wants to know, and turning on prompt or tool content changes the conversation with your developers and your legal team. If you need it later for audits, turn it on deliberately and filter it in your collector. If you set OTEL_LOG_ASSISTANT_RESPONSES=0 explicitly, you can collect prompts without collecting responses.