vLLM KV-cache usage gauge (1.0 = 100%)
vllm · gauge
Fields
id
metric-exposures/w3m-vllm-vllm-kv-cache-usage-percMetric name
vllm:kv_cache_usage_perc
Metric type
gauge
Unit
1
Exposure
prometheus
Endpoint
:8000/metrics
Labels
model_nameengine
Enabled by default
yes
notes
vLLM main, PrometheusStatLogger in vllm/v1/metrics/loggers.py, read 2026-10-04. On by default (EngineArgs.disable_log_stats defaults False); served at :8000/metrics. Bucket family name in --custom-histogram-buckets: no bucket family. Renamed from vllm:gpu_cache_usage_perc; reading the old name in a dashboard is a silent zero, not an error. A usage ratio is not a headroom signal on its own - see the kv-cache-usage gotcha.
Notes
vLLM main, PrometheusStatLogger in vllm/v1/metrics/loggers.py, read 2026-10-04. On by default (EngineArgs.disable_log_stats defaults False); served at :8000/metrics. Bucket family name in --custom-histogram-buckets: no bucket family. Renamed from vllm:gpu_cache_usage_perc; reading the old name in a dashboard is a silent zero, not an error. A usage ratio is not a headroom signal on its own - see the kv-cache-usage gotcha.