第九章可观测性与调试 on Machine Learning 学习笔记

9.1 request logger、trace 与 time stats

Mon, 01 Jan 0001 00:00:00 +0000

request logger、trace 与 time stats#

这一节会把最常见的观测入口先统一起来，解释 request logger、trace 和时间字段分别站在哪一层、解决什么问题。

为什么这三样要放在一起看#

很多人会把 request logger、trace 和时间字段当成三组并列工具：

logger 负责打印
trace 负责看链路
time stats 负责算延迟

但对 SGLang 来说，这三者更像同一条证据链的三个切面：

request logger 提供请求首尾事实
trace 提供阶段切片
ReqTimeStats 提供统一时间语义

如果把它们分开理解，第四部分后面的很多调试动作都会重新变得零散。

request logger 真正留下了什么#

RequestLogger 在请求首尾两端留下结构化事实。典型的日志行如下：

INFO: rid=7a3c21f8 | input=128 toks | output=64 toks | finish_reason=stop |
 TTFT=0.342s | E2E=2.187s | throughput=29.2 tok/s

这一行日志来自 python/sglang/srt/utils/request_logger.py，在请求结束时写入。它提供的不是 trace 级细节，而是：

rid：请求的全局唯一标识，用于跨层对照；
input / output token 数：最基础的输入输出规模；
finish_reason：请求是正常结束（stop）、达到长度上限（length），还是中途中止（abort）；
TTFT：time to first token，衡量首包延迟；
E2E：请求从到达到最后一个 token 送出的全程耗时。

对排障来说，request logger 的价值不在于它有多详细，而在于它把首尾事实钉住了。在用 trace 或 metrics 深入之前，先确认这一行是否存在、finish_reason 是否符合预期，能排掉一大类"请求是不是根本没完成"这类问题。

9.2 metrics、profiling 与 evidence

Mon, 01 Jan 0001 00:00:00 +0000

metrics、profiling 与 evidence#

这一节会解释 metrics、profiling 和更硬的证据面怎样彼此配合，避免把"有指标"误读成"已经能定位问题"。

metrics 和 profiling 为什么不能混看#

metrics 更适合回答"系统整体现在怎么样"，profiling 更适合回答"这一段为什么慢"。这两者都属于证据，但粒度和代价完全不同。

如果把它们混看，最常见的后果就是：

只看到整体吞吐变化，却不知道是哪个阶段变慢了；
或者 profile 看得太细，却没有先确认问题到底是不是整体趋势。

哪些 metrics 值得先看#

SGLang 在 /metrics 路径（Prometheus 格式）暴露系统指标。以下是排障中最先需要盯的几个：

请求状态类

sglang:num_running_reqs # 当前正在执行（在 forward pass 里）的请求数
sglang:num_waiting_reqs # 在 waiting queue 里等待的请求数
sglang:num_queue_reqs # 包含 grammar queue 的等待请求总数

这三个数字放在一起看，能立刻区分：

num_running 低但 num_waiting 高 → scheduler admission 有瓶颈，或 batch 成不起来
num_running 饱和，num_waiting 也高 → 正在正常工作，只是负载大
两者都低但延迟高 → 问题在单请求执行侧，不是吞吐侧

资源占用类

sglang:token_usage # KV cache 占用率（0.0 ~ 1.0），接近 1.0 代表显存紧张
sglang:gpu_memory_usage_bytes # GPU 显存绝对用量
sglang:cache_hit_ratio # RadixCache 前缀命中率

token_usage 接近 1.0 时，scheduler 会开始更激进地驱逐 KV，cache_hit_ratio 通常随之下降。这两个字段放在一起比单独看更有价值。

9.3 从症状到根因的调试路径

Mon, 01 Jan 0001 00:00:00 +0000

从症状到根因的调试路径#

这一节会给出一条更像运行手册的调试路线：先看什么、再排什么、哪些证据能真正缩小问题边界。

为什么这一节必须放在最后#

前面的调试章节已经把 request logger、trace、metrics、profiling、测试和回归路径分别讲出来了，但如果没有一节把它们重新压成一条工作顺序，读者在现场仍然很容易知道"有哪些工具"，却不知道"第一步到底该做什么"。

这一节的职责，就是把前面几节重新收束成三条从症状走到根因的具体路径。

场景一：请求高延迟或 P99 劣化#

症状：ttft_seconds 或 e2e_req_latency_seconds 的 P99 升高。

第一步：拉 metrics 确认资源状态：

curl http://localhost:30000/metrics | grep -E 'num_running|num_waiting|token_usage|cache_hit'

根据数字判断属于哪类问题：

现象	指向	下一步
`num_waiting` 远大于 `num_running`	调度瓶颈	看 `token_usage`：若 > 0.9，是 KV 压力导致 batch 受限
`token_usage` > 0.9，`cache_hit_ratio` 下降	KV 资源紧张	看 waiting queue 里请求的平均长度；考虑调整 `--mem-fraction-static`
`num_running` 饱和，`inter_token_latency` 正常	正常高负载	关注 `gen_throughput` 是否持续下降，考虑扩容
两者都低但 P99 高	单请求问题	进入第二步看 per-request trace

第二步：找到高延迟的单个请求，通过 rid 拿到它的 ReqTimeStats：

TTFT = 2.8s 但 prefill_start_time - tokenize_end_time = 2.3s

这说明高延迟的 2.3 秒发生在 waiting queue 里，不是 prefill 本身慢。对应的修方向是调度侧，不是 GPU 侧。

第九章 可观测性与调试 on Machine Learning 学习笔记

9.1 request logger、trace 与 time stats

request logger、trace 与 time stats#

为什么这三样要放在一起看#

request logger 真正留下了什么#

9.2 metrics、profiling 与 evidence

metrics、profiling 与 evidence#

metrics 和 profiling 为什么不能混看#

哪些 metrics 值得先看#

9.3 从症状到根因的调试路径

从症状到根因的调试路径#

为什么这一节必须放在最后#

场景一：请求高延迟或 P99 劣化#

第九章可观测性与调试 on Machine Learning 学习笔记