执行摘要

本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中推导所需比率，如物理使用率或可回收比例，从而准确诊断内存问题。

实现拆解

实现涉及两个文件，改动简洁：

1. metrics_collector.py：

   • 在SchedulerStats数据类中添加三个整数字段：
     

     kv_available_tokens: int = 0
     kv_evictable_tokens: int = 0
     kv_used_tokens: int = 0
     

   • 在SchedulerMetricsCollector类中创建对应的Prometheus Gauge对象，并设置名称、文档和标签。
   • 在log_stats()方法中调用_log_gauge()更新指标值。

2. scheduler_runtime_checker_mixin.py：

   • 在update_scheduler_stats()方法中，将内部属性值赋给stats对象：
     

     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等内部属性的正确计算，若这些属性有误将导致指标失真。
• 新增指标可能引入微小性能开销，但通常可忽略。
• 无兼容性风险，因为纯新增字段和指标。

影响：

• 运维团队获得更细粒度的KV缓存监控，可灵活计算衍生指标，提升内存问题诊断能力。
• 系统增加三个Prometheus时间序列，存储开销轻微。
• 代码变更集中在可观测性模块，易于维护。

关联脉络

从近期历史PR看，本PR与以下变更相关：

• PR #22331（澄清HiSparse解码令牌使用日志）：同属可观测性改进，但聚焦日志而非指标。
• PR #22506（网关毫秒级日志支持）：扩展了可观测性能力，但针对日志精度。
• PR #21971（跳过嵌入模式KV缓存）：涉及KV缓存性能优化，而本PR提供更细监控。

整体上，本PR是sglang项目持续增强系统可观测性的一部分，特别是在KV缓存管理领域，为复杂工作负载下的内存分析提供了必要工具。