{"id":51329860,"url":"https://github.com/neeltom92/claude-code-observability","last_synced_at":"2026-07-01T22:03:32.092Z","repository":{"id":365577798,"uuid":"1272708938","full_name":"neeltom92/claude-code-observability","owner":"neeltom92","description":"One-command local observability stack for Claude Code — Prometheus + Grafana + Loki + OTEL Collector with pre-built cost, token, session, tool \u0026 skills dashboards. ","archived":false,"fork":false,"pushed_at":"2026-06-18T00:11:40.000Z","size":774,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T01:19:54.067Z","etag":null,"topics":["claude-code","docker","grafana","loki","observability","opentelemetry","prometheus"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neeltom92.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-06-17T21:36:16.000Z","updated_at":"2026-06-18T00:11:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/neeltom92/claude-code-observability","commit_stats":null,"previous_names":["neeltom92/claude-code-observability"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/neeltom92/claude-code-observability","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neeltom92%2Fclaude-code-observability","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neeltom92%2Fclaude-code-observability/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neeltom92%2Fclaude-code-observability/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neeltom92%2Fclaude-code-observability/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neeltom92","download_url":"https://codeload.github.com/neeltom92/claude-code-observability/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neeltom92%2Fclaude-code-observability/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35024367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-code","docker","grafana","loki","observability","opentelemetry","prometheus"],"created_at":"2026-07-01T22:03:31.460Z","updated_at":"2026-07-01T22:03:32.086Z","avatar_url":"https://github.com/neeltom92.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code — Local Observability Stack (Docker)\n\nOne command spins up a full local observability stack for [Claude Code](https://claude.com/claude-code) — **Prometheus + Grafana + Loki + OTEL Collector** — with pre-built dashboards for cost, tokens, sessions, tool usage, and skills usage. Everything runs in Docker; nothing touches your system package manager.\n\nBuilt and tested on **macOS (Apple Silicon) + Docker Desktop**.\n\n## Demo\n\nhttps://github.com/user-attachments/assets/0cd0e2a5-0f8a-4f41-a313-0322ba55fda9\n\n## Screenshots\n\n**Claude Code** — cost, tokens, sessions, active time, code churn:\n\n![Claude Code dashboard](docs/screenshots/claude-code-dashboard.png)\n\n**Model Usage** — per-model cost, token, and efficiency breakdown:\n\n![Model Usage dashboard](docs/screenshots/model-usage-dashboard.png)\n\n**Skills Usage** — skill/tool invocation events from Loki:\n\n![Skills Usage dashboard](docs/screenshots/skills-usage-dashboard.png)\n\n## Quickstart\n\n```bash\ngit clone https://github.com/neeltom92/claude-code-observability.git\ncd claude-code-observability\nmake up\n```\n\nThat single command:\n\n1. **Preflights** — checks Docker is installed and running, `docker compose` is available, and the host ports are free. If Docker is missing it prints install guidance and stops.\n2. **Patches Claude Code** — adds the OTEL env vars to `~/.claude/settings.json` so Claude Code exports telemetry to the local collector.\n3. **Starts the stack** — `docker compose up -d` (4 containers).\n4. **Verifies health** — polls every service and reports per-service status.\n5. **Prints the URLs.**\n\nThen **restart Claude Code** so the new env vars take effect, and open \u003chttp://localhost:3000\u003e.\n\n## Is it running? (no install needed)\n\n```bash\nmake check\n```\n\nProbes Grafana, OTEL collector, Loki, and Prometheus on their host ports and reports `✓`/`✗` per service — without starting anything. Use it to confirm the stack is healthy or diagnose what's down.\n\n## Targets\n\n| Target | What it does |\n|---|---|\n| `make up` | Preflight → patch Claude settings → start → verify → print URLs |\n| `make check` | Health-check each service without starting the stack |\n| `make status` | `docker compose ps` + one-shot health report |\n| `make logs` | Tail logs from all services |\n| `make restart` | Restart all services |\n| `make down` | Stop the stack (keeps data volumes) |\n| `make clean` | Stop, **delete data volumes**, and revert the Claude settings patch |\n| `make patch` / `make unpatch` | Apply / remove the Claude OTEL settings patch only |\n| `make config` | Validate + render the compose config |\n| `make pull` | Pull the pinned images |\n\nRun `make` (or `make help`) for the full list.\n\n## Architecture\n\n```\nClaude Code (host) --OTLP/HTTP--\u003e localhost:4318 --\u003e otel-collector\n   otel-collector --prometheus exporter--\u003e :8889  (scraped by Prometheus)\n   otel-collector --OTLP logs--\u003e loki:3100/otlp\n   Grafana --query--\u003e prometheus:9090  and  loki:3100\n```\n\n| Service | Host port | Purpose |\n|---|---|---|\n| OTEL Collector | 4317 (gRPC), 4318 (HTTP), 8889 (prom) | Receives Claude Code telemetry; exports metrics to Prometheus, logs to Loki |\n| Prometheus | 9090 | Stores metrics (30d retention) |\n| Loki | 3100 | Stores per-invocation skill/tool events (30d retention) |\n| Grafana | 3000 | Dashboards (anonymous Viewer; `admin`/`admin` to edit) |\n\nAll ports bind to `127.0.0.1` only — the stack is not exposed beyond your machine.\n\n## Dashboards\n\n- **Claude Code** — cost, tokens, sessions, code churn, tool decisions: \u003chttp://localhost:3000/d/claude-code-metrics\u003e\n- **Model Usage** — per-model cost/token deep dive: \u003chttp://localhost:3000/d/claude-code-deep-usage\u003e\n- **Skills Usage** — skill/tool invocation events from Loki: \u003chttp://localhost:3000/d/claude-code-skills\u003e\n\n## Privacy note\n\n`OTEL_LOG_TOOL_DETAILS=1` (set by the settings patch) stores tool/skill names and input args — **including Bash command lines** — in your local Loki instance. This is loopback-only and never leaves your machine. Remove that key from `~/.claude/settings.json` (or run `make unpatch`) to disable event detail.\n\n## Uninstall\n\n```bash\nmake clean   # stops containers, deletes volumes, reverts Claude settings\n```\n\nThen restart Claude Code.\n\n## Notes\n\n- Image tags are pinned to known-good versions in `docker-compose.yml`. For stricter supply-chain hardening, replace each tag with its multi-arch digest (`image@sha256:...`).\n- This repo is self-contained — clone it anywhere and `make up`.\n- `make up` writes OTEL env vars into `~/.claude/settings.json`. A timestamped backup (`settings.json.bak.\u003cts\u003e`) is made before any change. Review `scripts/patch-claude-settings.py` first; `make unpatch` reverts them.\n\n## Contributing\n\nIssues and PRs welcome. Keep it boring and self-contained — no extra runtime dependencies beyond Docker.\n\n## License\n\n[Apache-2.0](LICENSE) © Neel Thomas\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneeltom92%2Fclaude-code-observability","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneeltom92%2Fclaude-code-observability","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneeltom92%2Fclaude-code-observability/lists"}