{"id":46984709,"url":"https://github.com/halyph/claude-mon","last_synced_at":"2026-03-11T13:31:53.796Z","repository":{"id":339642706,"uuid":"1162784452","full_name":"halyph/claude-mon","owner":"halyph","description":"Claude Code Monitoring Stack","archived":false,"fork":false,"pushed_at":"2026-02-20T19:21:51.000Z","size":1635,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-20T23:20:05.992Z","etag":null,"topics":["claude","claude-code","grafana","loki","otel"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/halyph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T17:33:39.000Z","updated_at":"2026-02-20T19:21:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/halyph/claude-mon","commit_stats":null,"previous_names":["halyph/claude-mon"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/halyph/claude-mon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fclaude-mon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fclaude-mon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fclaude-mon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fclaude-mon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/halyph","download_url":"https://codeload.github.com/halyph/claude-mon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halyph%2Fclaude-mon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30382673,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T12:49:11.341Z","status":"ssl_error","status_checked_at":"2026-03-11T12:46:41.342Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","grafana","loki","otel"],"created_at":"2026-03-11T13:31:53.149Z","updated_at":"2026-03-11T13:31:53.790Z","avatar_url":"https://github.com/halyph.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Monitoring Stack\n\nMonitor Claude Code usage, costs, and performance using OpenTelemetry, Prometheus, Loki, and Grafana.\n\n\u003e **Tested with**: Claude Code CLI v2.1.38  \n\u003e **Environment**: macOS with Colima (Docker Desktop alternative)\n\n## ⚠️ Environment Note\n\nThis setup was developed and tested using [Colima](https://github.com/abiosoft/colima) on macOS. While it should work with Docker Desktop and other Docker environments, there may be networking or volume mounting differences. If you encounter issues on other platforms, please check your Docker configuration.\n\n## Architecture\n\n```mermaid\ngraph LR\n    A[Claude Code] --\u003e|OTLP gRPC :4317| B[OTel Collector]\n    B --\u003e|Metrics| C[Prometheus :9090]\n    B --\u003e|Logs| D[Loki :3100]\n    C --\u003e E[Grafana :3000]\n    D --\u003e E\n\n    style A fill:#4a9eff,stroke:#333,stroke-width:2px,color:#fff\n    style B fill:#f9ab00,stroke:#333,stroke-width:2px,color:#fff\n    style C fill:#e6522c,stroke:#333,stroke-width:2px,color:#fff\n    style D fill:#f46800,stroke:#333,stroke-width:2px,color:#fff\n    style E fill:#f05a28,stroke:#333,stroke-width:2px,color:#fff\n```\n\n## Dashboard Preview\n\n### Metrics Dashboard\n*URL: http://localhost:3000/d/claude-code-monitoring*\n\n| Panel | Preview |\n|-------|---------|\n| **Summary Statistics** | [![Summary Statistics](images/dashboard/metrics/01-dashboard-summary-stats.png)](images/dashboard/metrics/01-dashboard-summary-stats.png) |\n| **Time Series Analysis** | [![Time Series Analysis](images/dashboard/metrics/02-dashboard-time-series.png)](images/dashboard/metrics/02-dashboard-time-series.png) |\n| **Analysis \u0026 Efficiency** | [![Analysis and Efficiency](images/dashboard/metrics/03-dashboard-analysis-efficiency.png)](images/dashboard/metrics/03-dashboard-analysis-efficiency.png) |\n| **Session Details** | [![Session Details](images/dashboard/metrics/04-dashboard-session-details.png)](images/dashboard/metrics/04-dashboard-session-details.png) |\n| **Development Activity** | [![Development Activity](images/dashboard/metrics/05-dashboard-dev-activity.png)](images/dashboard/metrics/05-dashboard-dev-activity.png) |\n| **Development Trends** | [![Development Trends](images/dashboard/metrics/06-dashboard-dev-trends.png)](images/dashboard/metrics/06-dashboard-dev-trends.png) |\n\n### Logs Dashboard\n*URL: http://localhost:3000/d/claude-code-logs*\n\n| Panel | Preview | Description |\n|-------|---------|-------------|\n| **Log Overview** | [![Log Overview](images/dashboard/logs/01-logs-overview.png)](images/dashboard/logs/01-logs-overview.png) | Total entries, active sessions, log rate, distribution |\n| **Real-time Stream** | [![Real-time Log Stream](images/dashboard/logs/02-logs-stream.png)](images/dashboard/logs/02-logs-stream.png) | Live streaming log viewer |\n| **Log Analysis** | [![Log Analysis](images/dashboard/logs/03-logs-analysis.png)](images/dashboard/logs/03-logs-analysis.png) | Volume over time, rate by session |\n| **Session Details** | [![Session Details](images/dashboard/logs/04-logs-session-details.png)](images/dashboard/logs/04-logs-session-details.png) | Sessions table, activity by model |\n\n## Prerequisites\n\n- Docker and Docker Compose installed\n- Claude Code CLI v2.1+ installed\n- Port 3000, 3100, 4317, 8889, 9090 available\n\n## Quick Start\n\n### 1. Run Setup Script\n\n```bash\n./setup.sh\n```\n\nThis automatically:\n- Starts all services\n- Configures Grafana data sources\n- Imports metrics and logs dashboards\n\n### 2. Enable Telemetry\n\nEdit `~/.claude/settings.json`:\n\n```json\n{\n  \"env\": {\n    \"CLAUDE_CODE_ENABLE_TELEMETRY\": \"1\",\n    \"OTEL_METRICS_EXPORTER\": \"otlp\",\n    \"OTEL_LOGS_EXPORTER\": \"otlp\",\n    \"OTEL_EXPORTER_OTLP_PROTOCOL\": \"grpc\",\n    \"OTEL_EXPORTER_OTLP_ENDPOINT\": \"http://localhost:4317\"\n  }\n}\n```\n\nRestart Claude Code to apply changes.\n\n### 3. View Dashboards\n\nOpen Grafana dashboards:\n- **Metrics**: http://localhost:3000/d/claude-code-monitoring\n- **Logs**: http://localhost:3000/d/claude-code-logs\n\nGenerate some telemetry:\n\n```bash\nclaude \"test telemetry\"\n```\n\n## What's Tracked\n\n- **Token usage** - Input, output, cache reads/writes\n- **API costs** - Per model (Sonnet, Haiku, etc.)\n- **Session activity** - Active time, session count\n- **Cache efficiency** - Cache hit rates\n- **Development metrics** - Lines changed, commits, pull requests\n- **Code editing** - Tool decisions and outcomes\n- **Logs** - Real-time streaming logs with session-level analysis\n\n## Service URLs\n\n| Service | URL | Purpose |\n|---------|-----|---------|\n| Grafana | http://localhost:3000 | Dashboard UI |\n| Metrics Dashboard | http://localhost:3000/d/claude-code-monitoring | Token usage, costs, development activity |\n| Logs Dashboard | http://localhost:3000/d/claude-code-logs | Real-time log streaming and analysis |\n| Prometheus | http://localhost:9090 | Metrics query UI |\n| Loki | http://localhost:3100 | Logs API |\n\n## Common Commands\n\n```bash\n# Stop services (data preserved)\ndocker-compose down\n\n# Stop and delete all data\ndocker-compose down -v\n\n# View logs\ndocker-compose logs -f otel-collector\n\n# Restart services\ndocker-compose restart\n\n# Check status\ndocker-compose ps\n```\n\n## Data Persistence\n\nYour data is **automatically saved** in Docker volumes:\n- Metrics history (Prometheus)\n- Log history (Loki)\n- Dashboard settings (Grafana)\n\nData persists across restarts. To reset completely:\n```bash\ndocker-compose down -v\n./setup.sh\n```\n\n## Available Metrics\n\n\u003e [!TIP]\n\u003e **Official Documentation**: [Claude Code Monitoring \u0026 Usage](https://code.claude.com/docs/en/monitoring-usage)\n\n\n\u003e [!NOTE]\n\u003e Metric names below use Prometheus format (dots → underscores, counters get `_total` suffix). Original OpenTelemetry metric names use dots (e.g., `claude_code.cost.usage` becomes `claude_code_cost_usage_USD_total`).*\n\n\n| Metric | Description |\n|--------|-------------|\n| `claude_code_cost_usage_USD_total` | Total cost in USD |\n| `claude_code_token_usage_tokens_total` | Token count by type |\n| `claude_code_active_time_seconds_total` | Active session time |\n| `claude_code_session_count_total` | Number of sessions |\n| `claude_code_lines_of_code_count_total` | Lines of code changed (added/removed) |\n| `claude_code_pull_request_count_total` | Pull requests created via Claude Code |\n| `claude_code_commit_count_total` | Git commits created via Claude Code |\n| `claude_code_code_edit_tool_decision_total` | Code edit tool decisions (accept/reject) |\n\n### Example Prometheus Queries\n\n**Total spending:**\n```promql\nsum(claude_code_cost_usage_USD_total)\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\"}) +\n sum(claude_code_token_usage_tokens_total{type=\"input\"}))\n```\n\n**Cost per hour:**\n```promql\nrate(claude_code_cost_usage_USD_total[1h]) * 3600\n```\n\n## Troubleshooting\n\n### No data appearing?\n\n1. Verify telemetry is enabled:\n   ```bash\n   cat ~/.claude/settings.json\n   ```\n   Should show `CLAUDE_CODE_ENABLE_TELEMETRY: \"1\"`\n\n2. Check services are running:\n   ```bash\n   docker-compose ps\n   ```\n   All should show \"Up\"\n\n3. Check OTel Collector is receiving data:\n   ```bash\n   docker-compose logs otel-collector | grep -i received\n   ```\n\n4. Verify Prometheus is scraping:\n   ```bash\n   curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[].health'\n   ```\n\n### Port already in use?\n\nEdit `docker-compose.yml` and change port mappings:\n```yaml\nports:\n  - \"13000:3000\"  # Use 13000 instead of 3000\n```\n\n### Colima-specific issues?\n\n- Check Colima is running: `colima status`\n- Verify Docker socket: `docker ps`\n- Try restarting: `colima restart`\n\n### Dashboard shows \"No Data\"?\n\n1. Generate some telemetry: `claude \"echo test\"`\n2. Wait 10-15 seconds for data to propagate\n3. Check Prometheus has data: `curl -s http://localhost:8889/metrics | grep claude_code`\n\n## Security Note\n\n⚠️ This setup uses **anonymous admin access** in Grafana for ease of use. This is suitable for local development only. Do not expose these services to the internet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalyph%2Fclaude-mon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhalyph%2Fclaude-mon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalyph%2Fclaude-mon/lists"}