Claude Code OpenTelemetry Setup Skill

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

| User Request | Mode | Action | |--------------|------|--------| | "Set up telemetry locally" | Mode 1 | Full PoC stack | | "I want to try OpenTelemetry" | Mode 1 | Full PoC stack | | "Connect to company endpoint" | Mode 2 | Enterprise config | | "Set up for team rollout" | Mode 2 | Enterprise + docs | | "Dashboard not working" | Troubleshoot | See known issues |

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

Check OTEL_METRICS_EXPORTER and OTEL_LOGS_EXPORTER are set
Verify Claude Code was restarted
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

Agent Skills: Claude Code OpenTelemetry Setup

Install this agent skill to your local

Skill Files