# PR #24341 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Refactor device timer installation and rename prefill prealloc to bootstrap
- 合并时间：2026-05-05 04:57
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/24341

---

# 执行摘要

- 一句话：重命名 PD 指标并提取设备计时器安装方法
- 推荐动作：该 PR 是适度的重构，值得学习其提取惯用法和统一命名的实践。可观测性相关开发者应关注指标名称变更，及时更新仪表盘。

# 功能与动机

PR body 明确指出需要重命名 `prefill_prealloc` 为 `prefill_bootstrap` 并提取设备计时器安装逻辑，以提升代码可读性和维护性。

# 实现拆解

1. **在 `SchedulerMetricsMixin` 中新增 `install_device_timer_on_runners` 方法**：该方法检查 `self.forward_pass_device_timer` 是否存在，若存在则将其赋值给 `tp_worker.model_runner` 以及草稿模型的所有运行器（`draft_runner` 和 `draft_runner_list`），集中管理设备计时器的挂载。
2. **在 `scheduler.py` 的 `__init__` 中替换内联逻辑**：调用 `init_model_worker()` 后立即调用 `self.install_device_timer_on_runners()`，并删除原先位于 `init_model_worker` 末尾的 12 行内联代码，消除重复。
3. **统一重命名 `prefill_prealloc` 为 `prefill_bootstrap`**：在 `io_struct.py`、`metrics_collector.py`、`scheduler_metrics_mixin.py`、`scheduler_runtime_checker_mixin.py` 中同步替换所有 `prefill_prealloc` 引用（包括字段名、Gauge 名称、日志消息、文档注释）。
4. **测试与配置**：变动仅涉及源码与可观测性基础设施，无测试文件变更；CI 通过验证了基本正确性。

关键文件：
- `python/sglang/srt/observability/scheduler_metrics_mixin.py`（模块 调度指标；类别 source；类型 core-logic；符号 install_device_timer_on_runners）: 新增 `install_device_timer_on_runners` 方法，并统一重命名指标字段和日志。
- `python/sglang/srt/managers/scheduler.py`（模块 调度器；类别 source；类型 core-logic）: 移除内联设备计时器安装逻辑，改为统一调用新方法，简化 `init_model_worker`。
- `python/sglang/srt/observability/metrics_collector.py`（模块 指标收集；类别 source；类型 core-logic）: 重命名 SchedulerStats 字段及对应的 Prometheus Gauge 注册，反映指标名称变更。
- `python/sglang/srt/managers/scheduler_runtime_checker_mixin.py`（模块 运行时检查；类别 source；类型 core-logic）: 在 idle 指标收集中使用新的字段名。
- `python/sglang/srt/managers/io_struct.py`（模块 I/O 结构；类别 source；类型 core-logic）: 重命名 DisaggregationMetrics 数据类中的字段和元数据。

关键符号：install_device_timer_on_runners

## 关键源码片段

### `python/sglang/srt/observability/scheduler_metrics_mixin.py`

新增 `install_device_timer_on_runners` 方法，并统一重命名指标字段和日志。

```python
# python/sglang/srt/observability/scheduler_metrics_mixin.py

# 在 __init__ 中完成 DeviceTimer 初始化后，新增此方法用于安装计时器到运行器
def install_device_timer_on_runners(self: Scheduler):
    if not hasattr(self, "forward_pass_device_timer"):
        return
    timer = self.forward_pass_device_timer
    # 安装到主模型运行器
    self.tp_worker.model_runner.device_timer = timer
    # 安装到草稿模型运行器（如果存在）
    if self.draft_worker is not None:
        dw = getattr(self.draft_worker, "draft_worker", None)
        if dw is not None:
            if hasattr(dw, "draft_runner"):
                dw.draft_runner.device_timer = timer
            # 处理多草稿运行器列表
            for r in getattr(dw, "draft_runner_list", []):
                r.device_timer = timer

# 在 report_prefill_stats 中，日志消息从 "#prealloc-req" 改为 "#bootstrap-req"
# 同时统计字段从 num_prefill_prealloc_queue_reqs 改为 num_prefill_bootstrap_queue_reqs

```

### `python/sglang/srt/managers/scheduler.py`

移除内联设备计时器安装逻辑，改为统一调用新方法，简化 `init_model_worker`。

```python
# python/sglang/srt/managers/scheduler.py

# 在 __init__ 的初始化方法链中，init_model_worker 后紧跟安装设备计时器
self.init_model_worker()
self.install_device_timer_on_runners()  # 新增：集中安装设备计时器

# 同时删除了 init_model_worker 末尾的以下内联代码（不再重复）：
# if hasattr(self, "forward_pass_device_timer"):
# timer = self.forward_pass_device_timer
# self.tp_worker.model_runner.device_timer = timer
# ...

```

# 评论区精华

无 review 讨论或评论。

- 暂无高价值评论线程

# 风险与影响

- 风险：
 - **兼容性风险**：Prometheus gauge 名称从 `sglang:num_prefill_prealloc_queue_reqs` 改为 `sglang:num_prefill_bootstrap_queue_reqs`，如果外部监控或告警依赖旧名称，会短暂失效。
 - **回归风险低**：重命名仅为机械替换，设备计时器提取逻辑与之前等价，但仍需关注草稿运行器 `draft_worker_list` 等边缘情况。
- 影响：
 - **对用户**：如果用户直接查询 `num_prefill_prealloc_queue_reqs` 指标，需要更新查询语句。日志中 `#prealloc-req` 变为 `#bootstrap-req`，不影响程序功能。
 - **对系统**：无性能影响。
 - **对团队**：代码清理降低了未来理解成本，命名更符合实际语义（`bootstrap` 比 `prealloc` 更贴切）。
 - 风险标记：指标名称变更可能破坏外部监控 , 无测试覆盖

# 关联脉络

- PR #24359 Minor scheduler fixes: 同属调度器模块，近期有相关维护，但本 PR 与之无直接依赖。
- PR #24350 [tiny] misc cleanups across configs, attention, jit_kernel: 也涉及命名清理，体现团队持续改进代码风格。