Monitor Claude Code with Axiom
Configure Claude Code to send OpenTelemetry metrics, logs, and traces to Axiom for usage monitoring and observability.
Claude Code has built-in OpenTelemetry support that exports metrics, logs, and traces (trace export is in beta). Axiom natively ingests OTLP data, making the two a natural fit. This guide covers the Axiom-specific configuration to connect Claude Code telemetry to Axiom.
Prerequisites
- Create an Axiom account.
- Create three datasets for metrics, logs, and traces in a correlation group. To create all three at once, go to Datasets > Correlations > New correlation group, select From new datasets, and enter a prefix such as
claude. Axiom createsclaude-metrics,claude-logs, andclaude-traces. - Create an API token in Axiom with ingest permissions for the three datasets only.
How Axiom routes OpenTelemetry data
Axiom routes data to datasets via headers, and the header differs by signal type:
- Logs and traces use
x-axiom-dataset - Metrics use
x-axiom-metrics-dataset
This means signal-specific header configuration is required rather than a single shared OTEL_EXPORTER_OTLP_HEADERS value.
Configure environment variables
Create a file named setup-otel.sh with the following content:
Verify the integration
Run the following command in your terminal:
Use Claude Code for 15 to 20 seconds to generate telemetry data. Ask questions, run commands, or perform any typical tasks.
In Axiom, go to your datasets and observe the telemetry data:
- The logs dataset shows events like
claude_code.user_prompt,claude_code.tool_result, andclaude_code.api_request. - The metrics dataset shows counters like
claude_code.session.countandclaude_code.token.usage, updating on the 10-second interval configured above. - The traces dataset shows spans like
claude_code.interactionandclaude_code.llm_request.
In the logs dataset, click an event, and then click View trace. Because the datasets are in a correlation group, Axiom opens the trace of the prompt that produced the event.
Production considerations
When moving from testing to production, consider these adjustments:
-
Disable prompt logging: Remove
OTEL_LOG_USER_PROMPTS=1unless prompt content is needed in your observability backend. This reduces the volume of sensitive data stored. -
Limit content logging:
OTEL_LOG_TOOL_DETAILS,OTEL_LOG_TOOL_CONTENT, andOTEL_LOG_RAW_API_BODIESadd commands, file contents, and full conversations to your telemetry. This content can include source code and secrets. Enable only the flags you need. -
Use managed settings for teams: For team deployments, administrators can set these variables in Claude Code's managed settings file instead of relying on each developer to source a script.
-
Add resource attributes: Use
OTEL_RESOURCE_ATTRIBUTESto tag all telemetry with department, team, or cost center identifiers for filtering and alerting in Axiom.shell -
Adjust export intervals: For production, consider using longer intervals to reduce overhead:
shell
Reference
Environment variables
| Variable | Description |
|---|---|
CLAUDE_CODE_ENABLE_TELEMETRY | Set to 1 to enable OpenTelemetry export. |
OTEL_METRICS_EXPORTER | Set to otlp to enable OTLP metrics export. |
OTEL_LOGS_EXPORTER | Set to otlp to enable OTLP logs export. |
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA | Set to 1 to enable trace export, which is in beta. |
OTEL_TRACES_EXPORTER | Set to otlp to enable OTLP traces export. |
OTEL_EXPORTER_OTLP_PROTOCOL | Protocol for all signals. Use http/protobuf for Axiom. |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Axiom metrics endpoint URL. |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Axiom logs endpoint URL. |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Axiom traces endpoint URL. |
OTEL_EXPORTER_OTLP_METRICS_HEADERS | Headers for metrics including authorization and dataset. |
OTEL_EXPORTER_OTLP_LOGS_HEADERS | Headers for logs including authorization and dataset. |
OTEL_EXPORTER_OTLP_TRACES_HEADERS | Headers for traces including authorization and dataset. |
OTEL_METRIC_EXPORT_INTERVAL | Metrics export interval in milliseconds. Default: 60000. |
OTEL_LOGS_EXPORT_INTERVAL | Logs export interval in milliseconds. Default: 5000. |
OTEL_LOG_USER_PROMPTS | Set to 1 to log full prompt content. |
OTEL_LOG_TOOL_DETAILS | Set to 1 to log tool and MCP details. |
OTEL_LOG_TOOL_CONTENT | Set to 1 to log tool output, such as file contents and command output, in trace spans. Requires trace export. |
OTEL_LOG_RAW_API_BODIES | Set to 1 to log the full API request and response bodies, which include the conversation history. |
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH | Maximum length of content attributes, such as tool output and API bodies, in UTF-16 code units. Default: 61440. The maximum field size in Axiom is 1 MB, and 262144 stays under it for any text. |
OTEL_RESOURCE_ATTRIBUTES | Comma-separated key=value pairs for resource attributes. |
Expected telemetry data
Claude Code exports the following telemetry:
Logs:
claude_code.user_prompt: User prompts sent to Claude Code.claude_code.tool_result: Results from tool executions.claude_code.api_request: API requests made by Claude Code.
Metrics:
claude_code.session.count: Number of Claude Code sessions.claude_code.token.usage: Token usage counters.
Traces:
claude_code.interaction: Root span for each user prompt.claude_code.llm_request: API requests made by Claude Code.claude_code.tool: Tool executions.