Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

docs(metrics): ship an importable Grafana dashboard (#2168)

Matthew Jackson6bdc8c44a34d
diff --git a/docs/content/docs/metrics.mdx b/docs/content/docs/metrics.mdx
index 0318d9273..1439c6861 100644
--- a/docs/content/docs/metrics.mdx
+++ b/docs/content/docs/metrics.mdx
@@ -265,7 +265,14 @@ When the budget is exceeded, requests return a budget exceeded error, the `/stat
## Grafana Dashboard
-Example Prometheus queries for a Grafana dashboard:
+A ready-to-import dashboard ships in
+[`examples/grafana/headroom-dashboard.json`](https://github.com/headroomlabs-ai/headroom/blob/main/examples/grafana/headroom-dashboard.json).
+Import it in Grafana (**Dashboards → New → Import → Upload**) and pick your Prometheus
+datasource — it renders tokens saved, request throughput, and processing overhead
+(`headroom_overhead_ms_sum` / `headroom_overhead_ms_count`) straight from the metrics
+the `/metrics` endpoint exposes.
+
+Example ad-hoc queries against the same metric family:
| Panel | PromQL |
|-------|--------|
diff --git a/examples/grafana/headroom-dashboard.json b/examples/grafana/headroom-dashboard.json
new file mode 100644
index 000000000..8f00989da
--- /dev/null
+++ b/examples/grafana/headroom-dashboard.json
@@ -0,0 +1,368 @@
+{
+ "__note": "Headroom compression dashboard. Built on the headroom_* Prometheus metrics exposed at GET /metrics (verified against the running proxy): counters for requests/tokens and the headroom_overhead_ms_* millisecond summary. No histograms are used because the proxy emits none. The pool/source template variables use regex matchers (=~) so they are optional: they match series with no such label as well, and let multi-tenant scrapers that add a per-source label filter by it. Import: Grafana -> Dashboards -> New -> Import -> Upload this file, then pick your Prometheus datasource.",
+ "annotations": {
+ "list": [
+ {
+ "builtIn": 1,
+ "datasource": { "type": "grafana", "uid": "-- Grafana --" },
+ "enable": true,
+ "hide": true,
+ "iconColor": "rgba(0, 211, 255, 1)",
+ "name": "Annotations & Alerts",
+ "type": "dashboard"
+ }
+ ]
+ },
+ "description": "Tokens saved, request throughput, and processing overhead for the Headroom compression proxy, read from the headroom_* Prometheus metrics.",
+ "editable": true,
+ "fiscalYearStartMonth": 0,
+ "graphTooltip": 1,
+ "id": null,
+ "links": [],
+ "liveNow": false,
+ "refresh": "30s",
+ "schemaVersion": 39,
+ "tags": ["headroom", "compression", "llm"],
+ "templating": {
+ "list": [
+ {
+ "current": {},
+ "hide": 0,
+ "includeAll": false,
+ "label": "Datasource",
+ "multi": false,
+ "name": "datasource",
+ "options": [],
+ "query": "prometheus",
+ "refresh": 1,
+ "regex": "",
+ "type": "datasource"
+ },
+ {
+ "allValue": ".*",
+ "current": { "text": "All", "value": "$__all" },
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "definition": "label_values(headroom_requests_total, pool)",
+ "hide": 0,
+ "includeAll": true,
+ "label": "Pool",
+ "multi": true,
+ "name": "pool",
+ "options": [],
+ "query": { "query": "label_values(headroom_requests_total, pool)", "refId": "PoolQuery" },
+ "refresh": 2,
+ "regex": "",
+ "sort": 1,
+ "type": "query"
+ },
+ {
+ "allValue": ".*",
+ "current": { "text": "All", "value": "$__all" },
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "definition": "label_values(headroom_requests_total, hook)",
+ "description": "Optional. Present when a multi-tenant scraper re-exposes headroom_* with a per-source 'hook' label; empty against Headroom's own /metrics.",
+ "hide": 0,
+ "includeAll": true,
+ "label": "Source",
+ "multi": true,
+ "name": "hook",
+ "options": [],
+ "query": { "query": "label_values(headroom_requests_total, hook)", "refId": "HookQuery" },
+ "refresh": 2,
+ "regex": "",
+ "sort": 1,
+ "type": "query"
+ }
+ ]
+ },
+ "time": { "from": "now-6h", "to": "now" },
+ "timepicker": {},
+ "timezone": "",
+ "title": "Headroom — Compression",
+ "uid": "headroom-compression",
+ "version": 1,
+ "weekStart": "",
+ "panels": [
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "description": "Input tokens saved by compression since the process started.",
+ "fieldConfig": {
+ "defaults": {
+ "color": { "mode": "thresholds" },
+ "mappings": [],
+ "thresholds": { "mode": "absolute", "steps": [{ "color": "green", "value": null }] },
+ "unit": "short"
+ },
+ "overrides": []
+ },
+ "gridPos": { "h": 4, "w": 6, "x": 0, "y": 0 },
+ "id": 1,
+ "options": {
+ "colorMode": "value",
+ "graphMode": "area",
+ "justifyMode": "auto",
+ "orientation": "auto",
+ "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
+ "textMode": "auto"
+ },
+ "pluginVersion": "10.4.0",
+ "targets": [
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "sum(headroom_tokens_saved_total{pool=~\"$pool\", hook=~\"$hook\"})",
+ "legendFormat": "Tokens saved",
+ "refId": "A"
+ }
+ ],
+ "title": "Tokens Saved",
+ "type": "stat"
+ },
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "description": "Total input tokens seen.",
+ "fieldConfig": {
+ "defaults": {
+ "color": { "mode": "thresholds" },
+ "mappings": [],
+ "thresholds": { "mode": "absolute", "steps": [{ "color": "blue", "value": null }] },
+ "unit": "short"
+ },
+ "overrides": []
+ },
+ "gridPos": { "h": 4, "w": 6, "x": 6, "y": 0 },
+ "id": 2,
+ "options": {
+ "colorMode": "value",
+ "graphMode": "area",
+ "justifyMode": "auto",
+ "orientation": "auto",
+ "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
+ "textMode": "auto"
+ },
+ "pluginVersion": "10.4.0",
+ "targets": [
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "sum(headroom_tokens_input_total{pool=~\"$pool\", hook=~\"$hook\"})",
+ "legendFormat": "Input tokens",
+ "refId": "A"
+ }
+ ],
+ "title": "Input Tokens",
+ "type": "stat"
+ },
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "description": "Requests processed per second.",
+ "fieldConfig": {
+ "defaults": {
+ "color": { "mode": "thresholds" },
+ "mappings": [],
+ "thresholds": { "mode": "absolute", "steps": [{ "color": "purple", "value": null }] },
+ "unit": "reqps"
+ },
+ "overrides": []
+ },
+ "gridPos": { "h": 4, "w": 6, "x": 12, "y": 0 },
+ "id": 3,
+ "options": {
+ "colorMode": "value",
+ "graphMode": "area",
+ "justifyMode": "auto",
+ "orientation": "auto",
+ "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
+ "textMode": "auto"
+ },
+ "pluginVersion": "10.4.0",
+ "targets": [
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "sum(rate(headroom_requests_total{pool=~\"$pool\", hook=~\"$hook\"}[$__rate_interval]))",
+ "legendFormat": "req/s",
+ "refId": "A"
+ }
+ ],
+ "title": "Request Rate",
+ "type": "stat"
+ },
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "description": "Mean Headroom processing overhead — overhead_ms_sum / overhead_ms_count over the window.",
+ "fieldConfig": {
+ "defaults": {
+ "color": { "mode": "thresholds" },
+ "mappings": [],
+ "thresholds": {
+ "mode": "absolute",
+ "steps": [
+ { "color": "green", "value": null },
+ { "color": "yellow", "value": 5 },
+ { "color": "red", "value": 25 }
+ ]
+ },
+ "unit": "ms"
+ },
+ "overrides": []
+ },
+ "gridPos": { "h": 4, "w": 6, "x": 18, "y": 0 },
+ "id": 4,
+ "options": {
+ "colorMode": "value",
+ "graphMode": "area",
+ "justifyMode": "auto",
+ "orientation": "auto",
+ "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false },
+ "textMode": "auto"
+ },
+ "pluginVersion": "10.4.0",
+ "targets": [
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "sum(rate(headroom_overhead_ms_sum{pool=~\"$pool\", hook=~\"$hook\"}[$__rate_interval])) / clamp_min(sum(rate(headroom_overhead_ms_count{pool=~\"$pool\", hook=~\"$hook\"}[$__rate_interval])), 1)",
+ "legendFormat": "mean overhead",
+ "refId": "A"
+ }
+ ],
+ "title": "Avg Overhead",
+ "type": "stat"
+ },
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "description": "Tokens saved per second, split by pool when a per-pool label is present.",
+ "fieldConfig": {
+ "defaults": {
+ "color": { "mode": "palette-classic" },
+ "custom": {
+ "axisCenteredZero": false,
+ "axisColorMode": "text",
+ "axisLabel": "",
+ "axisPlacement": "auto",
+ "drawStyle": "line",
+ "fillOpacity": 15,
+ "gradientMode": "opacity",
+ "lineInterpolation": "smooth",
+ "lineWidth": 2,
+ "pointSize": 5,
+ "showPoints": "never",
+ "spanNulls": true,
+ "stacking": { "group": "A", "mode": "normal" }
+ },
+ "unit": "short"
+ },
+ "overrides": []
+ },
+ "gridPos": { "h": 8, "w": 12, "x": 0, "y": 4 },
+ "id": 5,
+ "options": {
+ "legend": { "calcs": ["sum"], "displayMode": "table", "placement": "bottom", "showLegend": true },
+ "tooltip": { "mode": "multi", "sort": "desc" }
+ },
+ "targets": [
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "sum(rate(headroom_tokens_saved_total{pool=~\"$pool\", hook=~\"$hook\"}[$__rate_interval])) by (pool)",
+ "legendFormat": "{{pool}}",
+ "refId": "A"
+ }
+ ],
+ "title": "Tokens Saved / sec",
+ "type": "timeseries"
+ },
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "description": "Headroom processing overhead in milliseconds: mean (overhead_ms_sum/overhead_ms_count) with the reported min and max.",
+ "fieldConfig": {
+ "defaults": {
+ "color": { "mode": "palette-classic" },
+ "custom": {
+ "axisCenteredZero": false,
+ "axisColorMode": "text",
+ "axisLabel": "",
+ "axisPlacement": "auto",
+ "drawStyle": "line",
+ "fillOpacity": 8,
+ "gradientMode": "none",
+ "lineInterpolation": "smooth",
+ "lineWidth": 2,
+ "pointSize": 5,
+ "showPoints": "never",
+ "spanNulls": true,
+ "stacking": { "group": "A", "mode": "none" }
+ },
+ "unit": "ms"
+ },
+ "overrides": []
+ },
+ "gridPos": { "h": 8, "w": 12, "x": 12, "y": 4 },
+ "id": 6,
+ "options": {
+ "legend": { "calcs": ["mean", "max"], "displayMode": "table", "placement": "bottom", "showLegend": true },
+ "tooltip": { "mode": "multi", "sort": "desc" }
+ },
+ "targets": [
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "sum(rate(headroom_overhead_ms_sum{pool=~\"$pool\", hook=~\"$hook\"}[$__rate_interval])) / clamp_min(sum(rate(headroom_overhead_ms_count{pool=~\"$pool\", hook=~\"$hook\"}[$__rate_interval])), 1)",
+ "legendFormat": "mean",
+ "refId": "A"
+ },
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "max(headroom_overhead_ms_max{pool=~\"$pool\", hook=~\"$hook\"})",
+ "legendFormat": "max",
+ "refId": "B"
+ },
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "min(headroom_overhead_ms_min{pool=~\"$pool\", hook=~\"$hook\"})",
+ "legendFormat": "min",
+ "refId": "C"
+ }
+ ],
+ "title": "Processing Overhead",
+ "type": "timeseries"
+ },
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "description": "Request throughput split by pool (when a per-pool label is present).",
+ "fieldConfig": {
+ "defaults": {
+ "color": { "mode": "palette-classic" },
+ "custom": {
+ "axisCenteredZero": false,
+ "axisColorMode": "text",
+ "axisLabel": "",
+ "axisPlacement": "auto",
+ "drawStyle": "line",
+ "fillOpacity": 15,
+ "gradientMode": "opacity",
+ "lineInterpolation": "smooth",
+ "lineWidth": 2,
+ "pointSize": 5,
+ "showPoints": "never",
+ "spanNulls": true,
+ "stacking": { "group": "A", "mode": "normal" }
+ },
+ "unit": "reqps"
+ },
+ "overrides": []
+ },
+ "gridPos": { "h": 8, "w": 24, "x": 0, "y": 12 },
+ "id": 7,
+ "options": {
+ "legend": { "calcs": ["mean"], "displayMode": "table", "placement": "bottom", "showLegend": true },
+ "tooltip": { "mode": "multi", "sort": "desc" }
+ },
+ "targets": [
+ {
+ "datasource": { "type": "prometheus", "uid": "${datasource}" },
+ "expr": "sum(rate(headroom_requests_total{pool=~\"$pool\", hook=~\"$hook\"}[$__rate_interval])) by (pool)",
+ "legendFormat": "{{pool}}",
+ "refId": "A"
+ }
+ ],
+ "title": "Request Rate by Pool",
+ "type": "timeseries"
+ }
+ ]
+}