Request logger、straggler 与 crash dump 证据链#

扩展与调试部分已经讲了 observability、request metrics exporter、dump 工具和 liveness，但如果没有一章把 request logger、straggler 样本和 crash dump 窗口材料真正串起来，维护层仍然会缺一条特别贴近事故调查现场的证据链：系统在请求收尾时怎样留下结构化首尾事实，又怎样把“最近发生了什么”“哪些请求特别慢”“crash 前后还挂着什么请求”分别放进不同容器里。

这章真正要补的，不是“还有哪些日志功能”，而是 request-level 事故证据怎样分层。只要这条分层读稳了，request logger、metrics exporter、dump / replay 和 liveness 章节就会开始自然咬合，而不会像几篇互相引用的工具说明。

先把“请求完成之后”看成一条分叉链，而不是一条日志语句#

很多读者会把 finished request 自然联想到“写一条日志”。对 SGLang 来说，请求完成之后其实会进入多条不同的证据分支。下面这张图的作用，就是把这些分支明确摆出来：

flowchart LR
    Finish["request finished"] --> Log["RequestLogger.log_finished_request()"]
    Finish --> Metrics["request metrics exporter"]
    Finish --> Dump["dump_request_list / thresholded flush"]
    Finish --> Crash["crash_dump_request_list (recent window)"]
    Finish --> Strag["straggler_request_list"]

这张图最重要的一点是：finished request 并不是只留下“一条日志”，而会根据不同调查目的被送进不同容器。这正是维护层和普通开发日志的主要差异之一。

RequestLogger 先提供的是结构化首尾事实#

utils/request_logger.py 里最重要的两个入口是：

  • log_received_request(...)
  • log_finished_request(...)

这两者特别值钱，因为它们正好卡在请求生命周期的首尾两端。也就是说，request logger 并不只是“记录一下运行中的打印信息”，而是在为后面的事故调查提供一条最稳的外部故事线：

  • 请求什么时候进入系统
  • 请求最终以什么 finish reason 结束
  • 请求参数和结果摘要是什么

只要这条首尾事实先站稳，后面再去看 crash dump、straggler 或 trace，维护者就不容易在一堆材料里失去请求本身的轮廓。

TokenizerManager 之所以还要额外维护三类请求列表，是因为事故调查天然需要不同粒度的证据#

光有 request logger 还不够，TokenizerManager 之上又明确叠了一层更偏事故调查的容器：

  • dump_request_list
  • crash_dump_request_list
  • straggler_request_list

这三个容器之所以值得技术书专门讲，不在于它们名字不同，而在于它们分别服务不同调查目的。

dump_request_list#

它更像定期批量落盘容器。系统会把达到阈值的一批请求统一 dump 到文件，而不是每完成一条就立刻碎片化写出。它适合回答“最近这一批请求整体长什么样”。

crash_dump_request_list#

它更偏事故窗口。真正 crash 时，它能和未完成请求一起被打包出去，帮助你在事故后还原“crash 前最近发生了什么”和“崩的时候还有哪些请求挂在系统里”。

straggler_request_list#

它是把慢请求从普通请求流里显式拎出来的证据槽。它回答的不是“最近所有请求怎样”，而是“那些尾部异常请求具体是哪几条”。

把这三者分清以后，你会更容易接受一个事实：SGLang 把请求证据分成了“常规结构化记录”“定期快照”“事故窗口”和“慢请求特写”四个调查层次，而不是只靠一份日志兜底。

dump_requests_threshold 暗示了证据收集本身也要控制成本#

TokenizerManager 默认会维护 dump_requests_threshold = 1000。这一点特别值得写进书里，因为它透露了一个很成熟的工程判断：

  • 系统不希望对每条请求都做重型持久化
  • 而是采用“攒到一定规模，再统一 dump”的策略

这样做的收益很直接：运行时干扰更低。代价也很明确：单条请求的即时证据可见性没那么强。也就是说，证据收集本身并不是零成本能力，系统会按调查目的和运行代价做分层。对维护者来说，这是非常应该明确知道的 tradeoff。

crash dump 的真正价值不是“更多日志”，而是更好的事故窗口#

crash_dump_request_list 最值得强调的地方，不是它会多保存点东西，而是它保留的是 crash 前最近的窗口材料。事故调查真正需要的往往不是全量历史，而是：

  • 崩溃前最近完成了哪些请求
  • 崩溃时还有哪些请求没完成

这两类材料一起看，才能更接近真实事故现场。也正因为这样，crash dump 的价值并不在“数量更多”，而在“时间窗口更对”。

straggler 之所以值得单独收集，是因为尾部问题天然会被淹没#

如果慢请求只存在于普通 finished log 里，它们几乎一定会被大量正常请求淹没。因此 straggler_request_list 的存在，本身就在承认一件很现实的事：

  • 尾部问题值得有自己的证据通道

这和前面关于 P99、streaming backlog、retract、watchdog 的章节会形成非常自然的回扣。整本书到这里开始不像“工具目录”，而更像一套真正互相支撑的维护体系。

这条链和 request metrics exporter 的边界#

上一章讲的是结构化 request-level 证据怎样正式落盘；这一章讲的则是请求日志与事故调查容器怎样组织。更稳的区分方式是：

  • exporter 更像长期、规则化的结构化数据积累
  • request logger / crash dump 更像值班与事故现场的证据收集

两者都重要，但用途完全不同。把这一点说清楚非常关键，否则维护者很容易误把“我已经有了 request metrics exporter”当成“事故现场就不需要 request logger 和 crash dump”。

真正调查一次事故时，更稳的使用顺序#

建议按下面顺序：

  1. 先看 log_received_request(...) / log_finished_request(...) 有没有形成首尾闭环。
  2. 如果问题不是单条，而是批量异常，再看 dump_request_list 的批量落盘内容。
  3. 如果发生 crash，再看 crash_dump_request_list 对应的窗口材料。
  4. 如果是尾部慢请求，再看 straggler_request_list 是否已经把异常样本拎出来。
  5. 最后再把这些材料和 metrics exporter、trace、dump / replay 一起交叉验证。

这条顺序最值钱的地方，在于它先用不同容器把事故材料分好层，再决定回哪条更重的证据链，而不是一开始就把所有材料混在一起看。

最容易出现的三种误判#

第一，误把 RequestLogger 看成普通 logger.info(...) 包装。
它真正提供的是请求首尾两端的结构化事实。

第二，误把 dump / crash / straggler 容器看成“同一种日志池子”。
更稳的理解是，它们分别服务不同调查场景。

第三，误以为有 exporter 以后，这一层就不重要了。
exporter 更偏长期结构化积累，而事故调查仍然需要窗口材料和慢请求特写。

小结#

这一章真正补齐的，是 request-level 证据在维护层里的最后一层组织方式：RequestLogger 提供首尾结构化记录，dump / crash / straggler 容器提供不同调查场景下的材料留存，它们再和 exporter、trace、replay 共同组成完整证据链。

到这里，扩展与调试部分就不只是在讲“有哪些工具”，而开始讲“这些证据容器到底怎样分工配合”。