The name in your scrape is not the name in the code

The nuance

prometheus_client renames samples at exposition: counters gain _total and histograms emit _bucket/_count/_sum series, so the names operators see in scrapes and PromQL differ from the declared registration names. Before 2026-07-15 the _total form drew a false "absent from complete inventory" verdict — the worst failure class for a system whose honesty is load-bearing.

Expected behavior

Exposition-form names resolve to the declared metric with verdict present, alias_of the canonical name, alias_kind prometheus_exposition, and an interpretation naming the instrument class; gauge names with a _total suffix stay truthful absences because that sample never exists.

Try the questions (3)

Each question runs live against the product.

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.

Topics, entities, and gaps

Eval fixtures

eval.vllm.metric.exposition-total-alias

Counterfactual evidence

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

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

Status notes

General models handle the _total convention correctly unprompted (baseline probe 1), so this is table stakes, not differentiation — the differentiator is that misses stay honest (gauge+_total remains absent) instead of fuzzy-matching. Upstream doc evidence for the behavior: design/metrics.md lines 617-622 (candidate cand.vllm.metrics-design.total-suffix-exposition).