8.1 观测、Tracing 与调试抓手

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

观测、Tracing 与调试抓手#

这章解决什么问题#

这一章解决的是“当系统已经跑起来之后，出了问题先看哪里”。如果前面章节主要回答“系统怎样设计、代码在哪里”，这一章则回答“当请求异常、延迟波动、输出不稳定，或者你要定位瓶颈时，哪些 observability 和 debug 入口最值得先抓”。

这类内容不能混进前面的主线章节里讲。因为它们更多是操作层，而不是结构层。但如果完全不单独成章，读者又会在真正出问题时不知道该从 metrics、logging、trace、request dump 还是 crash dump 开始。

为什么 observability 需要独立章节#

官方 docs/advanced_features/observability.md 已经把 observability 分成三块：Production Metrics、Logging、Request Dump and Replay / Crash Dump and Replay。这种划分很有代表性，因为它说明 SGLang 并没有把“观测”理解成只有 Prometheus 指标，而是把 metrics、logs 和可复现材料都纳入观测体系。

更进一步，docs/references/production_request_trace.md 明确说 request trace 的实现落在 python/sglang/srt/observability/req_time_stats.py。这很重要，因为它把“文档层讲 tracing”与“源码层定义 request stage”连到了一起。也就是说，观测不是外围运营面板，而是 runtime 自己的一部分。

下面这张图的职责，是把 metrics、trace 和 dump / replay 这三种抓手放进同一条排障路径里。这样读者不必再靠记忆去猜“到底先看哪个”，而是能直接看出从轻量观测到重型复现的升级顺序。

flowchart TD
 A["异常 / 延迟 / 输出不稳定"] --> B["Metrics\n--enable-metrics / /metrics"]
 B --> C{"问题是整体性的\n还是个别请求?"}
 C -->|整体趋势| D["Prometheus / production_metrics"]
 C -->|单请求 / 阶段性| E["Trace\n--enable-trace / OTLP / Jaeger"]
 E --> F["req_time_stats.py\nRequestStage slices"]
 D --> G["需要更具体样本?"]
 F --> G
 G -->|是| H["Request dump / crash dump"]
 H --> I["scripts/playground/replay_request_dump.py"]
 G -->|否| J["回到对应 runtime 模块定位"]

这张图相对于段落的增量，是把“趋势问题”“阶段问题”“复现问题”拆成三个不同层次。后文再谈具体 flags 和文件路径时，读者就不会把所有调试手段混成一个平面列表。

8.2 扩展点与维护路径

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

扩展点与维护路径#

这章解决什么问题#

这一章解决的是“如果你不只是阅读 SGLang，而是准备修改它，应该从哪里下手”。这包括两类常见需求：一类是功能扩展，例如支持新模型、调整 parser、增加协议适配；另一类是维护性工作，例如加测试、跑回归、按贡献流程提交变更。

如果没有这一章，前面的章节会把系统讲清楚，但读者仍然会缺少一个问题的答案：知道系统怎么工作之后，下一步怎样安全地改它。这也是为什么本章要放在最后，它更像“把理解转成可操作路径”的收束章。

为什么扩展点不能只靠目录猜#

目录当然能给提示，但真正的扩展点最好看官方维护文档。docs/supported_models/extending/support_new_models.md 明确说明：支持新的语言模型，通常只需要在 python/sglang/srt/models 下增加一个文件；如果是多模态模型，还要额外考虑 model_config.py、conversation.py、multimodal processor、image feature extraction 和 multimodal token 处理等组件。

这比简单说“去 models 目录改”更有价值，因为它告诉你：扩展点不仅是文件位置，还包括一组必须一起成立的适配面。也正因为这样，本章不会把“支持新模型”简化成单点改动，而会把它当作一条跨模块路径来讲。

扩展路径本身也适合用图来收束，因为它横跨文档、源码和测试。下面这张图回答的是：一个“想改 SGLang”的工程任务，通常会穿过哪些入口，而不是停留在哪个单独目录。

flowchart LR
 A["扩展目标\n新模型 / 新协议 / 新 parser / 新 hook"] --> B["阅读入口\nsupport_new_models.md\ncontribution_guide.md\ntest/README.md"]
 B --> C["源码扩展面\nmodels / entrypoints / parser / multimodal"]
 C --> D["验证路径\nunit tests / server tests / bench_one_batch / benchmark"]
 D --> E["贡献路径\npre-commit / CI / PR / review"]

这张图比纯文字多解释了一点：扩展并不是“改完源码再说”，而是一条从设计入口到验证入口再到贡献入口的闭环。也正因为这样，本章会把测试和贡献流程看成扩展点的一部分，而不是附录。

模型扩展与协议扩展分别落在哪里#

模型扩展更偏 python/sglang/srt/models/、相关 config、processor 和测试路径。support_new_models.md 还给出了调试建议：用 Hugging Face 参考输出与 python3 -m sglang.bench_one_batch --correct --model ... 进行对比，并把模型加入测试套件与 benchmark。这说明扩展不是只让代码“能跑”，而是要让它进入长期维护路径。

8. 扩展与调试 on Machine Learning 学习笔记

8.1 观测、Tracing 与调试抓手

观测、Tracing 与调试抓手#

这章解决什么问题#

为什么 observability 需要独立章节#

8.2 扩展点与维护路径

扩展点与维护路径#

这章解决什么问题#

为什么扩展点不能只靠目录猜#

模型扩展与协议扩展分别落在哪里#