Claude Code
Monitor Claude Code token usage, cost, sessions, tool activity, and traces for one developer or a full team through built-in OpenTelemetry.
Claude Code has OpenTelemetry export built in. You turn it on with environment variables, and Claude Code sends metrics, events, and traces straight to https://api.telemetry.dev over OTLP/HTTP. There is nothing to install.
By default Claude Code does not send your prompts, Claude’s responses, tool arguments, file contents, or command output. The setup below turns on your prompts, Claude’s responses, and tool details, so you can see what you asked, what Claude answered, and what each tool call did: its arguments, which can include the start of the text an Edit or Write call replaces or writes, and the full error message of a failed call. It doesn’t send the output of successful tool calls, such as the files Claude reads or what a command prints, though Claude’s responses can quote that output. Claude Code always sends metadata such as token counts, tool names, and your account email. See What leaves your machine.
What you get
- Metrics: token usage, cost, session count, active time, lines of code changed, commits, and pull requests. telemetry.dev charts each metric series under Metric series on the project Overview.
- Events: one log record per prompt, API request, API error, tool result, and permission decision. They appear in Logs.
- Traces (beta): one trace per prompt, with a span for each model request and tool call. telemetry.dev reads the token usage on each model request and calculates its cost.
Set up
Create an API key
Create a project at telemetry.dev and copy its API key. Keys start with td_live_.
Set the environment variables
Set the variables in your shell, or save them in the env object of ~/.claude/settings.json so they apply however you start Claude Code:
TELEMETRY_DEV_API_KEY="td_live_..."
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.telemetry.dev"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $TELEMETRY_DEV_API_KEY"
unset TELEMETRY_DEV_API_KEY
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=development"{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
"OTEL_METRICS_EXPORTER": "otlp",
"OTEL_LOGS_EXPORTER": "otlp",
"OTEL_TRACES_EXPORTER": "otlp",
"OTEL_LOG_USER_PROMPTS": "1",
"OTEL_LOG_TOOL_DETAILS": "1",
"OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
"OTEL_EXPORTER_OTLP_ENDPOINT": "https://api.telemetry.dev",
"OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer td_live_...",
"OTEL_RESOURCE_ATTRIBUTES": "deployment.environment.name=development"
}
}- The header variable holds the key, so the last line removes
TELEMETRY_DEV_API_KEYfrom the shell. Programs that Claude Code starts then can’t inherit your key. - Put a literal space between
Bearerand the key, not%20. Claude Code sends%20unchanged, and telemetry.dev rejects the export with401 Unauthorized. OTEL_EXPORTER_OTLP_PROTOCOLis required because Claude Code has no default protocol. Keep it athttp/protobuf; telemetry.dev doesn’t acceptgrpc.CLAUDE_CODE_ENHANCED_TELEMETRY_BETAandOTEL_TRACES_EXPORTERturn on traces, which are a Claude Code beta. Remove them to send only metrics and events. See Traces (beta).OTEL_LOG_USER_PROMPTSsends the text of each prompt, and also turns on the text of Claude’s responses. Remove it to send only their lengths, or addOTEL_LOG_ASSISTANT_RESPONSES=0to keep the prompts and drop the responses. See What leaves your machine.OTEL_LOG_TOOL_DETAILSsends the arguments of each tool call, such as Bash commands, file paths, URLs, and the start of the text an Edit or Write call replaces or writes, and the full error message of a failed call, so traces and logs show what each tool did. Remove it to send only tool names. See What leaves your machine.OTEL_RESOURCE_ATTRIBUTESsets the telemetry.dev environment. Use any name you like.- Your shell doesn’t read
settings.json, so write the key itself into the header there. The file then holds your API key in plain text.
To turn on telemetry for every developer on a team, see Roll out to a team.
Start Claude Code
Run claude in the terminal where you set the variables. If you used settings.json, any terminal works. Claude Code reads the variables when it starts, so changing them in a running session has no effect.
Check that data arrives
Claude Code sends metrics every 60 seconds and events every 5 seconds. Set OTEL_METRIC_EXPORT_INTERVAL=10000 while testing to get metrics every 10 seconds.
- Open the project Overview. Claude Code sends
claude_code.session.countwhen a session starts, and it appears under Metric series after the first export. Select View all metrics (n) if it isn’t among the first charts. - Submit a prompt, then open Logs. The level filter starts at
error, so select All levels to see theclaude_code.user_promptandclaude_code.api_requestevents. - Open Traces. Each prompt that you submit becomes one
claude_code.interactiontrace.
If nothing arrives, start Claude Code with claude --debug-file /tmp/claude-debug.log and search the file for [3P telemetry] errors. Lines that start with [Anthropic telemetry] are about Anthropic’s own operational telemetry, not your export.
What you can track
Claude Code exports eight metrics and a set of events. telemetry.dev shows each metric series as a chart on the project Overview page and each event as a record on the Logs page.
| Metric | Unit | Question that it answers |
|---|---|---|
claude_code.session.count |
Count | How many sessions do developers start? |
claude_code.active_time.total |
Seconds | How much time do developers use Claude Code, without idle time? |
claude_code.token.usage |
Tokens | How many input, output, cache-read, and cache-write tokens does each model use? |
claude_code.cost.usage |
USD | How much does Claude Code cost, for each model? Claude Code calculates this value. |
claude_code.lines_of_code.count |
Count | How many lines of code does Claude Code add and remove? |
claude_code.commit.count |
Count | How many git commits does Claude Code make? |
claude_code.pull_request.count |
Count | How many pull requests does Claude Code open? |
claude_code.code_edit_tool.decision |
Count | How frequently do developers accept or reject the changes of the Edit, Write, and NotebookEdit tools? |
| Event | Claude Code sends it when | Question that it answers |
|---|---|---|
claude_code.user_prompt |
A developer submits a prompt | How many prompts does each session send, and how long are they? |
claude_code.api_request |
A model request completes | Which model answered, how long did it take, and how many tokens did it use? |
claude_code.api_error |
A model request returns an error after its last retry | Which requests do not complete, and with which status code? |
claude_code.api_retries_exhausted |
A request stops after more than one attempt | How long do developers wait on retries? |
claude_code.api_refusal |
The model refuses a request | How frequently does the model refuse? |
claude_code.assistant_response |
A model response contains text | What text did the model return? The text is redacted unless OTEL_LOG_USER_PROMPTS or OTEL_LOG_ASSISTANT_RESPONSES is set. The setup above sets the first. |
claude_code.tool_decision |
A tool permission is accepted or rejected | Which tools do developers permit, and does each decision come from a setting, a hook, or the developer? |
claude_code.tool_result |
A tool call completes | Which tools run, how long do they take, and do they complete correctly? |
claude_code.subagent_completed |
A subagent returns its result | Which subagent types run, and for how long? |
claude_code.skill_activated |
A skill starts | Which skills do developers use? |
claude_code.compaction |
A context compaction completes | How frequently do sessions fill the context window? |
claude_code.mcp_server_connection |
An MCP server connects, disconnects, or cannot connect | Which MCP servers do not connect? |
claude_code.permission_mode_changed |
The permission mode changes | When do developers change the permission mode? |
Claude Code also sends inventory and maintenance events: managed_settings_resolved, plugin_loaded, plugin_installed, hook_registered, hook_execution_start, hook_execution_complete, hook_plugin_metrics, at_mention, auth, internal_error, feedback_survey, and retention_sweep. Each name starts with claude_code.. For the attributes of each event, refer to the Claude Code monitoring reference.
Claude Code calculates claude_code.cost.usage itself, and Anthropic describes it as an approximation. telemetry.dev charts the metric as Claude Code reports it.
The Overview summary cards are built from traces. Without traces, Claude Code’s usage appears only under Metric series.
Traces (beta)
Claude Code’s tracing is a beta. The setup above turns it on with CLAUDE_CODE_ENHANCED_TELEMETRY_BETA and OTEL_TRACES_EXPORTER, and traces use the same endpoint and headers as metrics and events. To turn traces off, remove those two variables.
Anthropic can change or remove these spans in a Claude Code update. If traces stop arriving after an update, metrics and events keep working, and you can remove the two variables to stop exporting traces.
Each prompt becomes one trace:
claude_code.interaction
├── claude_code.llm_request
└── claude_code.tool
├── claude_code.tool.blocked_on_user
├── claude_code.tool.execution
└── subagent claude_code.llm_request and claude_code.tool spans
A subagent’s spans sit under the tool call that started it.
On each claude_code.llm_request span, telemetry.dev reads the input, output, cache-read, and cache-write tokens and the time to first token, and calculates the request’s cost from the model’s prices. When the span’s speed attribute is fast, telemetry.dev multiplies the rates by the model’s fast-mode multiplier if its price catalog has one, and uses standard rates otherwise. The trace’s usage and cost totals come from these spans. The claude_code.token.usage and claude_code.cost.usage metrics stay separate charts, so turning on traces doesn’t count a request twice.
If your organization also sends Claude Platform traces to the same project, each model request also has an API span from Anthropic. telemetry.dev counts the request once, on the API span. It links the two spans when the API span is a child of the claude_code.llm_request span, or when both carry the same request ID. Claude Code sends the trace context that creates the parent link only when it calls the Anthropic API directly; behind a proxy set in ANTHROPIC_BASE_URL, set CLAUDE_CODE_PROPAGATE_TRACEPARENT=1 to send it.
Roll out to a team
A managed settings file turns on telemetry for every developer on a machine. Claude Code applies managed settings above the settings of each developer.
-
Write a
managed-settings.jsonfile. Use literal values, because Claude Code does not expand references between entries in theenvobject:{ "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": "1", "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1", "OTEL_METRICS_EXPORTER": "otlp", "OTEL_LOGS_EXPORTER": "otlp", "OTEL_TRACES_EXPORTER": "otlp", "OTEL_LOG_USER_PROMPTS": "1", "OTEL_LOG_TOOL_DETAILS": "1", "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf", "OTEL_EXPORTER_OTLP_ENDPOINT": "https://api.telemetry.dev", "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer td_live_...", "OTEL_RESOURCE_ATTRIBUTES": "deployment.environment.name=production,team.id=platform" } }OTEL_LOG_USER_PROMPTSsends every developer’s prompts and Claude’s responses.OTEL_LOG_TOOL_DETAILSsends their tool arguments, such as Bash commands, file paths, and the start of the text written to files, and the full error message of each failed tool call, which can include command output. Managed settings keep developers from turning them off, though a developer can still setOTEL_LOG_ASSISTANT_RESPONSES=0to drop response text. RemoveOTEL_LOG_USER_PROMPTSto send only prompt and response lengths, andOTEL_LOG_TOOL_DETAILSto send only tool names. See What leaves your machine. -
Put the file in the system directory of each operating system:
Operating system Path macOS /Library/Application Support/ClaudeCode/managed-settings.jsonLinux and WSL /etc/claude-code/managed-settings.jsonWindows C:\Program Files\ClaudeCode\managed-settings.json -
On one machine, run
/statusin Claude Code. Make sure that theSetting sourcesline showsEnterprise managed settings (file).
You can also send the same env keys through an MDM profile or through server-managed settings in the Claude admin console. Refer to the Claude Code managed settings guide for each delivery method.
When managed settings set OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_HEADERS, Claude Code removes the conflicting endpoint and credential variables that a developer sets. As a result, a developer cannot send this telemetry to a different collector. The exporter variables, such as OTEL_METRICS_EXPORTER, follow the usual precedence, so keep them in the managed file. Otherwise, a developer can turn off a signal.
Claude Code ignores these OpenTelemetry variables in the .claude/settings.json and .claude/settings.local.json files of a repository. A repository cannot turn on telemetry or change its destination.
Use OTEL_RESOURCE_ATTRIBUTES to tell teams apart, for example with team.id=platform. A value must not contain a space. If a value contains a space, Claude Code drops all the keys and shows no error.
Attributes on each record
Each metric data point and event carries these attributes when they are available:
| Attribute | Value |
|---|---|
user.email |
The email address of the Claude account that the developer signs in with |
user.account_uuid, user.account_id |
The Claude account |
organization.id |
The Claude organization |
user.id |
An anonymous identifier for each installation of Claude Code |
session.id |
The Claude Code session |
terminal.type |
The terminal, for example iTerm.app or vscode |
Keys from OTEL_RESOURCE_ATTRIBUTES |
The keys that you set, for example team.id |
Events also carry prompt.id, which connects all the events of one prompt. Metrics do not carry prompt.id. To read the attributes of an event, open the event on the Logs page and look at the Data panel.
Estimate ingestion units
telemetry.dev counts one ingestion unit for each span, log record, and metric data point. Each event is one log record. We measured the records that Claude Code 2.1.294 and 2.1.301 send:
| Activity | Events | Spans, with traces on |
|---|---|---|
| Session start | 1 or 2, plus 1 for each plugin, hook, and MCP server | 0 |
| Prompt | 1 | 1 |
| Model request | 1, or 2 when the response contains text | 1 |
| Tool call | 2 | 3 |
The first prompt of an interactive session also makes one short model request for the session title. A slash command, such as /exit, also counts as a prompt.
Claude Code exports metrics every 60 seconds with delta temporality. An export contains only the series that changed. A minute with model requests sends 5 or more data points: four token types and one cost value for each model, plus active time and code edit counts. A minute without activity sends no data points.
Example for one developer
This example workload is an assumption. Your numbers can be different. The developer works 21 days a month. Each day, the developer starts 4 sessions and sends 25 prompts. Each prompt makes 8 model requests and 10 tool calls. Claude Code calls a model during 120 minutes of the day.
| Source | Units a day |
|---|---|
| Session starts: 4 × (15 events + 1 data point) | 64 |
| Prompts: 25 × 1 event | 25 |
| Model requests: 200 × 2 events | 400 |
| Tool calls: 250 × 2 events | 500 |
| Metrics: 120 minutes × 8 data points | 960 |
| Total for metrics and events | 1,949 |
| Traces: 25 + 200 + (250 × 3) spans | 975 |
| Total with traces | 2,924 |
For 21 days, this developer uses approximately 41,000 units a month for metrics and events, or 61,000 units with traces.
Plan for a team
| Developers | Metrics and events | With traces | Plan that fits |
|---|---|---|---|
| 1 | 41,000 | 61,000 | Pro. Free includes 30,000 units. |
| 5 | 205,000 | 307,000 | Pro, with 500,000 units |
| 20 | 819,000 | 1,228,000 | Team, with 2,000,000 units |
| 50 | 2,046,000 | 3,070,000 | Team. Ingestion continues above 2,000,000 units, with no automatic overage charges. |
A developer who only sends telemetry does not use a seat. Seats are for the members who open telemetry.dev. For the price and limits of each plan, refer to telemetry.dev/pricing.
To use fewer units, turn traces off, or set OTEL_METRIC_EXPORT_INTERVAL to a longer interval, for example 300000 for 5 minutes. Each export sends one data point for each changed series, so fewer exports send fewer data points. To see the real count, open Workspace settings → Usage.
What leaves your machine
With the setup above, Claude Code sends your prompts, Claude’s responses, and tool details, but not the output of successful tool calls. Claude’s responses can still quote file contents or command output. Each kind of content has its own opt-in variable, and all of them are off unless you set them. The setup above sets OTEL_LOG_USER_PROMPTS and OTEL_LOG_TOOL_DETAILS:
| Variable | What it adds |
|---|---|
OTEL_LOG_USER_PROMPTS=1 |
Prompt text on user_prompt events and on the claude_code.interaction span. Also turns on assistant response text unless you set OTEL_LOG_ASSISTANT_RESPONSES=0. |
OTEL_LOG_ASSISTANT_RESPONSES=1 |
Claude’s response text on assistant_response events. |
OTEL_LOG_TOOL_DETAILS=1 |
Tool arguments on events and tool spans: full Bash commands, file paths, URLs, and search patterns, and the input of each tool call, including the text an Edit or Write call replaces or writes. In that input, each value is cut at 512 characters and the whole input at about 4,000 characters. Also the full error message of a failed tool call, which can include command output; the real names of MCP servers and tools, skills, plugins, and agents; and the commit SHA and branch of a git commit that a tool ran. |
OTEL_LOG_TOOL_CONTENT=1 |
File contents, command output, and web results, on a tool.output event of each tool span. Needs tracing. |
OTEL_LOG_RAW_API_BODIES=1 |
API request and response bodies, on api_request_body and api_response_body events. They contain the conversation so far, including the system prompt and tool results, so they reveal what the other variables would. Each body is cut at about 60 KB by default, and Claude Code always redacts extended-thinking content. |
Even with all of these unset, including OTEL_LOG_USER_PROMPTS and OTEL_LOG_TOOL_DETAILS, Claude Code sends:
- Prompt and response lengths, model names, token counts, costs, durations, and success or failure.
- Tool names and permission decisions. On events, Claude Code replaces the names of tools from your own MCP servers with
mcp_tool. - Error messages from failed API requests.
session.id, an installation ID (user.id), and the host’s OS and architecture.- When you sign in with a Claude account:
user.email,user.account_uuid, andorganization.id.
telemetry.dev’s built-in redaction replaces email addresses and common secret formats before it stores data, but that happens after the data leaves your machine. To keep account UUIDs off metrics, set OTEL_METRICS_INCLUDE_ACCOUNT_UUID=false. To filter any other attribute before it is sent, route Claude Code through your own OpenTelemetry Collector.
Claude Code doesn’t pass OTEL_* variables to the commands, hooks, or MCP servers it starts, so they don’t inherit the exporter endpoint or the header that holds your key. Other variables are inherited: if you export TELEMETRY_DEV_API_KEY in the same shell, a program that uses a telemetry.dev SDK can send telemetry with it.