# PR #23595 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Deprecate --collect-tokens-histogram, auto-collect with --enable-metrics
- 合并时间：2026-04-25 03:00
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/23595

---

# 执行摘要

- 一句话：弃用 --collect-tokens-histogram，由 --enable-metrics 自动收集
- 推荐动作：该 PR 属于配置简化类变更，技术深度不高。但如果需要了解 SGLang 的可观测性配置或如何优雅地弃用 CLI 参数（DeprecatedAction），值得快速阅读。对于普通开发、运维人员，建议了解变更后将 --collect-tokens-histogram 从部署脚本中移除。

# 功能与动机

来自 PR body：移除单独的 `--collect-tokens-histogram` 标志；token 直方图现在在设置了 `--enable-metrics` 时总是被收集。`TokenizerMetricsCollector` 仅在一个 `if enable_metrics` 守卫内被实例化，因此额外的标志是冗余的。

# 实现拆解

1. **移除 ServerArgs 字段**：在 `python/sglang/srt/server_args.py` 中删除 `collect_tokens_histogram: bool = False` 字段定义。
2. **修改 CLI 参数**：在 `add_cli_args` 中将 `--collect-tokens-histogram` 的 action 改为 `DeprecatedAction`，帮助信息提示该参数已弃用。
3. **更新 TokenizerMetricsCollector**：在 `python/sglang/srt/observability/metrics_collector.py` 中移除了构造函数的 `collect_tokens_histogram` 参数，并删除了直方图创建和报告时的条件判断，现在始终创建和记录这两个直方图。
4. **调整调用方**：在 `python/sglang/srt/managers/tokenizer_manager.py` 的 `init_metric_collector_watchdog` 中移除了 `collect_tokens_histogram=self.server_args.collect_tokens_histogram` 参数传递（因为该字段已不存在）。
5. **保留向后兼容**：通过 `DeprecatedAction`，用户仍可传递 `--collect-tokens-histogram`，但会收到弃用警告并正常启动。

关键文件：
- `python/sglang/srt/observability/metrics_collector.py`（模块 可观测性；类别 source；类型 core-logic；符号 TokenizerMetricsCollector.__init__, TokenizerMetricsCollector.report）: 核心变更文件，移除了 collect_tokens_histogram 参数和条件判断，改为始终创建和记录 token 直方图。
- `python/sglang/srt/server_args.py`（模块 服务配置；类别 source；类型 core-logic；符号 ServerArgs, add_cli_args）: 移除了 collect_tokens_histogram 字段定义，并将 CLI 参数 action 改为 DeprecatedAction。
- `python/sglang/srt/managers/tokenizer_manager.py`（模块 令牌管理器；类别 source；类型 core-logic；符号 init_metric_collector_watchdog）: 移除了实例化 TokenizerMetricsCollector 时传递 collect_tokens_histogram 参数。

关键符号：TokenizerMetricsCollector.__init__, TokenizerMetricsCollector.report, ServerArgs.__init__, add_cli_args, init_metric_collector_watchdog

## 关键源码片段

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

核心变更文件，移除了 collect_tokens_histogram 参数和条件判断，改为始终创建和记录 token 直方图。

```python
class TokenizerMetricsCollector:
    def __init__(
        self,
        server_args: Optional[ServerArgs] = None,
        labels: Dict[str, str] = None,
        bucket_time_to_first_token: Optional[List[float]] = None,
        bucket_inter_token_latency: Optional[List[float]] = None,
        bucket_e2e_request_latency: Optional[List[float]] = None,
        # 移除了 collect_tokens_histogram 参数
    ) -> None:
        from prometheus_client import Counter, Histogram

        self.labels = labels or {}
        # 不再保存 collect_tokens_histogram 标志

        # 始终创建两个 token 计数的 Counter
        self.prompt_tokens_total = Counter(...)
        self.generation_tokens_total = Counter(...)

        # 始终创建直方图，不再条件判断
        default_bucket_prompt_tokens = [
            100, 300, 500, 700, 1000, 1500, 2000, 3000, 4000, 5000,
            6000, 7000, 8000, 9000, 10000, 12000, 15000, 20000, 22000,
            25000, 30000, 35000, 40000, 66000, 99000, 132000, 300000,
            600000, 900000, 1100000
        ]
        self.prompt_tokens_histogram = Histogram(
            name='sglang:prompt_tokens_histogram',
            documentation='Histogram of prompt token length.',
            labelnames=labels.keys(),
            buckets=generate_buckets(
                server_args.prompt_tokens_buckets, default_bucket_prompt_tokens
            ),
        )
        self.generation_tokens_histogram = Histogram(
            name='sglang:generation_tokens_histogram',
            documentation='Histogram of generation token length.',
            labelnames=labels.keys(),
            buckets=generate_buckets(
                server_args.generation_tokens_buckets, default_bucket_prompt_tokens
            ),
        )
        # ... 其他计数器

    def report(self, ...):
        # ... 其他指标报告
        # 直接记录直方图，不再检查 self.collect_tokens_histogram
        self.prompt_tokens_histogram.labels(**labels).observe(float(prompt_tokens))
        self.generation_tokens_histogram.labels(**labels).observe(float(generation_tokens))

```

# 评论区精华

PR 没有收到 review 评论。作者 merrymercy 在评论中执行了 /tag-and-rerun-ci 来触发 CI。未发现有实质性的设计讨论或争议。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险极低。核心风险包括：
 - **默认行为变更**：原本仅显式启用 --collect-tokens-histogram 才会收集直方图，现在只要 --enable-metrics 就会自动收集。可能带来轻微的内存和性能开销（两个 Histogram 对象），但通常可忽略。
 - **向后兼容**：保留的 DeprecatedAction 确保现有脚本不会报错。
 - **无测试配套**：本次变更没有附带测试文件修改，存在回归隐患，但影响范围小，历史测试应能覆盖。
 - 影响：
 - **用户**：多数用户无需修改启动命令；依赖 --collect-tokens-histogram 的脚本仍可运行但会收到弃用警告。用户将获得一致的直方图数据（之前可能因遗忘而未启用）。
 - **系统**：在启用 metrics 的所有部署中，prompt 和 generation token 直方图总是可用，提升了指标的可观测性。
 - **团队**：减少了需要维护的 CLI 参数数量，降低了文档和配置的复杂度。
 - 风险标记：默认行为变更 , 低内存开销 , 向后兼容

# 关联脉络

- 暂无明显关联 PR