sgl-project/sglang · 作者 ishandhanani · 合并时间 2026-04-14 09:30
PR body明确指出，现有sglang:token_usage指标仅报告非可回收令牌（活跃请求+固定会话），排除了可回收的radix缓存节点，导致缓存池看起来比实际更空。这在代理式工作负载中尤为关键，因为子代理KV在完成后仍滞留在radix树中——token_usage可能显示约2%的使用率，而物理GPU内存实际消耗了72%。暴露原始计数让运维人员能够根据需要推导任何比率。
该PR值得快速浏览，特别是对于关注系统监控和内存管理的工程师。虽然实现简单，但设计决策值得注意：
由于review评论为空，未发现具体的技术讨论或争议点。PR由作者自行合并，表明变更可能较为直接或已通过其他渠道达成共识。
实现分为两个文件：
metrics_collector.py：在SchedulerStats数据类中新增三个整数字段kv_available_tokens、kv_evictable_tokens、kv_used_tokens；在SchedulerMetricsCollector类中创建对应的Prometheus Gauge指标；在log_stats()方法中添加日志记录逻辑。scheduler_runtime_checker_mixin.py：在update_scheduler_stats()方法中，将self.full_available_size、self.full_evictable_size、self.full_num_used三个内部属性值填充到传入的stats对象的相应字段中，完成数据传递。| 文件 | 模块 | 状态 | 重要度 |
|---|---|---|---|
python/sglang/srt/observability/metrics_collector.py |
observability | modified | 8.0 |
python/sglang/srt/managers/scheduler_runtime_checker_mixin.py |
scheduling | modified | 6.0 |
分析完成后，这里会展示 LLM 生成的相对完整源码片段和详细注释。
当前评论区没有形成足够清晰的争议点或结论，后续有更多讨论时会体现在这里。
风险较低，主要涉及：
sglang:，与现有指标（如sglang:token_usage）风格一致，无命名冲突风险。full_available_size、full_evictable_size、full_num_used等内部属性的正确性，若这些属性计算有误，将导致指标数据失真。影响范围：
当前没有检测到明确关联的 Issue 链接，后续同步到相关引用后会出现在这里。
本PR新增了三个Prometheus Gauge指标（sglang:kv_available_tokens、sglang:kv_evictable_tokens、sglang:kv_used_tokens），暴露KV缓存池的原始令牌计数，解决了现有token_usage指标无法反映可回收radix缓存节点导致内存监控失真的问题。变更集中在可观测性模块，对核心推理路径无影响，为运维人员提供了更灵活的内存使用分析能力，尤其适用于代理式工作负载场景。
现有sglang:token_usage指标仅报告非可回收令牌（活跃请求+固定会话），而可回收的radix缓存节点被排除在外。这导致缓存池看起来比实际更空，在代理式工作负载中可能产生误导——例如，token_usage显示约2%使用率时，物理GPU内存实际消耗了72%。PR作者指出，暴露原始计数能让运维人员在PromQL/Grafana中推导所需比率，如物理使用率或可回收比例，从而准确诊断内存问题。
实现涉及两个文件，改动简洁：
metrics_collector.py：
SchedulerStats数据类中添加三个整数字段：python
kv_available_tokens: int = 0
kv_evictable_tokens: int = 0
kv_used_tokens: int = 0SchedulerMetricsCollector类中创建对应的Prometheus Gauge对象，并设置名称、文档和标签。log_stats()方法中调用_log_gauge()更新指标值。scheduler_runtime_checker_mixin.py：
update_scheduler_stats()方法中，将内部属性值赋给stats对象：python
stats.kv_available_tokens = self.full_available_size
stats.kv_evictable_tokens = self.full_evictable_size
stats.kv_used_tokens = self.full_num_used由于review评论为空，未发现具体的技术讨论或争议。PR由作者自行合并，表明变更可能较为直接或已通过其他渠道达成共识。
风险：
full_available_size等内部属性的正确计算，若这些属性有误将导致指标失真。影响：
从近期历史PR看，本PR与以下变更相关：
整体上，本PR是sglang项目持续增强系统可观测性的一部分，特别是在KV缓存管理领域，为复杂工作负载下的内存分析提供了必要工具。
参与讨论