If a KV-offload panel goes blank after a vLLM v0.28.0 upgrade, check its metric names before concluding that cache activity has dropped to zero. For teams serving AI APIs on vLLM, the immediate decision is whether the monitoring needs migration—not whether to tune the cache based on a missing series.
The v0.28.0 release notes, under Breaking Changes & Deprecations, say:
KV offload tiering metrics renamed from
kv_offload_tiering_block_{queries,hits}to..._chunk_...
That entry references PR #52812. The same release lists “tiering offloading metrics” under Large Scale Serving, referencing #48798. This is a change to a specific metric family, not evidence that every missing vLLM cache metric has the same cause.
Check the monitoring dependency first
The following is an operational checklist derived from the documented rename, not a report of a tested deployment:
- Find the consumers. Search dashboard definitions, recording rules and alerts for
kv_offload_tiering_block_. Include downstream panels that consume recording rules rather than raw metrics. If nothing depends on this family, this particular rename does not establish a need to rewrite your monitoring. - Inspect what the upgraded deployment emits. Check collection health and the observed KV-offload tiering series. Record the actual replacement names, metric descriptions and labels. The release uses
..._chunk_...as shorthand; it is not a copy-ready query or a complete exported schema. - Migrate against observations. Update dependent queries to the verified names and labels. If calculating a hit ratio, check both the query and hit inputs and their aggregation scope. Do not assume a text substitution validates the result.
- Exercise the monitoring path. Use an appropriate controlled workload to check that the expected series reach the monitoring backend and that dashboards and rules evaluate as intended. Test missing-data handling separately from a measured zero. Do not add a zero fallback merely to make a blank panel look healthy.
If the replacement series cannot be observed, stop migration sign-off. Investigate collection, offload configuration and whether the workload exercises the relevant path with the serving-platform owner. The rename is a lead, not a confirmed diagnosis. API consumers without access to serving metrics should ask that owner to verify the dependency rather than infer cache behavior from an empty report.
Visibility is not historical comparability
A populated panel proves less than a valid before-and-after comparison. The supplied release notes do not establish a block-to-chunk conversion factor, numerical equivalence, unchanged labels, compatibility aliases or suitable alert thresholds.
Keep the upgrade boundary visible in reports. Before joining old and new histories or carrying thresholds forward, verify units and measurement semantics. A recovered hit-ratio chart also needs that check; recognizable query and hit names alone do not prove a comparable ratio across versions.
The safe completion condition is two-part: the replacement signals are observable, and the queries using them have been validated. Historical comparisons remain a separate task until equivalence is established. Neither a blank panel nor a successful rename alone justifies a conclusion about cache effectiveness.