How anthropics/claude-code-monitoring-guide works
1. What this repository is
- This is not an application runtime; it is a measurement and reporting stack for evaluating the ROI of Claude Code in an engineering org.
- The repo combines documentation, telemetry configuration, dashboard provisioning, and report-generation artifacts.
2. Overall architecture
- The core flow is: Claude Code usage/activity data → OpenTelemetry collection → Prometheus storage → Grafana visualization → ROI/reporting outputs.
- A separate reporting path uses the collected metrics plus developer activity signals to produce narrative productivity summaries.
3. Telemetry ingestion layer
- otel-collector-config.yaml is the central boundary for telemetry intake and normalization.
- This is where Claude Code-related metrics would be received, processed, and exported into the metrics backend in a standardized format.
4. Metrics backend
- prometheus.yml defines the Prometheus side of the stack.
- Prometheus is the time-series datastore and query engine for the ROI metrics: cost, token usage, session behavior, and productivity signals.
5. Visualization and dashboards
- The grafana/ directory contains the visualization layer.
- grafana/provisioning/dashboards/dashboards.yaml and grafana/dashboards/working-dashboard.json indicate Grafana is pre-provisioned with a dashboard definition rather than configured manually at runtime.
6. Deployment/runtime composition
- docker-compose.yml ties the stack together as a local or self-hosted observability environment.
- This is the orchestration boundary for bringing up the collector, Prometheus, and Grafana as a single system.
7. Metric domains modeled by the repo
- The README makes the tracked domains explicit: cost metrics, token usage, productivity metrics, and team analytics.
- Example signals include total spend, cost per session, input/output tokens, cache efficiency, PR count, commit frequency, session duration, and adoption by developer.
8. Reporting workflow
- report-generation-prompt.md and sample-report-output.md form a separate reporting subsystem.
- The intended flow is to combine telemetry-derived metrics with organizational context to generate human-readable ROI and productivity reports, including integration with Linear per the README.
9. Documentation as a first-class component
- claude_code_roi_full.md is the main implementation guide and effectively the authoritative design document.
- troubleshooting.md captures operational knowledge for diagnosing setup/collection/dashboard issues.
10. Supporting assets
- screenshots/ and the sample report files are evidence and reference artifacts, not runtime dependencies.
- They help explain expected dashboard/report outputs and are useful when drawing the “observability + reporting” parts of the architecture.
11. Important boundary to capture in a diagram
- The repo’s main separation is between data collection/metrics infrastructure and analysis/reporting.
- Prometheus/Grafana handle continuous measurement and visualization, while the prompt/sample-report artifacts support periodic, narrative ROI synthesis.
12. External systems implied by the design
- The stack is centered on Prometheus, Grafana, and OpenTelemetry.
- The reporting story also implies external organizational data sources such as Linear and developer activity signals like PRs/commits, which feed the ROI analysis but are not implemented as application code here.
Main entry points: prometheus.yml Prometheus · grafana Grafana · docker-compose.yml Compose · claude_code_roi_full.md Full guide
Components 16
Observability stack
Telemetry collection, storage, and visualization for Claude Code ROI metrics.
- Compose · Brings up the local/self-hosted observability stack as a single environment.
docker-compose.yml - Collector · OpenTelemetry intake and normalization boundary for Claude Code-related metrics.
otel-collector-config.yaml - Prometheus · Time-series storage and query backend for cost, token, session, and productivity signals.
prometheus.yml - Grafana · Dashboard layer for ROI and productivity views.
grafana - Dashboard provisioning · Preloads Grafana dashboard definitions at startup.
grafana/provisioning/dashboards/dashboards.yaml - Working dashboard · Prebuilt Grafana dashboard for monitoring Claude Code ROI metrics.
grafana/dashboards/working-dashboard.json - Metric domains · Modeled signals such as cost, token usage, productivity, and team analytics.
- Usage signals · Claude Code activity and developer events that become observable metrics.
Reporting workflow
Narrative ROI synthesis from collected metrics and organizational activity signals.
- Report prompt · Instructions for generating human-readable ROI and productivity summaries.
report-generation-prompt.md - Sample report · Example narrative output showing the expected reporting format.
sample-report-output.md - Org context · External organizational context used in reporting, including systems like Linear.
- Dev activity · Supporting productivity inputs such as PRs, commits, and session behavior.
Reference material
Implementation guide, troubleshooting notes, and sample outputs used to understand and validate the stack.
- Overview · Top-level repository overview and orientation.
README.md - Full guide · Authoritative design and implementation guide for the monitoring stack.
claude_code_roi_full.md - Troubleshooting · Operational guidance for setup, collection, and dashboard issues.
troubleshooting.md - Screenshots · Visual evidence and reference artifacts for dashboards and reports.
screenshots
Connections 20
- Compose → Collector: starts · Compose launches the telemetry collector alongside the rest of the stack.
- Compose → Prometheus: starts · Compose brings up the metrics backend.
- Compose → Grafana: starts · Compose brings up the visualization layer.
- Usage signals → Collector: ingested by · Claude Code and developer activity signals enter via the collector boundary.
- Collector → Prometheus: exports · Collector normalizes and forwards metrics into Prometheus.
- Metric domains → Prometheus: queried from · Prometheus stores the ROI metric domains for analysis and dashboards.
- Prometheus → Grafana: visualized in · Grafana queries Prometheus to render ROI and productivity dashboards.
- Dashboard provisioning → Grafana: provisions · Dashboard provisioning loads the dashboard definition into Grafana.
- Working dashboard → Grafana: defines · The dashboard JSON is the concrete view shown in Grafana.
- Usage signals → Metric domains: populate · Raw usage and activity signals feed the modeled metric domains.
- Report prompt → Sample report: produces · The prompt template is used to generate narrative ROI reports.
- Prometheus → Report prompt: feeds metrics · Collected metrics are inputs to the reporting workflow.
- Org context → Report prompt: adds context · External organizational context enriches the narrative report.
- Dev activity → Report prompt: adds signals · Developer activity signals inform productivity summaries.
- Full guide → Collector: documents · The implementation guide explains collector configuration and data flow.
- Full guide → Prometheus: documents · The implementation guide covers the metrics backend and queries.
- Full guide → Grafana: documents · The implementation guide covers dashboard provisioning and usage.
- Overview → Full guide: points to · The README orients readers to the full design document.
- Troubleshooting → Compose: supports · Troubleshooting helps diagnose orchestration and runtime issues.
- Screenshots → Working dashboard: illustrates · Screenshots provide visual references for the expected dashboard output.