{"slug": "claude-code-metrics-setup-prometheus-grafana-dashboards-for-tracking-ai-coding", "title": "Claude Code Metrics Setup: Prometheus + Grafana dashboards for tracking AI coding productivity", "summary": "Technical guide for setting up OpenTelemetry (OTEL) telemetry from Claude Code to Prometheus and Grafana to track AI coding productivity metrics. It details the configuration steps, including enabling telemetry via environment variables, installing and configuring Prometheus with OTLP receiver support, and setting up Grafana dashboards for visualizing metrics like token usage, cost, lines of code, and productivity ratios. The guide also includes PromQL query examples for calculating key performance indicators such as productivity ratio, lines per dollar, and cache efficiency.", "body_md": "# Claude Code Metrics Setup Guide\n\nThis guide walks through setting up OTEL telemetry from Claude Code to Prometheus + Grafana.\n\n## Architecture\n\n```\nClaude Code  -->  OTLP/HTTP  -->  Prometheus  -->  Grafana\n   (metrics)      (protobuf)      (storage)       (viz)\n```\n\n## 1. Environment Variables\n\nAdd to your shell profile (`~/.bashrc` for Linux, `~/.zshrc` for macOS):\n\n``` bash\n# Enable Claude Code telemetry\nexport CLAUDE_CODE_ENABLE_TELEMETRY=1\n\n# OTEL export configuration\nexport OTEL_METRICS_EXPORTER=otlp\nexport OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\nexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:9090/api/v1/otlp\nexport OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta\n```\n\nReload your shell: `source ~/.bashrc`\n\n## 2. Prometheus Setup\n\n### Install (AL2023 / Amazon Linux)\n\n``` bash\n# Download latest Prometheus\ncd /tmp\ncurl -LO https://github.com/prometheus/prometheus/releases/download/v3.0.0/prometheus-3.0.0.linux-amd64.tar.gz\ntar xzf prometheus-3.0.0.linux-amd64.tar.gz\nsudo mv prometheus-3.0.0.linux-amd64 /opt/prometheus\n\n# Create data directory\nmkdir -p ~/.prometheus/data\n```\n\n### Install (macOS with Homebrew)\n\n``` bash\nbrew install prometheus\n```\n\n### Configuration\n\nCreate `~/.prometheus/prometheus.yml`:\n\n``` yaml\nglobal:\n  scrape_interval: 15s\n\nscrape_configs:\n  - job_name: \"prometheus\"\n    static_configs:\n    - targets: [\"localhost:9090\"]\n```\n\n### Run Prometheus with OTLP Receiver\n\n**Critical flags:**\n- `--web.enable-otlp-receiver` - Enables the OTLP ingestion endpoint\n- `--enable-feature=otlp-deltatocumulative` - Converts delta metrics (like lines_of_code) to cumulative\n\n``` bash\n# Linux\n/opt/prometheus/prometheus \\\n  --config.file=~/.prometheus/prometheus.yml \\\n  --storage.tsdb.path=~/.prometheus/data \\\n  --web.listen-address=127.0.0.1:9090 \\\n  --web.enable-otlp-receiver \\\n  --enable-feature=otlp-deltatocumulative\n\n# macOS (if running manually)\nprometheus \\\n  --config.file=/opt/homebrew/etc/prometheus.yml \\\n  --storage.tsdb.path=/opt/homebrew/var/prometheus \\\n  --web.listen-address=127.0.0.1:9090 \\\n  --web.enable-otlp-receiver \\\n  --enable-feature=otlp-deltatocumulative\n```\n\nYou can run this in a tmux session or background it.\n\n## 3. Grafana Setup\n\n### Install (AL2023 / Amazon Linux)\n\n``` bash\n# Add Grafana repo\nsudo tee /etc/yum.repos.d/grafana.repo << 'EOF'\n[grafana]\nname=grafana\nbaseurl=https://rpm.grafana.com\nrepo_gpgcheck=1\nenabled=1\ngpgcheck=1\ngpgkey=https://rpm.grafana.com/gpg.key\nsslverify=1\nsslcacert=/etc/pki/tls/certs/ca-bundle.crt\nEOF\n\nsudo dnf install grafana -y\nsudo systemctl start grafana-server\n```\n\n### Install (macOS)\n\n``` bash\nbrew install grafana\nbrew services start grafana\n```\n\n### Access\n\n- URL: http://localhost:3000\n- Default login: admin / admin\n\n### Add Prometheus Data Source\n\n1. Go to Connections → Data Sources → Add data source\n2. Select Prometheus\n3. URL: `http://localhost:9090`\n4. Save & Test\n\n### Import Dashboards\n\n1. Go to Dashboards → Import\n2. Paste the JSON from the dashboard files in this directory\n3. Select your Prometheus data source\n4. Import\n\nDashboard files included:\n- `dashboard-metrics.json` - Claude Code Metrics (tokens, cost, productivity ratio)\n- `dashboard-summary.json` - Daily/Weekly Summary (aggregated stats)\n- `dashboard-economics.json` - Engineering Economics (ROI, team equivalence)\n\n## 4. Verify Metrics Are Flowing\n\nAfter using Claude Code with telemetry enabled:\n\n``` bash\n# Check available metrics\ncurl -s 'http://localhost:9090/api/v1/label/__name__/values' | jq '.data[]' | grep claude\n```\n\nYou should see:\n- `claude_code_token_usage_tokens_total`\n- `claude_code_cost_usage_USD_total`\n- `claude_code_active_time_seconds_total`\n- `claude_code_lines_of_code_count_total`\n- `claude_code_session_count_total`\n\n## 5. Available Metrics\n\n| Metric | Labels | Description |\n|--------|--------|-------------|\n| `claude_code_token_usage_tokens_total` | `type` (input/output/cacheRead/cacheCreation), `model` | Token consumption |\n| `claude_code_cost_usage_USD_total` | `model` | Estimated API cost in USD |\n| `claude_code_active_time_seconds_total` | `type` (cli/user) | Time tracking |\n| `claude_code_lines_of_code_count_total` | `type` (added/removed) | Code output (delta metric!) |\n| `claude_code_session_count_total` | | Session count |\n| `claude_code_event_count_total` | `event` | Events (commits, PRs, etc.) |\n\n## 6. Key Queries\n\n**Productivity Ratio** (CLI time / User time):\n``` promql\nsum(claude_code_active_time_seconds_total{type=\"cli\"})\n/ sum(claude_code_active_time_seconds_total{type=\"user\"})\n```\n\n**Lines per Dollar**:\n``` promql\nsum(sum_over_time(claude_code_lines_of_code_count_total[$__range]))\n/ sum(increase(claude_code_cost_usage_USD_total[$__range]))\n```\n\n**Cache Efficiency**:\n``` promql\nsum(claude_code_token_usage_tokens_total{type=\"cacheRead\"})\n/ (sum(claude_code_token_usage_tokens_total{type=\"cacheRead\"}) + sum(claude_code_token_usage_tokens_total{type=\"input\"}))\n* 100\n```\n\n**Important:** The `lines_of_code` metric is a **delta metric**, not cumulative. Use `sum_over_time()` instead of `increase()`:\n``` promql\n# Correct\nsum(sum_over_time(claude_code_lines_of_code_count_total[$__range]))\n\n# Wrong - will give weird extrapolated values\nsum(increase(claude_code_lines_of_code_count_total[$__range]))\n```\n\n## 7. Troubleshooting\n\n### No metrics showing up\n\n1. Check env vars are set: `env | grep OTEL`\n2. Verify Prometheus is running with OTLP flags: `ps aux | grep prometheus`\n3. Check Prometheus logs for OTLP errors\n4. Make sure you've used Claude Code after setting env vars (restart terminal first)\n\n### Grafana can't connect to Prometheus\n\n1. Verify Prometheus is running: `curl http://localhost:9090/-/healthy`\n2. Check Grafana data source URL matches Prometheus listen address\n\n### Dashboard shows no data\n\n1. Check time range (try \"Last 24 hours\")\n2. Verify metrics exist: `curl 'http://localhost:9090/api/v1/query?query=claude_code_token_usage_tokens_total'`\n3. Make sure Prometheus data source is selected in dashboard\n\n## 8. For Datadog (Alternative)\n\nIf pushing to Datadog instead of local Prometheus:\n\n``` bash\nexport OTEL_METRICS_EXPORTER=otlp\nexport OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\nexport OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.datadoghq.com\nexport OTEL_EXPORTER_OTLP_HEADERS=\"DD-API-KEY=your_api_key\"\n```\n\nThe same metrics will flow to Datadog, and you can build similar dashboards there.\n", "url": "https://wpnews.pro/news/claude-code-metrics-setup-prometheus-grafana-dashboards-for-tracking-ai-coding", "canonical_source": "https://gist.github.com/mikelane/9bf3053b5608df5858d299d636a48e8f", "published_at": "2025-12-12 21:19:55+00:00", "updated_at": "2026-05-22 06:08:49.759799+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "open-source", "data"], "entities": ["Claude Code", "Prometheus", "Grafana", "OTEL", "OTLP"], "alternates": {"html": "https://wpnews.pro/news/claude-code-metrics-setup-prometheus-grafana-dashboards-for-tracking-ai-coding", "markdown": "https://wpnews.pro/news/claude-code-metrics-setup-prometheus-grafana-dashboards-for-tracking-ai-coding.md", "text": "https://wpnews.pro/news/claude-code-metrics-setup-prometheus-grafana-dashboards-for-tracking-ai-coding.txt", "jsonld": "https://wpnews.pro/news/claude-code-metrics-setup-prometheus-grafana-dashboards-for-tracking-ai-coding.jsonld"}}