Monitor Claude Code with Axiom

Prerequisites#

• Create an Axiom account.
• Create two datasets in Axiom: one for metrics and one for logs. Claude Code doesn't emit traces. For more information, see Create dataset.
• Create an API token in Axiom with ingest permissions for both datasets.

How Axiom routes OpenTelemetry data#

Axiom routes data to datasets via headers, and the header differs by signal type:

• Logs 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.

The /v1/metrics endpoint only supports the application/x-protobuf content type.

Configure environment variables#

Create a file named setup-otel.sh with the following content:

setup-otel.sh

#!/bin/bash
 
# Claude Code OpenTelemetry configuration for Axiom
# Usage: source ./setup-otel.sh && claude
 
# Replace these with your own values
AXIOM_API_TOKEN="API_TOKEN"
AXIOM_HOST="AXIOM_DOMAIN"
AXIOM_METRICS_DATASET="METRICS_DATASET_NAME"
AXIOM_LOGS_DATASET="LOGS_DATASET_NAME"
 
# Enable telemetry and configure both exporters
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
 
# Axiom's metrics endpoint requires protobuf (no JSON support)
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf
 
# Separate endpoints per signal type
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://${AXIOM_HOST}/v1/metrics
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://${AXIOM_HOST}/v1/logs
 
# Separate headers per signal type (Axiom routes to datasets via different headers)
export OTEL_EXPORTER_OTLP_METRICS_HEADERS="Authorization=Bearer ${AXIOM_API_TOKEN},x-axiom-metrics-dataset=${AXIOM_METRICS_DATASET}"
export OTEL_EXPORTER_OTLP_LOGS_HEADERS="Authorization=Bearer ${AXIOM_API_TOKEN},x-axiom-dataset=${AXIOM_LOGS_DATASET}"
 
# Shorter intervals for testing (default: 60s metrics, 5s logs)
export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000
 
# Optional: log full prompt content and tool/MCP details
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
 
echo "Axiom OTel configured: metrics -> ${AXIOM_METRICS_DATASET}, logs -> ${AXIOM_LOGS_DATASET}"

Verify the integration#

source ./setup-otel.sh && claude

Production considerations#

When moving from testing to production, consider these adjustments:

• Disable prompt logging: Remove OTEL_LOG_USER_PROMPTS=1 unless prompt content is needed in your observability backend. This reduces the volume of sensitive data stored.

• 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_ATTRIBUTES to tag all telemetry with department, team, or cost center identifiers for filtering and alerting in Axiom.

  export OTEL_RESOURCE_ATTRIBUTES="team=platform,cost_center=engineering,environment=production"

• Adjust export intervals: For production, consider using longer intervals to reduce overhead:

  export OTEL_METRIC_EXPORT_INTERVAL=60000  # 60 seconds
  export OTEL_LOGS_EXPORT_INTERVAL=30000    # 30 seconds

Reference#

Environment variables#

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.