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