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.

Add observed cache TTL metrics and dashboard coverage

JerrettDavisa6787556beec
diff --git a/docs/metrics.md b/docs/metrics.md
index 6664fa989..66bcdef43 100644
--- a/docs/metrics.md
+++ b/docs/metrics.md
@@ -53,6 +53,41 @@ for backward compatibility. The new `persistent_savings` block is durable local
proxy compression history stored by default at `~/.headroom/proxy_savings.json`.
Use `HEADROOM_SAVINGS_PATH` to override the file location.
+For Anthropic-style providers that return cache-write TTL buckets, `/stats`
+also surfaces observed cache TTL usage under `prefix_cache`:
+
+```json
+{
+ "prefix_cache": {
+ "by_provider": {
+ "anthropic": {
+ "observed_ttl_buckets": {
+ "5m": {"tokens": 20000, "requests": 8},
+ "1h": {"tokens": 50000, "requests": 12}
+ },
+ "observed_ttl_mix": {
+ "5m_pct": 28.6,
+ "1h_pct": 71.4,
+ "active_buckets": ["5m", "1h"]
+ }
+ }
+ },
+ "totals": {
+ "observed_ttl_buckets": {
+ "5m": {"tokens": 20000, "requests": 8},
+ "1h": {"tokens": 50000, "requests": 12}
+ }
+ }
+ }
+}
+```
+
+These fields are observational only:
+
+- they reflect provider-reported cache write buckets
+- they do not configure TTL
+- they do not represent remaining expiration time
+
### Historical Savings Endpoint
```bash
diff --git a/docs/proxy.md b/docs/proxy.md
index 244e9bde6..cc0ee7959 100644
--- a/docs/proxy.md
+++ b/docs/proxy.md
@@ -133,6 +133,16 @@ curl http://localhost:8787/stats
small recent preview. The existing `savings_history` field is still present and
remains session-scoped for backward compatibility.
+For providers that return cache-write TTL bucket usage, `/stats` also includes
+observed TTL breakdowns under `prefix_cache`:
+
+- `observed_ttl_buckets.5m.tokens`
+- `observed_ttl_buckets.1h.tokens`
+- `observed_ttl_mix`
+
+These are provider-reported observations, not configured TTL and not remaining
+expiration time.
+
### Historical Savings
```bash
diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.html
index 68e4f4df7..68f12319f 100644
--- a/headroom/dashboard/templates/dashboard.html
+++ b/headroom/dashboard/templates/dashboard.html
@@ -208,6 +208,60 @@
<span class="flex items-center gap-1"><span class="w-2 h-2 rounded-full bg-border inline-block"></span> Uncached</span>
</div>
</div>
+ <template x-if="hasObservedTtlBuckets">
+ <div class="mt-5 border-t border-border pt-4">
+ <div class="flex items-center justify-between mb-3">
+ <div>
+ <div class="text-xs text-gray-500 uppercase tracking-[0.22em]">Observed TTL Buckets</div>
+ <div class="text-sm text-gray-300 mt-1">Provider-reported cache write mix</div>
+ </div>
+ <div class="text-xs text-gray-500 font-mono" x-text="observedTtlWindowLabel"></div>
+ </div>
+ <div class="grid grid-cols-1 xl:grid-cols-[1.3fr_0.9fr] gap-4">
+ <div class="rounded-2xl border border-cyan-500/20 bg-[linear-gradient(180deg,rgba(34,211,238,0.10),rgba(12,16,22,0.88))] p-4 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]">
+ <div class="flex items-start justify-between gap-3">
+ <div>
+ <div class="text-[11px] uppercase tracking-[0.22em] text-cyan-300/75">Bucket Mix</div>
+ <div class="mt-1 text-2xl font-light text-cyan-50">
+ <span data-testid="ttl-bucket-mix-1h-total" x-text="formatNumber(stats.prefix_cache?.totals?.cache_write_1h_tokens || 0)"></span>
+ <span class="text-sm text-cyan-300/70">1h</span>
+ <span class="mx-2 text-cyan-500/60">/</span>
+ <span data-testid="ttl-bucket-mix-5m-total" x-text="formatNumber(stats.prefix_cache?.totals?.cache_write_5m_tokens || 0)"></span>
+ <span class="text-sm text-cyan-300/70">5m</span>
+ </div>
+ </div>
+ <div data-testid="ttl-bucket-headline" class="rounded-full border border-cyan-400/20 bg-black/20 px-3 py-1 text-[11px] uppercase tracking-[0.18em] text-cyan-200/80" x-text="observedTtlHeadline"></div>
+ </div>
+ <div class="mt-4">
+ <div class="flex justify-between text-xs text-gray-500 mb-1">
+ <span>Observed write-token split</span>
+ <span x-text="(stats.prefix_cache?.totals?.observed_ttl_mix?.active_buckets || []).join(' + ')"></span>
+ </div>
+ <div class="h-3 overflow-hidden rounded-full bg-black/30 ring-1 ring-white/5 flex">
+ <div class="h-full bg-cyan-400 transition-all duration-500" :style="'width:' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['1h_pct'] || 0) + '%'"></div>
+ <div class="h-full bg-violet-400 transition-all duration-500" :style="'width:' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['5m_pct'] || 0) + '%'"></div>
+ </div>
+ <div class="mt-2 flex flex-wrap gap-3 text-xs text-gray-400">
+ <span class="inline-flex items-center gap-1.5"><span class="inline-block h-2 w-2 rounded-full bg-cyan-400"></span><span data-testid="ttl-bucket-mix-1h-pct" x-text="'1h ' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['1h_pct'] || 0).toFixed(1) + '%'"></span></span>
+ <span class="inline-flex items-center gap-1.5"><span class="inline-block h-2 w-2 rounded-full bg-violet-400"></span><span data-testid="ttl-bucket-mix-5m-pct" x-text="'5m ' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['5m_pct'] || 0).toFixed(1) + '%'"></span></span>
+ </div>
+ </div>
+ </div>
+ <div class="grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-1 gap-3">
+ <div class="rounded-2xl border border-white/8 bg-black/20 p-4">
+ <div class="text-[11px] uppercase tracking-[0.18em] text-cyan-300/75">1h Cache Writes</div>
+ <div data-testid="ttl-bucket-1h-value" class="mt-2 text-3xl font-light text-cyan-50" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['1h']?.tokens || 0)"></div>
+ <div class="mt-1 text-xs text-gray-500" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['1h']?.requests || 0) + ' requests observed'"></div>
+ </div>
+ <div class="rounded-2xl border border-white/8 bg-black/20 p-4">
+ <div class="text-[11px] uppercase tracking-[0.18em] text-violet-300/75">5m Cache Writes</div>
+ <div data-testid="ttl-bucket-5m-value" class="mt-2 text-3xl font-light text-violet-50" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['5m']?.tokens || 0)"></div>
+ <div class="mt-1 text-xs text-gray-500" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['5m']?.requests || 0) + ' requests observed'"></div>
+ </div>
+ </div>
+ </div>
+ </div>
+ </template>
<!-- Per-provider breakdown -->
<template x-if="Object.keys(stats.prefix_cache?.by_provider || {}).length > 0">
<div class="mt-4 border-t border-border pt-3">
@@ -219,11 +273,14 @@
<span class="px-2 py-0.5 bg-border rounded text-xs font-mono" x-text="prov"></span>
<span class="text-xs text-gray-500" x-text="pc.label"></span>
</div>
- <div class="flex items-center gap-4 text-xs font-mono">
+ <div class="flex flex-wrap items-center justify-end gap-4 text-xs font-mono">
<span class="text-emerald-400" x-text="formatNumber(pc.cache_read_tokens) + ' reads (' + pc.read_discount + ' off)'"></span>
<template x-if="pc.write_premium !== 'none'">
<span class="text-amber-400" x-text="formatNumber(pc.cache_write_tokens) + ' writes (+' + pc.write_premium + ')'"></span>
</template>
+ <template x-if="pc.observed_ttl_mix">
+ <span class="text-cyan-300" x-text="'TTL 1h ' + (pc.observed_ttl_mix['1h_pct'] || 0).toFixed(1) + '% / 5m ' + (pc.observed_ttl_mix['5m_pct'] || 0).toFixed(1) + '%'"></span>
+ </template>
<span :class="pc.bust_count > 0 ? 'text-red-400' : 'text-gray-500'" x-text="pc.bust_count + ' busts'"></span>
<span class="text-emerald-400" x-text="'$' + formatCurrency(pc.net_savings_usd)"></span>
</div>
@@ -1054,6 +1111,26 @@
return Math.round((t.cache_write_tokens || 0) / total * 100);
},
+ get hasObservedTtlBuckets() {
+ const buckets = this.stats.prefix_cache?.totals?.observed_ttl_buckets || {};
+ return ((buckets['5m']?.tokens || 0) + (buckets['1h']?.tokens || 0)) > 0;
+ },
+
+ get observedTtlHeadline() {
+ const mix = this.stats.prefix_cache?.totals?.observed_ttl_mix || {};
+ const oneHour = mix['1h_pct'] || 0;
+ const fiveMinute = mix['5m_pct'] || 0;
+ if (oneHour === fiveMinute) return 'Balanced';
+ return oneHour > fiveMinute ? '1h leaning' : '5m leaning';
+ },
+
+ get observedTtlWindowLabel() {
+ const mix = this.stats.prefix_cache?.totals?.observed_ttl_mix || {};
+ const active = mix.active_buckets || [];
+ if (!active.length) return 'No TTL bucket data';
+ return active.length === 1 ? active[0] + ' only' : active.join(' / ');
+ },
+
// --- Waste Signals ---
wasteSignalLabel(signal) {
diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.py
index d2f1859ea..0f0bd9011 100644
--- a/headroom/proxy/cost.py
+++ b/headroom/proxy/cost.py
@@ -78,6 +78,10 @@ def build_prefix_cache_stats(
totals = {
"cache_read_tokens": 0,
"cache_write_tokens": 0,
+ "cache_write_5m_tokens": 0,
+ "cache_write_1h_tokens": 0,
+ "cache_write_5m_requests": 0,
+ "cache_write_1h_requests": 0,
"requests": 0,
"hit_requests": 0,
"bust_count": 0,
@@ -119,6 +123,10 @@ def build_prefix_cache_stats(
# for observability but don't penalise our savings number.
read_tokens: int = pc["cache_read_tokens"] # type: ignore[assignment]
write_tokens: int = pc["cache_write_tokens"] # type: ignore[assignment]
+ write_5m_tokens: int = pc["cache_write_5m_tokens"] # type: ignore[assignment]
+ write_1h_tokens: int = pc["cache_write_1h_tokens"] # type: ignore[assignment]
+ write_5m_requests: int = pc["cache_write_5m_requests"] # type: ignore[assignment]
+ write_1h_requests: int = pc["cache_write_1h_requests"] # type: ignore[assignment]
savings_usd = 0.0
write_premium_usd = 0.0
@@ -134,6 +142,10 @@ def build_prefix_cache_stats(
provider_stats = {
"cache_read_tokens": read_tokens,
"cache_write_tokens": write_tokens,
+ "cache_write_5m_tokens": write_5m_tokens,
+ "cache_write_1h_tokens": write_1h_tokens,
+ "cache_write_5m_requests": write_5m_requests,
+ "cache_write_1h_requests": write_1h_requests,
"requests": pc["requests"],
"hit_requests": pc["hit_requests"],
"hit_rate": hit_rate,
@@ -145,12 +157,37 @@ def build_prefix_cache_stats(
"write_premium_usd": round(write_premium_usd, 4),
"net_savings_usd": round(savings_usd, 4),
"label": str(econ["label"]),
+ "observed_ttl_buckets": {
+ "5m": {
+ "tokens": write_5m_tokens,
+ "requests": write_5m_requests,
+ },
+ "1h": {
+ "tokens": write_1h_tokens,
+ "requests": write_1h_requests,
+ },
+ },
}
+ total_observed_ttl_tokens = write_5m_tokens + write_1h_tokens
+ if total_observed_ttl_tokens > 0:
+ provider_stats["observed_ttl_mix"] = {
+ "5m_pct": round(write_5m_tokens / total_observed_ttl_tokens * 100, 1),
+ "1h_pct": round(write_1h_tokens / total_observed_ttl_tokens * 100, 1),
+ "active_buckets": [
+ bucket
+ for bucket, tokens in (("5m", write_5m_tokens), ("1h", write_1h_tokens))
+ if tokens > 0
+ ],
+ }
by_provider[provider] = provider_stats
# Accumulate totals
totals["cache_read_tokens"] += read_tokens
totals["cache_write_tokens"] += write_tokens
+ totals["cache_write_5m_tokens"] += write_5m_tokens
+ totals["cache_write_1h_tokens"] += write_1h_tokens
+ totals["cache_write_5m_requests"] += write_5m_requests
+ totals["cache_write_1h_requests"] += write_1h_requests
totals["requests"] += pc["requests"]
totals["hit_requests"] += pc["hit_requests"]
totals["bust_count"] += pc["bust_count"]
@@ -164,6 +201,33 @@ def build_prefix_cache_stats(
totals["hit_rate"] = (
round(totals["hit_requests"] / totals["requests"] * 100, 1) if totals["requests"] > 0 else 0
)
+ total_observed_ttl_tokens = totals["cache_write_5m_tokens"] + totals["cache_write_1h_tokens"]
+ totals["observed_ttl_buckets"] = {
+ "5m": {
+ "tokens": totals["cache_write_5m_tokens"],
+ "requests": totals["cache_write_5m_requests"],
+ },
+ "1h": {
+ "tokens": totals["cache_write_1h_tokens"],
+ "requests": totals["cache_write_1h_requests"],
+ },
+ }
+ totals["observed_ttl_mix"] = {
+ "5m_pct": round(totals["cache_write_5m_tokens"] / total_observed_ttl_tokens * 100, 1)
+ if total_observed_ttl_tokens > 0
+ else 0.0,
+ "1h_pct": round(totals["cache_write_1h_tokens"] / total_observed_ttl_tokens * 100, 1)
+ if total_observed_ttl_tokens > 0
+ else 0.0,
+ "active_buckets": [
+ bucket
+ for bucket, tokens in (
+ ("5m", totals["cache_write_5m_tokens"]),
+ ("1h", totals["cache_write_1h_tokens"]),
+ )
+ if tokens > 0
+ ],
+ }
return {
"by_provider": by_provider,
@@ -180,7 +244,9 @@ def build_prefix_cache_stats(
"Prefix caching is performed by the LLM provider (Anthropic, OpenAI). "
"Headroom reports cache stats as observed from API responses. "
"CacheAligner and prefix freeze improve cache hit rates by stabilizing "
- "the message prefix, but baseline caching happens without Headroom."
+ "the message prefix, but baseline caching happens without Headroom. "
+ "Observed TTL bucket metrics reflect provider-reported cache write usage "
+ "(for example Anthropic 5m vs 1h), not configured or remaining TTL."
),
}
@@ -356,6 +422,8 @@ class CostTracker:
# API-reported cache breakdown per model (for accurate cost calculation)
self._api_cache_read_by_model: dict[str, int] = {}
self._api_cache_write_by_model: dict[str, int] = {}
+ self._api_cache_write_5m_by_model: dict[str, int] = {}
+ self._api_cache_write_1h_by_model: dict[str, int] = {}
self._api_uncached_by_model: dict[str, int] = {}
# Cache resolved model names to avoid repeated litellm lookups.
@@ -480,6 +548,8 @@ class CostTracker:
tokens_sent: int,
cache_read_tokens: int = 0,
cache_write_tokens: int = 0,
+ cache_write_5m_tokens: int = 0,
+ cache_write_1h_tokens: int = 0,
uncached_tokens: int = 0,
):
"""Record token counts per model.
@@ -503,6 +573,12 @@ class CostTracker:
self._api_cache_write_by_model[model] = (
self._api_cache_write_by_model.get(model, 0) + cache_write_tokens
)
+ self._api_cache_write_5m_by_model[model] = (
+ self._api_cache_write_5m_by_model.get(model, 0) + cache_write_5m_tokens
+ )
+ self._api_cache_write_1h_by_model[model] = (
+ self._api_cache_write_1h_by_model.get(model, 0) + cache_write_1h_tokens
+ )
self._api_uncached_by_model[model] = (
self._api_uncached_by_model.get(model, 0) + uncached_tokens
)
@@ -574,6 +650,8 @@ class CostTracker:
"requests": reqs,
"tokens_saved": saved,
"tokens_sent": sent,
+ "cache_write_5m_tokens": self._api_cache_write_5m_by_model.get(model, 0),
+ "cache_write_1h_tokens": self._api_cache_write_1h_by_model.get(model, 0),
"reduction_pct": round(saved / (saved + sent) * 100, 1)
if (saved + sent) > 0
else 0,
@@ -625,6 +703,8 @@ class CostTracker:
"total_tokens_saved": total_saved,
"total_input_tokens": total_input_tokens,
"total_input_cost_usd": round(cost_with_headroom, 4),
+ "cache_write_5m_tokens": sum(self._api_cache_write_5m_by_model.values()),
+ "cache_write_1h_tokens": sum(self._api_cache_write_1h_by_model.values()),
"per_model": per_model,
"cost_with_headroom_usd": round(cost_with_headroom, 4),
"savings_usd": round(savings_usd, 4),
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 7a3fb9a9d..cf0407466 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -40,6 +40,24 @@ class AnthropicHandlerMixin:
canonical = str(tool)
return (name, canonical)
+ @staticmethod
+ def _extract_anthropic_cache_ttl_metrics(usage: dict[str, Any] | None) -> tuple[int, int]:
+ """Extract observed Anthropic cache-write TTL bucket usage.
+
+ Returns (cache_write_5m_tokens, cache_write_1h_tokens) from provider usage.
+ These are observational metrics only; they do not imply configured or
+ remaining TTL.
+ """
+ if not isinstance(usage, dict):
+ return (0, 0)
+ cache_creation = usage.get("cache_creation")
+ if not isinstance(cache_creation, dict):
+ return (0, 0)
+ return (
+ int(cache_creation.get("ephemeral_5m_input_tokens", 0) or 0),
+ int(cache_creation.get("ephemeral_1h_input_tokens", 0) or 0),
+ )
+
@classmethod
def _sort_tools_deterministically(
cls, tools: list[dict[str, Any]] | None
@@ -1196,12 +1214,15 @@ class AnthropicHandlerMixin:
output_tokens = 0
cr_tokens = 0
cw_tokens = 0
+ cw_5m_tokens = 0
+ cw_1h_tokens = 0
uncached_input_tokens = 0
if resp_json:
usage = resp_json.get("usage", {})
output_tokens = usage.get("output_tokens", 0)
cr_tokens = usage.get("cache_read_input_tokens", 0)
cw_tokens = usage.get("cache_creation_input_tokens", 0)
+ cw_5m_tokens, cw_1h_tokens = self._extract_anthropic_cache_ttl_metrics(usage)
uncached_input_tokens = usage.get("input_tokens", 0)
# Update prefix cache tracker for next turn
@@ -1225,6 +1246,8 @@ class AnthropicHandlerMixin:
optimized_tokens,
cache_read_tokens=cr_tokens,
cache_write_tokens=cw_tokens,
+ cache_write_5m_tokens=cw_5m_tokens,
+ cache_write_1h_tokens=cw_1h_tokens,
uncached_tokens=uncached_input_tokens,
)
@@ -1252,6 +1275,8 @@ class AnthropicHandlerMixin:
waste_signals=waste_signals_dict,
cache_read_tokens=cr_tokens,
cache_write_tokens=cw_tokens,
+ cache_write_5m_tokens=cw_5m_tokens,
+ cache_write_1h_tokens=cw_1h_tokens,
uncached_input_tokens=uncached_input_tokens,
)
diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py
index ea9065915..80c6656c8 100644
--- a/headroom/proxy/handlers/streaming.py
+++ b/headroom/proxy/handlers/streaming.py
@@ -24,6 +24,19 @@ logger = logging.getLogger("headroom.proxy")
class StreamingMixin:
"""Mixin providing streaming response methods for HeadroomProxy."""
+ @staticmethod
+ def _extract_anthropic_cache_ttl_metrics(usage: dict[str, Any] | None) -> tuple[int, int]:
+ """Extract observed Anthropic cache-write TTL bucket usage."""
+ if not isinstance(usage, dict):
+ return (0, 0)
+ cache_creation = usage.get("cache_creation")
+ if not isinstance(cache_creation, dict):
+ return (0, 0)
+ return (
+ int(cache_creation.get("ephemeral_5m_input_tokens", 0) or 0),
+ int(cache_creation.get("ephemeral_1h_input_tokens", 0) or 0),
+ )
+
def _parse_sse_usage(self, chunk: bytes, provider: str) -> dict[str, int] | None:
"""Parse usage information from SSE chunk.
@@ -31,7 +44,9 @@ class StreamingMixin:
For OpenAI: Looks for final chunk with usage object (requires stream_options.include_usage=true)
For Gemini: Looks for usageMetadata in each chunk
- Returns dict with keys: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens
+ Returns dict with keys: input_tokens, output_tokens, cache_read_input_tokens,
+ cache_creation_input_tokens, cache_creation_ephemeral_5m_input_tokens,
+ cache_creation_ephemeral_1h_input_tokens
Returns None if no usage found in this chunk.
"""
try:
@@ -67,6 +82,11 @@ class StreamingMixin:
usage["cache_creation_input_tokens"] = msg_usage.get(
"cache_creation_input_tokens", 0
)
+ cache_write_5m, cache_write_1h = (
+ self._extract_anthropic_cache_ttl_metrics(msg_usage)
+ )
+ usage["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m
+ usage["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1h
elif event_type == "message_delta":
delta_usage = data.get("usage", {})
@@ -148,6 +168,11 @@ class StreamingMixin:
usage_found["cache_creation_input_tokens"] = msg_usage.get(
"cache_creation_input_tokens", 0
)
+ cache_write_5m, cache_write_1h = (
+ self._extract_anthropic_cache_ttl_metrics(msg_usage)
+ )
+ usage_found["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m
+ usage_found["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1h
# INFO logging for cache token tracking (temporary for debugging)
logger.info(
f"[CACHE] Anthropic usage: input={usage_found.get('input_tokens')}, "
@@ -450,6 +475,8 @@ class StreamingMixin:
"output_tokens": None,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
+ "cache_creation_ephemeral_5m_input_tokens": 0,
+ "cache_creation_ephemeral_1h_input_tokens": 0,
"total_bytes": 0,
"sse_buffer": "", # Buffer for incomplete SSE events
"ttfb_ms": None, # Time to first byte from upstream
@@ -550,6 +577,14 @@ class StreamingMixin:
stream_state["cache_creation_input_tokens"] = usage[
"cache_creation_input_tokens"
]
+ if "cache_creation_ephemeral_5m_input_tokens" in usage:
+ stream_state["cache_creation_ephemeral_5m_input_tokens"] = usage[
+ "cache_creation_ephemeral_5m_input_tokens"
+ ]
+ if "cache_creation_ephemeral_1h_input_tokens" in usage:
+ stream_state["cache_creation_ephemeral_1h_input_tokens"] = usage[
+ "cache_creation_ephemeral_1h_input_tokens"
+ ]
# Memory tool handling after stream completes
# Chunks were already yielded in real-time above, so we only
@@ -637,6 +672,8 @@ class StreamingMixin:
# misleading for aggregation (often just 1 with prompt caching).
cache_read_tokens = stream_state["cache_read_input_tokens"]
cache_write_tokens = stream_state["cache_creation_input_tokens"]
+ cache_write_5m_tokens = stream_state["cache_creation_ephemeral_5m_input_tokens"]
+ cache_write_1h_tokens = stream_state["cache_creation_ephemeral_1h_input_tokens"]
uncached_input_tokens = stream_state.get("input_tokens") or 0
# Structured perf log line for `headroom perf` analysis
@@ -672,6 +709,8 @@ class StreamingMixin:
optimized_tokens,
cache_read_tokens=cache_read_tokens,
cache_write_tokens=cache_write_tokens,
+ cache_write_5m_tokens=cache_write_5m_tokens,
+ cache_write_1h_tokens=cache_write_1h_tokens,
uncached_tokens=uncached_input_tokens,
)
@@ -687,6 +726,8 @@ class StreamingMixin:
pipeline_timing=pipeline_timing,
cache_read_tokens=cache_read_tokens,
cache_write_tokens=cache_write_tokens,
+ cache_write_5m_tokens=cache_write_5m_tokens,
+ cache_write_1h_tokens=cache_write_1h_tokens,
uncached_input_tokens=uncached_input_tokens,
)
diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.py
index c23bafe78..e5889d406 100644
--- a/headroom/proxy/prometheus_metrics.py
+++ b/headroom/proxy/prometheus_metrics.py
@@ -77,6 +77,10 @@ class PrometheusMetrics:
lambda: {
"cache_read_tokens": 0,
"cache_write_tokens": 0,
+ "cache_write_5m_tokens": 0,
+ "cache_write_1h_tokens": 0,
+ "cache_write_5m_requests": 0,
+ "cache_write_1h_requests": 0,
"requests": 0,
"hit_requests": 0, # requests with cache_read > 0
"bust_count": 0,
@@ -158,6 +162,8 @@ class PrometheusMetrics:
waste_signals: dict[str, int] | None = None,
cache_read_tokens: int = 0,
cache_write_tokens: int = 0,
+ cache_write_5m_tokens: int = 0,
+ cache_write_1h_tokens: int = 0,
uncached_input_tokens: int = 0,
):
"""Record metrics for a request."""
@@ -178,6 +184,12 @@ class PrometheusMetrics:
pc = self.cache_by_provider[provider]
pc["cache_read_tokens"] += cache_read_tokens
pc["cache_write_tokens"] += cache_write_tokens
+ pc["cache_write_5m_tokens"] += cache_write_5m_tokens
+ pc["cache_write_1h_tokens"] += cache_write_1h_tokens
+ if cache_write_5m_tokens > 0:
+ pc["cache_write_5m_requests"] += 1
+ if cache_write_1h_tokens > 0:
+ pc["cache_write_1h_requests"] += 1
pc["requests"] += 1
if cache_read_tokens > 0:
pc["hit_requests"] += 1
diff --git a/tests/test_dashboard_cache_ttl_playwright.py b/tests/test_dashboard_cache_ttl_playwright.py
new file mode 100644
index 000000000..09b398dc3
--- /dev/null
+++ b/tests/test_dashboard_cache_ttl_playwright.py
@@ -0,0 +1,211 @@
+"""Behavior-driven Playwright validation for dashboard TTL cache metrics."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from headroom.dashboard import get_dashboard_html
+
+playwright = pytest.importorskip("playwright.sync_api")
+Page = playwright.Page
+expect = playwright.expect
+sync_playwright = playwright.sync_playwright
+
+
+def _sample_stats() -> dict:
+ return {
+ "cost": {
+ "savings_usd": 12.34,
+ "compression_savings_usd": 12.34,
+ "cache_savings_usd": 5.67,
+ "cli_tokens_avoided": 0,
+ },
+ "requests": {
+ "total": 128,
+ "cached": 96,
+ "rate_limited": 0,
+ "failed": 0,
+ "by_provider": {"anthropic": 128},
+ "by_model": {"claude-opus-4-6": 128},
+ },
+ "tokens": {
+ "input": 245_000,
+ "output": 88_000,
+ "saved": 143_000,
+ "cli_tokens_avoided": 0,
+ "total_before_compression": 388_000,
+ "savings_percent": 36.86,
+ },
+ "overhead": {"average_ms": 14.2, "min_ms": 4.5, "max_ms": 42.7},
+ "ttfb": {"average_ms": 1320.0, "min_ms": 420.0, "max_ms": 2900.0},
+ "latency": {"average_ms": 1510.0, "min_ms": 520.0, "max_ms": 3300.0},
+ "waste_signals": {"json_bloat": 95_000, "repetition": 48_000},
+ "savings_history": [
+ ["2026-04-01T00:00:00Z", 12_000],
+ ["2026-04-02T00:00:00Z", 38_000],
+ ["2026-04-03T00:00:00Z", 57_000],
+ ["2026-04-04T00:00:00Z", 102_000],
+ ["2026-04-05T00:00:00Z", 143_000],
+ ],
+ "persistent_savings": {
+ "display_session": {},
+ "lifetime": {"tokens_saved": 143_000, "compression_savings_usd": 12.34},
+ },
+ "pipeline_timing": {},
+ "compression_cache": {"mode": "cache"},
+ "prefix_cache": {
+ "by_provider": {
+ "anthropic": {
+ "cache_read_tokens": 9_800_000,
+ "cache_write_tokens": 420_000,
+ "cache_write_5m_tokens": 185_000,
+ "cache_write_1h_tokens": 235_000,
+ "cache_write_5m_requests": 18,
+ "cache_write_1h_requests": 24,
+ "requests": 128,
+ "hit_requests": 96,
+ "hit_rate": 75.0,
+ "bust_count": 0,
+ "bust_write_tokens": 0,
+ "read_discount": "90%",
+ "write_premium": "25%",
+ "savings_usd": 5.67,
+ "write_premium_usd": 0.42,
+ "net_savings_usd": 5.67,
+ "label": "Explicit breakpoints, 5-min TTL",
+ "observed_ttl_buckets": {
+ "5m": {"tokens": 185_000, "requests": 18},
+ "1h": {"tokens": 235_000, "requests": 24},
+ },
+ "observed_ttl_mix": {
+ "5m_pct": 44.0,
+ "1h_pct": 56.0,
+ "active_buckets": ["5m", "1h"],
+ },
+ }
+ },
+ "totals": {
+ "cache_read_tokens": 9_800_000,
+ "cache_write_tokens": 420_000,
+ "cache_write_5m_tokens": 185_000,
+ "cache_write_1h_tokens": 235_000,
+ "cache_write_5m_requests": 18,
+ "cache_write_1h_requests": 24,
+ "requests": 128,
+ "hit_requests": 96,
+ "bust_count": 0,
+ "bust_write_tokens": 0,
+ "savings_usd": 5.67,
+ "write_premium_usd": 0.42,
+ "net_savings_usd": 5.67,
+ "hit_rate": 75.0,
+ "observed_ttl_buckets": {
+ "5m": {"tokens": 185_000, "requests": 18},
+ "1h": {"tokens": 235_000, "requests": 24},
+ },
+ "observed_ttl_mix": {
+ "5m_pct": 44.0,
+ "1h_pct": 56.0,
+ "active_buckets": ["5m", "1h"],
+ },
+ },
+ "prefix_freeze": {
+ "busts_avoided": 0,
+ "tokens_preserved": 0,
+ "compression_foregone_tokens": 0,
+ "net_benefit_tokens": 0,
+ },
+ "attribution": "Observed provider TTL buckets.",
+ },
+ }
+
+
+def _sample_history() -> dict:
+ return {
+ "history": [
+ {
+ "timestamp": "2026-04-01T00:00:00Z",
+ "total_tokens_saved": 12_000,
+ "compression_savings_usd": 0.6,
+ },
+ {
+ "timestamp": "2026-04-05T00:00:00Z",
+ "total_tokens_saved": 143_000,
+ "compression_savings_usd": 12.34,
+ },
+ ],
+ "series": {
+ "daily": [
+ {
+ "timestamp": "2026-04-05T00:00:00Z",
+ "tokens_saved": 20_000,
+ "total_tokens_saved": 143_000,
+ "compression_savings_usd_delta": 1.7,
+ }
+ ],
+ "weekly": [],
+ "monthly": [],
+ },
+ "lifetime": {"tokens_saved": 143_000, "compression_savings_usd": 12.34},
+ }
+
+
+def _install_dashboard_routes(page: Page) -> None:
+ stats = _sample_stats()
+ history = _sample_history()
+ health = {"status": "healthy", "version": "0.3.0"}
+ dashboard_html = get_dashboard_html()
+
+ def handler(route) -> None: # type: ignore[no-untyped-def]
+ url = route.request.url
+ if url.endswith("/dashboard") or url == "http://headroom.local/":
+ route.fulfill(status=200, content_type="text/html", body=dashboard_html)
+ return
+ if url.endswith("/stats"):
+ route.fulfill(status=200, content_type="application/json", body=json.dumps(stats))
+ return
+ if "/stats-history" in url:
+ route.fulfill(
+ status=200,
+ content_type="application/json",
+ body=json.dumps(history),
+ )
+ return
+ if url.endswith("/health"):
+ route.fulfill(status=200, content_type="application/json", body=json.dumps(health))
+ return
+ route.continue_()
+
+ page.route("**/*", handler)
+
+
+def test_dashboard_renders_observed_ttl_metrics_and_can_capture_screenshot() -> None:
+ artifact_dir = os.environ.get("HEADROOM_PLAYWRIGHT_ARTIFACT_DIR")
+
+ with sync_playwright() as pw:
+ browser = pw.chromium.launch()
+ page = browser.new_page(viewport={"width": 1720, "height": 1400}, color_scheme="dark")
+ _install_dashboard_routes(page)
+ page.goto("http://headroom.local/dashboard", wait_until="load")
+
+ expect(page.get_by_text("Observed TTL Buckets")).to_be_visible()
+ expect(page.get_by_text("Provider-reported cache write mix")).to_be_visible()
+ expect(page.get_by_test_id("ttl-bucket-headline")).to_have_text("1h leaning")
+ expect(page.get_by_test_id("ttl-bucket-mix-1h-pct")).to_have_text("1h 56.0%")
+ expect(page.get_by_test_id("ttl-bucket-mix-5m-pct")).to_have_text("5m 44.0%")
+ expect(page.get_by_test_id("ttl-bucket-1h-value")).to_have_text("235.0k")
+ expect(page.get_by_test_id("ttl-bucket-5m-value")).to_have_text("185.0k")
+ expect(page.get_by_text("TTL 1h 56.0% / 5m 44.0%")).to_be_visible()
+
+ screenshot_path = (
+ Path(artifact_dir) / "dashboard-cache-ttl-main.png"
+ if artifact_dir
+ else Path.cwd() / "dashboard-cache-ttl-main.png"
+ )
+ screenshot_path.parent.mkdir(parents=True, exist_ok=True)
+ page.screenshot(path=str(screenshot_path), full_page=True)
+ browser.close()
diff --git a/tests/test_proxy_cache_ttl_metrics.py b/tests/test_proxy_cache_ttl_metrics.py
new file mode 100644
index 000000000..3d9301048
--- /dev/null
+++ b/tests/test_proxy_cache_ttl_metrics.py
@@ -0,0 +1,147 @@
+"""Tests for observed Anthropic cache TTL bucket metrics."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from headroom.proxy.cost import CostTracker, build_prefix_cache_stats
+from headroom.proxy.prometheus_metrics import PrometheusMetrics
+
+
+def test_prometheus_metrics_tracks_observed_ttl_buckets() -> None:
+ metrics = PrometheusMetrics()
+
+ asyncio.run(
+ metrics.record_request(
+ provider="anthropic",
+ model="claude-opus-4-6",
+ input_tokens=100,
+ output_tokens=20,
+ tokens_saved=5,
+ latency_ms=10.0,
+ cache_read_tokens=40,
+ cache_write_tokens=60,
+ cache_write_5m_tokens=10,
+ cache_write_1h_tokens=50,
+ )
+ )
+
+ stats = metrics.cache_by_provider["anthropic"]
+ assert stats["cache_write_5m_tokens"] == 10
+ assert stats["cache_write_1h_tokens"] == 50
+ assert stats["cache_write_5m_requests"] == 1
+ assert stats["cache_write_1h_requests"] == 1
+
+
+def test_cost_tracker_exposes_observed_ttl_buckets_per_model() -> None:
+ tracker = CostTracker()
+ tracker.record_tokens(
+ "claude-opus-4-6",
+ tokens_saved=10,
+ tokens_sent=90,
+ cache_read_tokens=40,
+ cache_write_tokens=60,
+ cache_write_5m_tokens=10,
+ cache_write_1h_tokens=50,
+ uncached_tokens=20,
+ )
+
+ stats = tracker.stats()
+ assert stats["cache_write_5m_tokens"] == 10
+ assert stats["cache_write_1h_tokens"] == 50
+ assert stats["per_model"]["claude-opus-4-6"]["cache_write_5m_tokens"] == 10
+ assert stats["per_model"]["claude-opus-4-6"]["cache_write_1h_tokens"] == 50
+
+
+def test_prefix_cache_stats_include_observed_ttl_mix() -> None:
+ metrics = PrometheusMetrics()
+ provider_stats = metrics.cache_by_provider["anthropic"]
+ provider_stats["requests"] = 2
+ provider_stats["hit_requests"] = 1
+ provider_stats["cache_read_tokens"] = 40
+ provider_stats["cache_write_tokens"] = 60
+ provider_stats["cache_write_5m_tokens"] = 15
+ provider_stats["cache_write_1h_tokens"] = 45
+ provider_stats["cache_write_5m_requests"] = 1
+ provider_stats["cache_write_1h_requests"] = 1
+
+ stats = build_prefix_cache_stats(metrics, None)
+ anthropic = stats["by_provider"]["anthropic"]
+
+ assert anthropic["observed_ttl_buckets"]["5m"]["tokens"] == 15
+ assert anthropic["observed_ttl_buckets"]["1h"]["tokens"] == 45
+ assert anthropic["observed_ttl_mix"]["5m_pct"] == 25.0
+ assert anthropic["observed_ttl_mix"]["1h_pct"] == 75.0
+ assert stats["totals"]["observed_ttl_buckets"]["5m"]["tokens"] == 15
+ assert stats["totals"]["observed_ttl_buckets"]["1h"]["tokens"] == 45
+
+
+def test_streaming_parser_extracts_anthropic_ttl_bucket_usage() -> None:
+ from headroom.proxy.server import HeadroomProxy, ProxyConfig
+
+ proxy = HeadroomProxy(
+ ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ log_requests=False,
+ ccr_inject_tool=False,
+ ccr_handle_responses=False,
+ ccr_context_tracking=False,
+ )
+ )
+
+ chunk = (
+ b'data: {"type":"message_start","message":{"usage":{"input_tokens":12,'
+ b'"cache_read_input_tokens":3,"cache_creation_input_tokens":9,'
+ b'"cache_creation":{"ephemeral_5m_input_tokens":4,"ephemeral_1h_input_tokens":5}}}}\n\n'
+ )
+ usage = proxy._parse_sse_usage(chunk, "anthropic")
+
+ assert usage is not None
+ assert usage["cache_creation_ephemeral_5m_input_tokens"] == 4
+ assert usage["cache_creation_ephemeral_1h_input_tokens"] == 5
+
+
+def test_stats_endpoint_reports_observed_ttl_buckets() -> None:
+ pytest.importorskip("fastapi")
+ from fastapi.testclient import TestClient
+
+ from headroom.proxy.server import ProxyConfig, create_app
+
+ app = create_app(
+ ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ log_requests=False,
+ ccr_inject_tool=False,
+ ccr_handle_responses=False,
+ ccr_context_tracking=False,
+ )
+ )
+
+ proxy = app.state.proxy
+ provider_stats = proxy.metrics.cache_by_provider["anthropic"]
+ provider_stats["requests"] = 1
+ provider_stats["hit_requests"] = 1
+ provider_stats["cache_read_tokens"] = 30
+ provider_stats["cache_write_tokens"] = 70
+ provider_stats["cache_write_5m_tokens"] = 20
+ provider_stats["cache_write_1h_tokens"] = 50
+ provider_stats["cache_write_5m_requests"] = 1
+ provider_stats["cache_write_1h_requests"] = 1
+
+ with TestClient(app) as client:
+ response = client.get("/stats")
+
+ assert response.status_code == 200
+ prefix_cache = response.json()["prefix_cache"]
+ anthropic = prefix_cache["by_provider"]["anthropic"]
+ assert anthropic["observed_ttl_buckets"]["5m"]["tokens"] == 20
+ assert anthropic["observed_ttl_buckets"]["1h"]["tokens"] == 50
+ assert prefix_cache["totals"]["observed_ttl_mix"]["active_buckets"] == ["5m", "1h"]