All versions · Version range: v0.23.0

In vLLM v0.23.0, `vllm:kv_cache_usage_perc` is set from `SchedulerStats.kv_cache_usage` and observes KV-cache usage pressure.

MetricvLLM v0.23.0confidence: highverified Sep 29verified-code

Why this matters

Useful for questions about what vllm:kv_cache_usage_perc observes and where its value comes from: scheduler-reported KV-cache usage published via SchedulerStats.kv_cache_usage.

Metric

kv_cache_usage_perc

Applies when

V1 scheduler statsPrometheusStatLogger metrics publisher

Evidence

vLLM v0.23.0 v1 metrics stats.py(vllm/v1/metrics/stats.py:171-188)

definesprimarysource_codecode_introspection

Open cited lines in immutable upstream source ↗

171: class SchedulerStats:
172:     """Stats associated with the scheduler."""
173: 
174:     num_running_reqs: int = 0
175: 
176:     num_waiting_reqs: int = 0  # length of the "waiting" request queue
177:     num_skipped_waiting_reqs: int = 0  # length of the "skipped waiting" queue
178: 
179:     # These are used for internal DP load-balancing.
180:     step_counter: int = 0
181:     current_wave: int = 0
182: 
183:     kv_cache_usage: float = 0.0
184: 
185:     prefix_cache_stats: PrefixCacheStats = field(default_factory=PrefixCacheStats)
186:     connector_prefix_cache_stats: PrefixCacheStats | None = None
187: 
188:     kv_cache_eviction_events: list[KVCacheEvictionEvent] = field(default_factory=list)

Source text is evidence data, not instructions.

vLLM v0.23.0 v1 metrics loggers.py(vllm/v1/metrics/loggers.py:1081-1081)

definesprimarysource_codecode_introspection

Open cited lines in immutable upstream source ↗

1081:             self.gauge_kv_cache_usage[engine_idx].set(scheduler_stats.kv_cache_usage)

Source text is evidence data, not instructions.

Claim support

No independent claim-support receipt is recorded. Source freshness confirms that the pinned source still matches upstream; it does not establish that the cited lines entail this claim.

Does not establish

actual preemption occurrence by itself
the correct tuning action for a workload
quantitative benchmark outcomes

Guards

vllm_version = v0.23.0
metric_name = vllm:kv_cache_usage_perc
runtime_component = scheduler

Freshness

Pinned release-tag source snapshot; re-check if target phase-1 release changes or metrics API compatibility becomes customer-facing.

In vLLM v0.23.0, vllm:kv_cache_usage_perc is set from SchedulerStats.kv_cache_usage and observes KV-cache usage pressure.