# anthropics/claude-code-monitoring-guide architecture

> Architecture diagram of the GitHub repository anthropics/claude-code-monitoring-guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anthropics/claude-code-monitoring-guide
- Repository: https://github.com/anthropics/claude-code-monitoring-guide

## Overview

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`](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/prometheus.yml) (Prometheus), [`grafana`](https://github.com/anthropics/claude-code-monitoring-guide/tree/main/grafana) (Grafana), [`docker-compose.yml`](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/docker-compose.yml) (Compose), [`claude_code_roi_full.md`](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/claude_code_roi_full.md) (Full guide)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_observability["Observability stack"]
  node_n_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
  node_n_otel["Collector<br/>otel-config"]
  node_n_prometheus[("Prometheus<br/>metrics-store<br/>[prometheus.yml]")]
  node_n_grafana["Grafana<br/>visualization"]
  node_n_dash_prov["Dashboard provisioning<br/>grafana-provisioning<br/>[dashboards.yaml]"]
  node_n_dashboard["Working dashboard<br/>grafana-dashboard"]
  node_n_metric_domain{{"Metric domains<br/>roi-model"}}
  node_n_usage_signals(("Usage signals<br/>activity-data"))
end

subgraph group_g_reporting["Reporting workflow"]
  node_n_report_prompt["Report prompt<br/>report-template"]
  node_n_sample_report["Sample report<br/>report-example"]
  node_n_org_context(("Org context<br/>external-data"))
  node_n_dev_activity(("Dev activity<br/>external-signals"))
end

subgraph group_g_reference["Reference material"]
  node_n_readme["Overview<br/>guide<br/>[README.md]"]
  node_n_full_guide["Full guide<br/>implementation-doc"]
  node_n_troubleshoot["Troubleshooting<br/>ops-notes<br/>[troubleshooting.md]"]
  node_n_screenshots["Screenshots<br/>reference-assets"]
end

node_n_compose -->|"starts"| node_n_otel
node_n_compose -->|"starts"| node_n_prometheus
node_n_compose -->|"starts"| node_n_grafana
node_n_usage_signals -->|"ingested by"| node_n_otel
node_n_otel -->|"exports"| node_n_prometheus
node_n_metric_domain -->|"queried from"| node_n_prometheus
node_n_prometheus -->|"visualized in"| node_n_grafana
node_n_dash_prov -->|"provisions"| node_n_grafana
node_n_dashboard -->|"defines"| node_n_grafana
node_n_usage_signals -->|"populate"| node_n_metric_domain
node_n_report_prompt -->|"produces"| node_n_sample_report
node_n_prometheus -->|"feeds metrics"| node_n_report_prompt
node_n_org_context -.->|"adds context"| node_n_report_prompt
node_n_dev_activity -.->|"adds signals"| node_n_report_prompt
node_n_full_guide -->|"documents"| node_n_otel
node_n_full_guide -->|"documents"| node_n_prometheus
node_n_full_guide -->|"documents"| node_n_grafana
node_n_readme -->|"points to"| node_n_full_guide
node_n_troubleshoot -.->|"supports"| node_n_compose
node_n_screenshots -.->|"illustrates"| node_n_dashboard

click node_n_compose "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/docker-compose.yml"
click node_n_otel "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/otel-collector-config.yaml"
click node_n_prometheus "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/prometheus.yml"
click node_n_grafana "https://github.com/anthropics/claude-code-monitoring-guide/tree/main/grafana"
click node_n_dash_prov "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/grafana/provisioning/dashboards/dashboards.yaml"
click node_n_dashboard "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/grafana/dashboards/working-dashboard.json"
click node_n_report_prompt "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/report-generation-prompt.md"
click node_n_sample_report "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/sample-report-output.md"
click node_n_readme "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/README.md"
click node_n_full_guide "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/claude_code_roi_full.md"
click node_n_troubleshoot "https://github.com/anthropics/claude-code-monitoring-guide/blob/main/troubleshooting.md"
click node_n_screenshots "https://github.com/anthropics/claude-code-monitoring-guide/tree/main/screenshots"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_compose,node_n_otel,node_n_prometheus,node_n_grafana,node_n_dash_prov,node_n_dashboard,node_n_metric_domain,node_n_usage_signals toneBlue
class node_n_report_prompt,node_n_sample_report,node_n_org_context,node_n_dev_activity toneAmber
class node_n_readme,node_n_full_guide,node_n_troubleshoot,node_n_screenshots toneMint
```

## Components

### Observability stack

Telemetry collection, storage, and visualization for Claude Code ROI metrics.

- [Compose](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/docker-compose.yml): orchestration · Brings up the local/self-hosted observability stack as a single environment. · `docker-compose.yml`
- [Collector](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/otel-collector-config.yaml): otel-config · OpenTelemetry intake and normalization boundary for Claude Code-related metrics. · `otel-collector-config.yaml`
- [Prometheus](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/prometheus.yml): metrics-store · Time-series storage and query backend for cost, token, session, and productivity signals. · `prometheus.yml`
- [Grafana](https://github.com/anthropics/claude-code-monitoring-guide/tree/main/grafana): visualization · Dashboard layer for ROI and productivity views. · `grafana`
- [Dashboard provisioning](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/grafana/provisioning/dashboards/dashboards.yaml): grafana-provisioning · Preloads Grafana dashboard definitions at startup. · `grafana/provisioning/dashboards/dashboards.yaml`
- [Working dashboard](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/grafana/dashboards/working-dashboard.json): grafana-dashboard · Prebuilt Grafana dashboard for monitoring Claude Code ROI metrics. · `grafana/dashboards/working-dashboard.json`
- **Metric domains**: roi-model · Modeled signals such as cost, token usage, productivity, and team analytics.
- **Usage signals**: activity-data · Claude Code activity and developer events that become observable metrics.

### Reporting workflow

Narrative ROI synthesis from collected metrics and organizational activity signals.

- [Report prompt](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/report-generation-prompt.md): report-template · Instructions for generating human-readable ROI and productivity summaries. · `report-generation-prompt.md`
- [Sample report](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/sample-report-output.md): report-example · Example narrative output showing the expected reporting format. · `sample-report-output.md`
- **Org context**: external-data · External organizational context used in reporting, including systems like Linear.
- **Dev activity**: external-signals · 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](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/README.md): guide · Top-level repository overview and orientation. · `README.md`
- [Full guide](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/claude_code_roi_full.md): implementation-doc · Authoritative design and implementation guide for the monitoring stack. · `claude_code_roi_full.md`
- [Troubleshooting](https://github.com/anthropics/claude-code-monitoring-guide/blob/main/troubleshooting.md): ops-notes · Operational guidance for setup, collection, and dashboard issues. · `troubleshooting.md`
- [Screenshots](https://github.com/anthropics/claude-code-monitoring-guide/tree/main/screenshots): reference-assets · Visual evidence and reference artifacts for dashboards and reports. · `screenshots`

## Connections

- 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.