Initial commit

skills/otel-monitoring-setup/dashboards/README.md

@@ -0,0 +1,160 @@
+# Grafana Dashboard Templates
+
+This directory contains pre-configured Grafana dashboards for Claude Code telemetry.
+
+## Available Dashboards
+
+### 1. claude-code-overview.json
+**Comprehensive dashboard with all key metrics**
+
+**Panels:**
+- Total Lines of Code (all-time counter)
+- Total Cost (24h rolling window)
+- Total Tokens (24h rolling window)
+- Active Time (24h rolling window)
+- Cost Over Time (per hour rate)
+- Token Usage by Type (stacked timeseries)
+- Lines of Code Modified (bar chart)
+- Commits Created (24h counter)
+
+**Metrics Used:**
+- `claude_code_claude_code_lines_of_code_count_total`
+- `claude_code_claude_code_cost_usage_USD_total`
+- `claude_code_claude_code_token_usage_tokens_total`
+- `claude_code_claude_code_active_time_seconds_total`
+- `claude_code_claude_code_commit_count_total`
+
+**Note:** This dashboard uses the correct double-prefix metric names.
+
+### 2. claude-code-simple.json
+**Simplified dashboard for quick overview**
+
+**Panels:**
+- Active Sessions
+- Total Cost (24h)
+- Total Tokens (24h)
+- Active Time (24h)
+- Cost Over Time
+- Token Usage by Type
+
+**Use Case:** Lightweight dashboard for basic monitoring without detailed breakdowns.
+
+## Importing Dashboards
+
+### Method 1: Grafana UI (Recommended)
+
+1. Access Grafana: http://localhost:3000
+2. Login with admin/admin
+3. Go to: Dashboards → New → Import
+4. Click "Upload JSON file"
+5. Select the dashboard JSON file
+6. Click "Import"
+
+### Method 2: Grafana API
+
+```bash
+# Get the datasource UID first
+DATASOURCE_UID=$(curl -s -u admin:admin http://localhost:3000/api/datasources | jq -r '.[] | select(.type=="prometheus") | .uid')
+
+# Update dashboard with correct UID
+cat claude-code-overview.json | jq --arg uid "$DATASOURCE_UID" '
+  walk(if type == "object" and .datasource.type == "prometheus" then .datasource.uid = $uid else . end)
+' > dashboard-updated.json
+
+# Import dashboard
+curl -X POST http://localhost:3000/api/dashboards/db \
+  -u admin:admin \
+  -H "Content-Type: application/json" \
+  -d @dashboard-updated.json
+```
+
+## Datasource UID Configuration
+
+**Important:** The dashboards have a hardcoded Prometheus datasource UID: `PBFA97CFB590B2093`
+
+If your Grafana instance has a different UID, you need to replace it:
+
+```bash
+# Find your datasource UID
+curl -s -u admin:admin http://localhost:3000/api/datasources | jq '.[] | select(.type=="prometheus") | {name, uid}'
+
+# Replace UID in dashboard
+YOUR_UID="YOUR_ACTUAL_UID_HERE"
+cat claude-code-overview.json | sed "s/PBFA97CFB590B2093/$YOUR_UID/g" > claude-code-overview-fixed.json
+
+# Import the fixed version
+```
+
+The skill handles this automatically during Mode 1 setup!
+
+## Customizing Dashboards
+
+### Adding Custom Panels
+
+Use these PromQL queries as templates:
+
+**Total Tokens by Model:**
+```promql
+sum by (model) (increase(claude_code_claude_code_token_usage_tokens_total[24h]))
+```
+
+**Cost per Session:**
+```promql
+increase(claude_code_claude_code_cost_usage_USD_total[24h])
+/
+increase(claude_code_claude_code_session_count_total[24h])
+```
+
+**Lines of Code per Hour:**
+```promql
+rate(claude_code_claude_code_lines_of_code_count_total[5m]) * 3600
+```
+
+**Average Session Duration:**
+```promql
+increase(claude_code_claude_code_active_time_seconds_total[24h])
+/
+increase(claude_code_claude_code_session_count_total[24h])
+```
+
+### Time Range Recommendations
+
+- **Real-time monitoring:** Last 15 minutes, 30s refresh
+- **Daily review:** Last 24 hours, 1m refresh
+- **Weekly analysis:** Last 7 days, 5m refresh
+- **Monthly reports:** Last 30 days, 15m refresh
+
+## Troubleshooting
+
+### Dashboard Shows "No Data"
+
+1. **Check data source connection:**
+   ```bash
+   curl -s http://localhost:3000/api/health | jq .
+   ```
+
+2. **Verify Prometheus has data:**
+   ```bash
+   curl -s 'http://localhost:9090/api/v1/label/__name__/values' | jq . | grep claude_code
+   ```
+
+3. **Check metric naming:**
+   - Ensure queries use double prefix: `claude_code_claude_code_*`
+   - Not single prefix: `claude_code_*`
+
+### Dashboard Shows "Datasource Not Found"
+
+- Your datasource UID doesn't match the dashboard
+- Follow the "Datasource UID Configuration" section above
+
+### Panels Show Different Time Ranges
+
+- Set dashboard time range at top-right
+- Individual panels inherit from dashboard unless overridden
+- Check panel settings: Edit → Query Options → Time Range
+
+## Additional Resources
+
+- **Metric Reference:** See `../data/metrics-reference.md`
+- **PromQL Queries:** See `../data/prometheus-queries.md`
+- **Grafana Docs:** https://grafana.com/docs/grafana/latest/