Claude Code Observability Stack

The stack follows a standard OpenTelemetry pipeline to ingest, store, and visualize Claude Code data:

1. Claude Code: Generates telemetry data.
2. OpenTelemetry Collector: Receives metrics and logs via gRPC (port 4317) or HTTP (port 4318).
3. Storage Layer:
   • Prometheus: Stores time-series metrics.
   • Loki: Aggregates and stores events and logs.
4. Grafana: Provides the visualization layer for querying both Prometheus and Loki to create dashboards.

Claude Code → OpenTelemetry Collector → Prometheus (metrics) + Loki (events/logs)
                                     ↓
                              Grafana (visualization & analysis)

Use the exported metrics to build dashboards for the following purposes:

Usage & Productivity

• Adoption: Track claude_code.session.count over time.
• Token Consumption: Break down claude_code.token.usage by type (input/output), model, or user.account_uuid.
• Development Impact: Monitor claude_code.lines_of_code.count, claude_code.commit.count, and claude_code.pull_request.count to measure productivity.

Cost Management

• Trend Analysis: Use claude_code.cost.usage to track spending across teams or individuals.
• Optimization: Identify high-cost sessions by segmenting cost metrics by model or session.id.

Note: Cost metrics are approximations. Use your API provider's console (Anthropic, AWS, or Google Cloud) for official billing data.

Use event data to monitor the reliability and performance of the Claude Code environment:

Tool Performance

Analyze claude_code.tool_result events to determine:

• Most frequently used tools.
• Tool success rates.
• Average execution time (duration_ms).
• Error patterns by tool name.

API Reliability

Analyze claude_code.api_request and claude_code.api_error events to track:

• Request latency (duration_ms).
• Error rates and specific error messages.
• Model-specific performance (e.g., comparing Sonnet vs Haiku latency/errors).
• Retry attempts via the attempt attribute in error events.

Administrators can centrally manage OpenTelemetry settings for all users by using a managed settings file. Environment variables defined here have high precedence and cannot be overridden by individual users. This is ideal for distribution via MDM (Mobile Device Management).

File Locations:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux: /etc/claude-code/managed-settings.json

{
  "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.company.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"
  }
}

By default, user prompt content is redacted for privacy; only the prompt_length is recorded in the claude_code.user_prompt event. To capture the actual content of user prompts for debugging or analysis, set the OTEL_LOG_USER_PROMPTS environment variable to 1.

export OTEL_LOG_USER_PROMPTS=1

After starting the stack, you must configure your Claude Code environment variables to enable telemetry and point the OpenTelemetry exporters to the local collector. Use the following configuration to enable gRPC-based OTLP exporting.

# Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# Configure exporters
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Run Claude Code
claude

To set up the Claude Code Observability Stack, use the provided Makefile to manage the Docker-based services. This will start the OpenTelemetry Collector, Prometheus, Loki, and Grafana.

# Start all services
make up

# Check status
make status

Once the stack is running and Claude Code is sending data, you can access the visualization and metrics interfaces at these default local addresses:

• Grafana (Dashboards): http://localhost:3000 (Default credentials: admin/admin)
• Prometheus (Metrics): http://localhost:9090

You can control which metadata is attached to exported metrics using the following environment variables:

• OTEL_METRICS_INCLUDE_SESSION_ID: Controls inclusion of the session.id attribute.
• OTEL_METRICS_INCLUDE_VERSION: Controls inclusion of the app.version attribute.
• OTEL_METRICS_INCLUDE_ACCOUNT_UUID: Controls inclusion of the user.account_uuid attribute.

You can fine-tune the telemetry behavior using several OpenTelemetry and Claude-specific environment variables. Use these to control export intervals, privacy, and data cardinality.

# Core telemetry
CLAUDE_CODE_ENABLE_TELEMETRY=1

# Exporter configuration
OTEL_METRICS_EXPORTER=otlp,prometheus    # Multiple exporters
OTEL_LOGS_EXPORTER=otlp

# Protocol and endpoints
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token"

# Export intervals
OTEL_METRIC_EXPORT_INTERVAL=60000        # 1 minute (production)
OTEL_LOGS_EXPORT_INTERVAL=5000           # 5 seconds

# Privacy controls
OTEL_LOG_USER_PROMPTS=1                   # Enable prompt content logging

# Cardinality control
OTEL_METRICS_INCLUDE_SESSION_ID=true
OTEL_METRICS_INCLUDE_VERSION=false
OTEL_METRICS_INCLUDE_ACCOUNT_UUID=true