vllm:kv_cache_usage_perc

Gauge for KV-cache usage where 1 means 100 percent usage.

MetricPrometheusvLLM v0.23.0verified 11 hr ago

Identity

Prometheus type: gauge
Labels: model_nameengine
Unit: Not recorded — vLLM registration code has no structured unit field, and units are not inferred from name suffixes

Semantic coverage

covered · Availability & namecovered · Structural identitycovered · Measurement semanticscovered · Causal/runtime semanticscovered · Interpretation & compositioncovered · Guarded guidance

Metric knowledge (7)

Claim	Semantic layer	Verified
In vLLM v0.23.0, `vllm:kv_cache_usage_perc` is a point-in-time gauge where 1 represents fully used KV block capacity.	Measurement semantics	11 hr ago
In vLLM v0.23.0, `vllm:kv_cache_usage_perc` is set from `SchedulerStats.kv_cache_usage` rather than incremented from completed requests.	Causal/runtime semantics	11 hr ago
In vLLM v0.23.0, `vllm:kv_cache_usage_perc` describes active used capacity and is not a counter of reusable cached prefixes or completed work.	Interpretation & composition	11 hr ago
In vLLM v0.23.0, `vllm:kv_cache_usage_perc` use it as a pressure signal alongside waiting and progress metrics; do not infer cache effectiveness from it alone.	Guarded guidance	11 hr ago
In vLLM v0.23.0, `vllm:kv_cache_usage_perc` is registered with the label names `model_name`, engine.	Structural identity	11 hr ago
In vLLM v0.23.0, `vllm:kv_cache_usage_perc` is a Prometheus gauge for KV-cache usage where 1 means 100 percent usage.	Structural identity	11 hr ago
In vLLM v0.23.0, `vllm:kv_cache_usage_perc` is set from `SchedulerStats.kv_cache_usage` and observes KV-cache usage pressure.	Interpretation & composition	11 hr ago

Related Use Cases (1)

#12077: Active KV use is not reusable cache residency

Availability

vllm:kv_cache_usage_perc is registered as a Prometheus gauge in vLLM v0.23.0.

vllm.surface.prometheus_metricscomplete_inventoryPrometheusStatLogger metrics publisher

vLLM v0.23.0 v1 metrics loggers.py · vllm/v1/metrics/loggers.py:519-527