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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
docs(metrics): ship an importable Grafana dashboard (#2168)
Matthew Jackson6bdc8c44a34d
diff --git a/docs/content/docs/metrics.mdx b/docs/content/docs/metrics.mdxindex 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.jsonnew file mode 100644index 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"+ }+ ]+}