Study: vLLM Offload Metrics and RFC #44008

1. Current Statistics Method

Data Flow

[Worker 进程]                                  [EngineCore / Scheduler]              [Metrics Output]
     │                                                   │                                 │
     │ post_forward()                                    │                                 │
     │   └─ get_finished()                               │                                 │
     │        └─ record_transfer()                       │                                 │
     │             (收集 op_size, op_time, transfer_type) │                                 │
     │                                                   │                                 │
     │ get_kv_connector_stats()                          │                                 │
     │   └─ OffloadingConnectorStats ───────────────────→│ update_from_output()            │
     │                                                   │   └─ aggregate()                │
     │                                                   │   └─ make_stats()               │
     │                                                   │       └─ SchedulerStats         │
     │                                                   │           └─ kv_connector_stats │
     │                                                   │              ↓                  │
     │                                                   │    EngineCoreOutputs ──────────→│ StatLogger
     │                                                   │                                 │ ├─ LoggingStatLogger (stdout)
     │                                                   │                                 │ └─ PrometheusStatLogger (/metrics)

关键实现层级

层级	核心类	职责
数据容器	`OffloadingConnectorStats`	在 Worker 端暂存原始传输数据（`{类型: [MetricsList]}`）。
日志输出	`LoggingStatLogger` + `KVConnectorLogging`	周期性聚合数据并打印到标准输出。
指标暴露	`PrometheusStatLogger` + `OffloadPromMetrics`	将统计数据更新到 `prometheus_client` 提供的 `/metrics` 端点。

PrometheusStatLogger

本质就是解析内容，然后调用 prometheus_client SDK，这个 SDK 会自动提供 /metrics 端点（通过 make_asgi_app() 挂载到 Starlette 应用）。

2. Current Statistics Metrics

OffloadingConnectorStats

最终会生成以下 4 个核心指标：

GPU_to_CPU_total_bytes: 累计卸载字节数。
GPU_to_CPU_total_time: 累计卸载耗时。
CPU_to_GPU_total_bytes: 累计加载字节数。
CPU_to_GPU_total_time: 累计加载耗时。

内部数据结构：

@dataclass
class OffloadingOperationMetrics:
    op_size: int      # 传输的字节数
    op_time: float    # 传输耗时（秒）

class OffloadingConnectorStats:
    data: dict[str, list[OffloadingOperationMetrics]]
    # 示例: { "GPU_to_CPU": [Metrics(op_size=1024, op_time=0.5)], ... }

局限性： 缺乏 Offloading 特有的调度状态指标（如 Cache 使用率、Store 跳过数等）。

3. Significance of RFC #44008

RFC #44008 (Offloading Metrics Redesign) 旨在解决现有指标系统”硬编码且难以扩展”的问题。

3.1 核心痛点

可扩展性差：当前逻辑是写死在 Connector 里的，新增 Manager 层指标（如 stores_skipped）需要修改多处代码。
缺乏调度视角：目前只能看到”搬运了多少数据”，看不到”CPU 缓存用了多少”或”有多少请求被阻塞等待”。

3.2 改进方案

提出 Metadata-driven 的通用指标设计：

通用元数据注册表：Connector 和 Manager 在初始化时注册自己的指标定义。
类型化聚合：明确定义 Counter（求和）、Gauge（取最新值）、Histogram（拼接样本）的聚合规则。
预注册 Prometheus 对象：在 __init__ 阶段创建好所有 Metric 对象，避免热路径中的懒加载和字符串切片。

3.3 后续指标扩展

通过 RFC 的实施，未来将增加关键的可观测性指标：

Cache 使用率：vllm:kv_offload_cache_usage (Gauge)，监控 CPU 缓存水位。
跳过计数：vllm:kv_offload_stores_skipped (Counter)，反映复用或过滤掉的 Block 数。

3.4 相关 PR

PR	状态	内容
#35669	Open, Changes Requested	实现 `OffloadingManager.get_stats()` + manager stats 聚合
#43877	Open	修复 scheduler 层 stats 收集时序（先 update 再提取）+ worker/scheduler 聚合
#44008	Open (RFC)	设计文档，定义 metadata-driven 架构