Claude Code metrics: the OpenTelemetry reference

Turning it on

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

# cardinality: opt out of the two attributes that are on by default
export OTEL_METRICS_INCLUDE_SESSION_ID=false
export OTEL_METRICS_INCLUDE_ACCOUNT_UUID=false

# shorter intervals while you are verifying it works
export OTEL_METRIC_EXPORT_INTERVAL=10000

The eight metrics

The attributes that turn a total into an answer

The attribute set on the token and cost counters is far richer than most people realise, and it is where the interesting queries come from. It answers which subsystem spent the money, not just which model.

processors:
  attributes/strip:
    actions:
      - key: session.id
        action: delete
  deltatocumulative: {}

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [attributes/strip, deltatocumulative, batch]
      exporters: [prometheus]

Events and traces

The logs exporter carries fifteen structured events. They are the layer where per-request detail lives, and they are what you want when a metric spike needs explaining.

• claude_code.user_prompt, claude_code.assistant_response
• claude_code.api_request, claude_code.api_error, claude_code.api_refusal
• claude_code.api_request_body, claude_code.api_response_body
• claude_code.tool_result, claude_code.tool_decision
• claude_code.permission_mode_changed, claude_code.auth
• claude_code.mcp_server_connection, claude_code.internal_error
• claude_code.plugin_installed, claude_code.plugin_loaded

The most useful of these is claude_code.api_request, which carries cost_usd, cost_usd_micros, duration_ms, ttft_ms on the span side, all four token counts, the request id, and the same attribution attributes as the counters. It is a per-request billing record.

Span tracing, in beta

Setting CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 alongside a traces exporter produces spans: claude_code.interaction wrapping a whole turn, claude_code.llm_request per model call with ttft_ms and retry attempt, claude_code.tool per tool call, and claude_code.tool.blocked_on_user measuring how long the agent waited on a permission prompt.

That last span is the one to instrument first if you are trying to work out where agent time actually goes. It separates "the model is slow" from "the human did not answer the prompt for four minutes", and those have completely different fixes.

Queries worth having

# spend per day
sum(increase(claude_code_cost_usage_total[1d]))

# spend by model
sum by (model) (increase(claude_code_cost_usage_total[1d]))

# spend by subsystem: main thread vs subagents vs auxiliary
sum by (query_source) (increase(claude_code_cost_usage_total[1d]))

# cache hit ratio: the health metric for agent efficiency
sum(rate(claude_code_token_usage_total{type="cacheRead"}[1h]))
  /
sum(rate(claude_code_token_usage_total{type=~"input|cacheRead|cacheCreation"}[1h]))

# how often people reject the agent edits
sum(rate(claude_code_code_edit_tool_decision_total{decision="reject"}[1d]))
  /
sum(rate(claude_code_code_edit_tool_decision_total[1d]))

# adoption: distinct engineers active this week
count(count by (user_account_uuid) (
  increase(claude_code_session_count_total[7d]) > 0
))

The rejection rate is the most interesting series in the set and the least used. A rising rejection rate is an early signal that a model change, a prompt convention, or a project memory file has made the agent worse, and it moves before anyone files a complaint.

Rolling it out to a team

Asking every engineer to export eight variables produces partial coverage and silent gaps, and the gaps are invisible: a machine with telemetry off looks exactly like a machine that had a quiet week. Ship the configuration with the tool instead.

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel.internal.example.com",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <token>",
    "OTEL_METRICS_INCLUDE_SESSION_ID": "false",
    "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE": "cumulative",
    "OTEL_RESOURCE_ATTRIBUTES": "team=payments,env=prod"
  }
}

For a backend that needs short-lived credentials, set otelHeadersHelper in settings to a script that prints a JSON object of headers. Claude Code re-runs it on an interval, so a token with a one-hour life works without anyone rotating anything by hand.

Questions people ask

Keep reading