The metric of interest is the ratio, not the counters you can see

The nuance

The vLLM design docs record prefix-cache activity as two token-denominated counters but state the metric of interest is the derived hit rate. The rationale section never names the real metrics (its PromQL example uses placeholder names), so no keyword search over the raw source can join the counter an operator sees to the compute-the-ratio guidance — Schema's interpretation claim is the only place that join exists. The question arrives in the source's own vocabulary ("tokens queried" / "queried tokens"), which a web-grounded frontier model resolved to the wrong metrics entirely (prompt/generation tokens).

Expected behavior

All variants should serve the prefix-cache counter claims together with the hit-rate interpretation claim (rate over exposition _total series, tokens not requests), with the hit-rate-thresholds gap explicit — never a synthesized healthy range.

Try the questions (3)

This scenario is documented as known failing: some variants do not yet serve the expected blocks. Running them shows today's real behavior — the failure is recorded, not hidden.

Grounding claims

• In vLLM v0.23.0, vllm:prefix_cache_queries is a Prometheus counter measured in queried tokens — it counts tokens, not requests or cache blocks.
• In vLLM v0.23.0, vllm:prefix_cache_hits is a Prometheus counter measured in cached (hit) tokens — it counts tokens, not requests or cache blocks.
• The vLLM v0.23.0 metrics design docs state the metric of interest is the prefix cache hit rate (hits per query): the counters are exposed raw so operators compute the rate over an interval of their choosing with PromQL (rate(hits)/rate(queries)); vLLM's own logging equivalent aggregates hit_rate over the most recent queries.

Topics, entities, and gaps

Eval fixtures

eval.vllm.metric.prefix-cache.hit-rate-blocks

Counterfactual evidence

What a general model did with these questions (repo artifacts).

docs/research/handoff_inbox/vllm-prometheus-metrics-session-handoff.md

docs/research/handoff_inbox/chatgpt_review_claim_1.md

Status notes

known_failing (2026-07-15): the first variant retrieves the scheduler/KV claims — generic framing tokens swamp the discriminative doc-phrase (BACKLOG: Query Retrieval: Discriminative-Phrase Ranking). The bare phrase and the interpretation-question variants work. Counter-name entry points also do not co-serve the interpretation claim (BACKLOG: Claim Anatomy, contrast-sets item). Promote to works_today when both land, and convert the failing variant into a golden fixture.