Debug utils、dump 与低层证据采集#

这章解决什么问题#

到目前为止，扩展与调试这一节已经覆盖了 observability、tests、profiling、checklists 和故障工作流，但还缺最底下一层：当问题已经细到“我需要直接采集运行时材料、函数输入输出、kernel API 级证据”时，应该怎么办？

这一章就是把这层低级诊断工具拉回主线。否则整本书的维护层仍然会停在比较高层的 metrics / trace / tests，而缺少真正“贴着实现抓证据”的部分。

为什么 dump 工具值得进入技术书正文#

很多项目会把 dump / debug utils 当成内部脚本，不会在主书里认真讲。但对 inference runtime 来说，某些最棘手的问题恰恰只会在这里暴露：某个函数输入输出是否真的符合预期，某个 kernel 调用是否被正确记录，某个阶段的材料是否已落盘。

因此，debug utils 不只是开发者玩具，而是更深层证据链的一部分。

从哪里看这层能力#

python/sglang/kernel_api_logging.py、python/sglang/srt/debug_utils/*、test/registered/debug_utils/* 这类路径都说明，系统已经提供了低层材料采集与验证能力。它们并不替代 trace 和 profiler，而是在更接近实现的层面补充证据。

从技术书角度看，这层很重要，因为它告诉读者：如果高层证据不够，还可以往下继续收证，而不是只能猜。

本章对应哪些代码路径#

这一章的锚点包括 python/sglang/kernel_api_logging.py、python/sglang/srt/debug_utils/、test/registered/debug_utils/、python/sglang/profiler.py 以及相关 dump / trace 文件生成路径。

小结#

当一本技术书能把“高层观察”一直讲到底层证据采集，它就更接近一本真正能带着进复杂现场的书，而不只是一本原理读物。