Claude Code OpenTelemetry Setup

Automated workflow for setting up OpenTelemetry telemetry collection for Claude Code usage monitoring, cost tracking, and productivity analytics.

Quick Decision Matrix

Mode 1: Local PoC Setup

Goal: Complete local telemetry stack for individual developer

Creates:

• •OpenTelemetry Collector (receives data)
• •Prometheus (stores metrics)
• •Loki (stores logs)
• •Grafana (dashboards)

Prerequisites:

• •Docker Desktop running
• •2GB free disk space
• •Write access to ~/.claude/

Time: 5-7 minutes

Workflow: modes/mode1-poc-setup.md

Output:

• •Grafana at http://localhost:3000 (admin/admin)
• •Management scripts in ~/.claude/telemetry/

Mode 2: Enterprise Setup

Goal: Connect Claude Code to centralized company infrastructure

Required Info:

• •OTEL Collector endpoint URL
• •Authentication (API key or certificates)
• •Team/department identifier

Time: 2-3 minutes

Workflow: modes/mode2-enterprise.md

Output:

• •settings.json configured for central endpoint
• •Team rollout documentation

Critical Configuration

REQUIRED in settings.json (without these, telemetry won't work):

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"
  }
}

Must restart Claude Code after settings changes!

Pre-Flight Check

Always run before setup:

# Verify Docker is running
docker info > /dev/null 2>&1 || echo "Start Docker Desktop first"

# Check available ports
for port in 3000 4317 4318 8889 9090; do
  lsof -i :$port > /dev/null 2>&1 && echo "Port $port in use"
done

# Check disk space (need 2GB)
df -h ~/.claude

Metrics Collected

• •Session counts and active time
• •Token usage (input/output/cached)
• •API costs by model (USD)
• •Lines of code modified
• •Commits and PRs created

Management Commands

# Start telemetry stack
~/.claude/telemetry/start-telemetry.sh

# Stop (preserves data)
~/.claude/telemetry/stop-telemetry.sh

# Full cleanup (removes all data)
~/.claude/telemetry/cleanup-telemetry.sh

Common Issues

No Data in Dashboard

1. •Check OTEL_METRICS_EXPORTER and OTEL_LOGS_EXPORTER are set
2. •Verify Claude Code was restarted
3. •See reference/known-issues.md

Datasource Not Found

Dashboard has wrong UID. Detect your UID:

curl -s http://admin:admin@localhost:3000/api/datasources | jq '.[0].uid'

Replace in dashboard JSON and re-import.

Metric Names Double Prefix

Metrics use claude_code_claude_code_* format. Update dashboard queries accordingly.

Reference Documentation

• •modes/mode1-poc-setup.md - Detailed local setup workflow
• •modes/mode2-enterprise.md - Enterprise configuration steps
• •reference/known-issues.md - Troubleshooting guide
• •templates/ - Configuration file templates
• •dashboards/ - Grafana dashboard JSON files

Safety Checklist

• • Backup settings.json before modification
• • Verify Docker is running first
• • Check ports are available
• • Test data flow before declaring success
• • Provide cleanup instructions

Version: 1.1.0 | Author: Prometheus Team