Skip to content
telemetry.dev
Esc
↑↓navigate↵open⌘Jpreview
On this page

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_KEY from the shell. Programs that Claude Code starts then can’t inherit your key.
  • Put a literal space between Bearer and the key, not %20. Claude Code sends %20 unchanged, and telemetry.dev rejects the export with 401 Unauthorized.
  • OTEL_EXPORTER_OTLP_PROTOCOL is required because Claude Code has no default protocol. Keep it at http/protobuf; telemetry.dev doesn’t accept grpc.
  • CLAUDE_CODE_ENHANCED_TELEMETRY_BETA and OTEL_TRACES_EXPORTER turn on traces, which are a Claude Code beta. Remove them to send only metrics and events. See Traces (beta).
  • OTEL_LOG_USER_PROMPTS sends the text of each prompt, and also turns on the text of Claude’s responses. Remove it to send only their lengths, or add OTEL_LOG_ASSISTANT_RESPONSES=0 to keep the prompts and drop the responses. See What leaves your machine.
  • OTEL_LOG_TOOL_DETAILS sends 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_ATTRIBUTES sets 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.

  1. Open the project Overview. Claude Code sends claude_code.session.count when 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.
  2. Submit a prompt, then open Logs. The level filter starts at error, so select All levels to see the claude_code.user_prompt and claude_code.api_request events.
  3. Open Traces. Each prompt that you submit becomes one claude_code.interaction trace.

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.

  1. Write a managed-settings.json file. Use literal values, because Claude Code does not expand references between entries in the env object:

    {
      "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_PROMPTS sends every developer’s prompts and Claude’s responses. OTEL_LOG_TOOL_DETAILS sends 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 set OTEL_LOG_ASSISTANT_RESPONSES=0 to drop response text. Remove OTEL_LOG_USER_PROMPTS to send only prompt and response lengths, and OTEL_LOG_TOOL_DETAILS to send only tool names. See What leaves your machine.

  2. Put the file in the system directory of each operating system:

    Operating system Path
    macOS /Library/Application Support/ClaudeCode/managed-settings.json
    Linux and WSL /etc/claude-code/managed-settings.json
    Windows C:\Program Files\ClaudeCode\managed-settings.json
  3. On one machine, run /status in Claude Code. Make sure that the Setting sources line shows Enterprise 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, and organization.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.

Last updated on November 16, 2026

Was this page helpful?