Monitoring

​

Quick start

# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choose exporters (both are optional - configure only what you need)
export OTEL_METRICS_EXPORTER=otlp       # Options: otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # Options: otlp, console

# 3. Configure OTLP endpoint (for OTLP exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Set authentication (if required)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. For debugging: reduce export intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 seconds (default: 5000ms)

# 6. Run Claude Code
claude

​

Administrator configuration

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

​

Configuration details

​

Common configuration variables

​

Metrics cardinality control

​

Dynamic headers

​

Settings configuration

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

​

Script requirements

#!/bin/bash
# Example: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

​

Refresh behavior

​

Multi-team organization support

# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

• Filter metrics by team or department
• Track costs per cost center
• Create team-specific dashboards
• Set up alerts for specific teams

# ❌ Invalid - contains spaces
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valid - use underscores or camelCase instead
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valid - percent-encode special characters if needed
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

​

Example configurations

# Console debugging (1-second intervals)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Multiple exporters
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Different endpoints/backends for metrics and logs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

# Metrics only (no events/logs)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Events/logs only (no metrics)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

​

Available metrics and events

​

Standard attributes

​

Metrics

​

Metric details

​

Session counter

• All standard attributes

​

Lines of code counter

• All standard attributes
• type: ("added", "removed")

​

Pull request counter

• All standard attributes

​

Commit counter

• All standard attributes

​

Cost counter

• All standard attributes
• model: Model identifier (for example, “claude-sonnet-4-6”)

​

Token counter

• All standard attributes
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Model identifier (for example, “claude-sonnet-4-6”)

​

Code edit tool decision counter

• All standard attributes
• tool_name: Tool name ("Edit", "Write", "NotebookEdit")
• decision: User decision ("accept", "reject")
• source: Decision source - "config", "hook", "user_permanent", "user_temporary", "user_abort", or "user_reject"
• language: Programming language of the edited file, such as "TypeScript", "Python", "JavaScript", or "Markdown". Returns "unknown" for unrecognized file extensions.

​

Active time counter

• All standard attributes
• type: "user" for keyboard interactions, "cli" for tool execution and AI responses

​

Events

​

Event correlation attributes

​

User prompt event

• All standard attributes
• event.name: "user_prompt"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• prompt_length: Length of the prompt
• prompt: Prompt content (redacted by default, enable with OTEL_LOG_USER_PROMPTS=1)

​

Tool result event

• All standard attributes
• event.name: "tool_result"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• tool_name: Name of the tool
• success: "true" or "false"
• duration_ms: Execution time in milliseconds
• error: Error message (if failed)
• decision_type: Either "accept" or "reject"
• decision_source: Decision source - "config", "hook", "user_permanent", "user_temporary", "user_abort", or "user_reject"
• tool_result_size_bytes: Size of the tool result in bytes
• mcp_server_scope: MCP server scope identifier (for MCP tools)
• tool_parameters: JSON string containing tool-specific parameters (when available)
  • For Bash tool: includes bash_command, full_command, timeout, description, dangerouslyDisableSandbox, and git_commit_id (the commit SHA, when a git commit command succeeds)
  • For MCP tools (when OTEL_LOG_TOOL_DETAILS=1): includes mcp_server_name, mcp_tool_name
  • For Skill tool (when OTEL_LOG_TOOL_DETAILS=1): includes skill_name

​

API request event

• All standard attributes
• event.name: "api_request"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• model: Model used (for example, “claude-sonnet-4-6”)
• cost_usd: Estimated cost in USD
• duration_ms: Request duration in milliseconds
• input_tokens: Number of input tokens
• output_tokens: Number of output tokens
• cache_read_tokens: Number of tokens read from cache
• cache_creation_tokens: Number of tokens used for cache creation
• speed: "fast" or "normal", indicating whether fast mode was active

​

API error event

• All standard attributes
• event.name: "api_error"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• model: Model used (for example, “claude-sonnet-4-6”)
• error: Error message
• status_code: HTTP status code as a string, or "undefined" for non-HTTP errors
• duration_ms: Request duration in milliseconds
• attempt: Attempt number (for retried requests)
• speed: "fast" or "normal", indicating whether fast mode was active

​

Tool decision event

• All standard attributes
• event.name: "tool_decision"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• tool_name: Name of the tool (for example, “Read”, “Edit”, “Write”, “NotebookEdit”)
• decision: Either "accept" or "reject"
• source: Decision source - "config", "hook", "user_permanent", "user_temporary", "user_abort", or "user_reject"

​

Interpret metrics and events data

​

Usage monitoring

​

Cost monitoring

• Tracking usage trends across teams or individuals
• Identifying high-usage sessions for optimization

​

Alerting and segmentation

• Cost spikes
• Unusual token consumption
• High session volume from specific users

​

Event analysis

• Most frequently used tools
• Tool success rates
• Average tool execution times
• Error patterns by tool type

​

Backend considerations

​

For metrics

• Time series databases (for example, Prometheus): Rate calculations, aggregated metrics
• Columnar stores (for example, ClickHouse): Complex queries, unique user analysis
• Full-featured observability platforms (for example, Honeycomb, Datadog): Advanced querying, visualization, alerting

​

For events/logs

• Log aggregation systems (for example, Elasticsearch, Loki): Full-text search, log analysis
• Columnar stores (for example, ClickHouse): Structured event analysis
• Full-featured observability platforms (for example, Honeycomb, Datadog): Correlation between metrics and events

​

Service information

• service.name: claude-code
• service.version: Current Claude Code version
• os.type: Operating system type (for example, linux, darwin, windows)
• os.version: Operating system version string
• host.arch: Host architecture (for example, amd64, arm64)
• wsl.version: WSL version number (only present when running on Windows Subsystem for Linux)
• Meter Name: com.anthropic.claude_code

​

ROI measurement resources

​

Security and privacy

• Telemetry is opt-in and requires explicit configuration
• Raw file contents and code snippets are not included in metrics or events. Tool execution events include bash commands and file paths in the tool_parameters field, which may contain sensitive values. If your commands may include secrets, configure your telemetry backend to filter or redact tool_parameters
• When authenticated via OAuth, user.email is included in telemetry attributes. If this is a concern for your organization, work with your telemetry backend to filter or redact this field
• User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set OTEL_LOG_USER_PROMPTS=1
• MCP server/tool names and skill names are not logged by default because they can reveal user-specific configurations. To include them, set OTEL_LOG_TOOL_DETAILS=1

​

Monitor Claude Code on Amazon Bedrock