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.

feat(metrics): record per-extension token savings (#2371)

Tejas Chopra02eb90f24318
diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.py
index 97006376c..ef423c22a 100644
--- a/headroom/proxy/prometheus_metrics.py
+++ b/headroom/proxy/prometheus_metrics.py
@@ -117,6 +117,13 @@ class PrometheusMetrics:
self.compressions_by_strategy: dict[str, int] = defaultdict(int)
self.tokens_saved_by_strategy: dict[str, int] = defaultdict(int)
+ # Per-extension token savings, keyed by the extension-supplied
+ # ``key``. Populated lazily by ``record_extension_savings`` — no
+ # hardcoded list of extensions. Proxy extensions report the tokens
+ # they saved so per-extension contribution is observable via /stats,
+ # mirroring the per-strategy compression breakdown above.
+ self.extension_savings: dict[str, int] = defaultdict(int)
+
# Fail-open compression failures, keyed by reason ("timeout",
# "error"). The proxy fails open on any optimization error so the
# request still succeeds; without this counter the failure is only
@@ -321,6 +328,7 @@ class PrometheusMetrics:
self.compressions_by_strategy.clear()
self.tokens_saved_by_strategy.clear()
+ self.extension_savings.clear()
with self._obs_counter_lock:
self.compression_failed_by_reason.clear()
self.kompress_size_gate_by_outcome.clear()
@@ -483,6 +491,24 @@ class PrometheusMetrics:
if saved > 0:
self.tokens_saved_by_strategy[strategy] += saved
+ def record_extension_savings(self, key: str, saved: int) -> None:
+ """Accumulate tokens saved by a proxy extension, keyed by ``key``.
+
+ Called by proxy extensions that perform their own token
+ reduction and want that contribution surfaced alongside the
+ built-in compression metrics. The per-extension totals are
+ exposed via /stats (``extension_savings``), mirroring how
+ ``record_compression`` accumulates ``tokens_saved_by_strategy``.
+
+ Synchronous + lock-free: ``defaultdict(int)`` writes are atomic
+ under the GIL for these key types, matching ``record_compression``.
+
+ Non-positive ``saved`` values are ignored — the metric never
+ records "negative savings".
+ """
+ if saved > 0:
+ self.extension_savings[key] += saved
+
def record_compression_failed(self, reason: str) -> None:
"""Record one fail-open compression failure, bucketed by ``reason``.
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index abecfe245..0226a7a79 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -3817,6 +3817,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
else {},
"compressions_by_strategy": dict(m.compressions_by_strategy),
"tokens_saved_by_strategy": dict(m.tokens_saved_by_strategy),
+ "extension_savings": dict(m.extension_savings),
"codex_ws": {
"units_total": m.codex_ws_units_total,
"units_modified_total": m.codex_ws_units_modified_total,
diff --git a/tests/test_compression_observability.py b/tests/test_compression_observability.py
index 3491a6ceb..d7c66d4dc 100644
--- a/tests/test_compression_observability.py
+++ b/tests/test_compression_observability.py
@@ -33,6 +33,7 @@ Coverage:
from __future__ import annotations
from dataclasses import dataclass, field
+from pathlib import Path
from typing import Any
import pytest
@@ -273,6 +274,50 @@ def test_prometheus_metrics_accumulates_per_strategy_counters():
assert m.tokens_saved_by_strategy == {"smart_crusher": 210}
+def test_prometheus_metrics_accumulates_extension_savings_per_key() -> None:
+ from headroom.proxy.prometheus_metrics import PrometheusMetrics
+
+ m = PrometheusMetrics()
+
+ m.record_extension_savings("tool_router", 120)
+ m.record_extension_savings("tool_router", 30)
+ m.record_extension_savings("skill_search", 45)
+ m.record_extension_savings("skill_search", 0) # no savings, ignored
+ m.record_extension_savings("noop_ext", -10) # negative, ignored
+
+ # Savings accumulate per key; non-positive values never create or
+ # bump an entry.
+ assert m.extension_savings == {"tool_router": 150, "skill_search": 45}
+
+
+def test_extension_savings_surface_in_stats(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from fastapi.testclient import TestClient
+
+ from headroom.proxy.server import ProxyConfig, create_app
+
+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "proxy_savings.json"))
+ config = ProxyConfig(
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ log_requests=False,
+ )
+ app = create_app(config)
+ with TestClient(app) as client:
+ proxy = app.state.proxy
+ proxy.metrics.record_extension_savings("tool_router", 200)
+ proxy.metrics.record_extension_savings("tool_router", 50)
+ proxy.metrics.record_extension_savings("skill_search", 75)
+
+ stats = client.get("/stats")
+ assert stats.status_code == 200
+ assert stats.json()["extension_savings"] == {
+ "tool_router": 250,
+ "skill_search": 75,
+ }
+
+
def test_prometheus_metrics_accumulates_codex_ws_unit_and_frame_counters():
from headroom.proxy.prometheus_metrics import PrometheusMetrics