[Metrics] Add Prometheus counter for CUDA graph iteration mode

Add `vllm:cudagraph_iterations` counter with `runtime_mode` label
(NONE/PIECEWISE/FULL) so CUDA graph usage percentage can be computed
in PromQL. Also always populate CUDAGraphStat regardless of the
`--cudagraph-metrics` flag, since the stat is trivially cheap and that
flag should only gate the verbose text log table.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Tyler Michael Smith <tlrmchlsmth@gmail.com>

vllm/v1/metrics/loggers.py

@@ -413,6 +413,7 @@ class PrometheusStatLogger(AggregateStatLoggerBase):
 
         labelnames = ["model_name", "engine"]
         model_name = vllm_config.model_config.served_model_name
+        self.model_name = model_name
         max_model_len = vllm_config.model_config.max_model_len
 
         per_engine_labelvalues: dict[int, list[object]] = {
@@ -975,6 +976,18 @@ class PrometheusStatLogger(AggregateStatLoggerBase):
             self.histogram_kv_block_idle_before_evict = {}
             self.histogram_kv_block_reuse_gap = {}
 
+        #
+        # CUDAGraph metrics
+        #
+        self._counter_cudagraph_iterations_base = self._counter_cls(
+            name="vllm:cudagraph_iterations",
+            documentation=(
+                "Number of engine iterations by CUDA graph runtime mode."
+            ),
+            labelnames=labelnames + ["runtime_mode"],
+        )
+        self.counter_cudagraph_iterations: dict[str, dict[int, Counter]] = {}
+
         #
         # LoRA metrics
         #
@@ -1086,6 +1099,17 @@ class PrometheusStatLogger(AggregateStatLoggerBase):
                     for gap in event.reuse_gaps_seconds:
                         reuse_hist.observe(gap)
 
+            if scheduler_stats.cudagraph_stats is not None:
+                mode = scheduler_stats.cudagraph_stats.runtime_mode
+                if mode not in self.counter_cudagraph_iterations:
+                    self.counter_cudagraph_iterations[mode] = {
+                        idx: self._counter_cudagraph_iterations_base.labels(
+                            self.model_name, str(idx), mode
+                        )
+                        for idx in self.engine_indexes
+                    }
+                self.counter_cudagraph_iterations[mode][engine_idx].inc()
+
             if self.gauge_lora_info is not None:
                 running_lora_adapters = ",".join(
                     scheduler_stats.running_lora_adapters.keys()

vllm/v1/worker/gpu_model_runner.py

@@ -3431,14 +3431,12 @@ class GPUModelRunner(
                 # num_tokens_across_dp will no-longer be valid
                 assert batch_descriptor.num_tokens == num_tokens_padded
 
-        cudagraph_stats = None
+        cudagraph_stats = CUDAGraphStat(
-        if self.vllm_config.observability_config.cudagraph_metrics:
+            num_unpadded_tokens=num_tokens,
-            cudagraph_stats = CUDAGraphStat(
+            num_padded_tokens=batch_descriptor.num_tokens,
-                num_unpadded_tokens=num_tokens,
+            num_paddings=batch_descriptor.num_tokens - num_tokens,
-                num_padded_tokens=batch_descriptor.num_tokens,
+            runtime_mode=str(cudagraph_mode),
-                num_paddings=batch_descriptor.num_tokens - num_tokens,
+        )
-                runtime_mode=str(cudagraph_mode),
-            )
 
         return (
             cudagraph_mode,