Claude Code OpenTelemetry Setup

This guide explains how to set up Claude Code to export telemetry to an OpenTelemetry Collector running in Docker, which writes data as JSONL files that you can analyze in Hyperparam.

Note: Claude Code also writes conversation transcripts directly to ~/.claude/projects/<project-hash>/<session-id>.jsonl. These can be more convenient for local chat log analysis, while OpenTelemetry is useful for centralized telemetry collection and analysis.

Telemetry Types

OpenTelemetry exports three data types: traces (detailed operation spans with full context), logs (discrete events), and metrics (aggregated numbers). Traces contain the most raw data.

Quick Start

The setup has three components:

  1. Claude Code exports telemetry via OTLP protocol
  2. OTel Collector receives telemetry and processes it
  3. JSONL files collector writes data to disk that can be analyzed in Hyperparam

1. Create the Collector Configuration

Create otel-collector-config.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  file/traces:
    path: /data/traces.jsonl
    format: json
  file/logs:
    path: /data/logs.jsonl
    format: json
  file/metrics:
    path: /data/metrics.jsonl
    format: json

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [file/traces]
    logs:
      receivers: [otlp]
      exporters: [file/logs]
    metrics:
      receivers: [otlp]
      exporters: [file/metrics]

This configuration listens for OTLP on port 4318 (HTTP) and writes traces, logs, and metrics as JSONL files.

2. Run the Collector with Docker

Create a directory for output and start the collector:

mkdir -p otel-data
docker run -d \
  --name otel-collector \
  -v ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  -v ./otel-data:/data:rw \
  -p 4318:4318 \
  otel/opentelemetry-collector-contrib:latest

3. Configure Claude Code

Add these environment variables to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
  }
}

Alternatively, set these as shell environment variables.

Verification

After running Claude Code with telemetry enabled, check the output files:

tail -f otel-data/traces.jsonl
tail -f otel-data/logs.jsonl

Open the JSONL files in Hyperparam to explore and analyze your Claude Code logs.

Troubleshooting

Check collector logs for errors:

docker logs otel-collector
Claude Code OpenTelemetry Setup - Hyperparam