Profiling、trace 采样与性能回归证据#

这章解决什么问题#

很多系统在讲完 observability 和 testing 之后，仍然会缺一块：如果你怀疑是性能问题，或者你做了一次优化，究竟拿什么证明“它真的更快了、或者至少没有更慢”？这类问题并不完全属于 metrics，也不完全属于 benchmark，它更像“证据链”问题。

这一章要解决的，就是把 profiling、trace 采样和性能回归证据拉回整本书主线里。这样一来，扩展与调试部分就不只是“出了问题怎么看”，还会继续回答“改完之后拿什么证明变化是真的”。

profiler 和常规 trace 的差别#

从 python/sglang/profiler.py 和 docs/developer_guide/benchmark_and_profiling.md 看，SGLang 并不是只有在线 trace 或 Prometheus metrics。它还提供 profile trace 输出、profile-by-stage、merge profiles 等路径。这说明 profiling 的目的，不只是“再多收一点日志”，而是生成更适合性能分析的时间证据。

因此，profiling 章节和 observability 章节的边界也要讲清楚：observability 更偏持续可见性；profiling 更偏一次性、定点、面向诊断和优化的高密度证据。

为什么 bench 工具也属于证据链的一部分#

bench_one_batch.py、bench_serving.py、developer guide 里的 benchmark / profiling 文档都在说明一件事：性能判断不能只靠“感觉更快了”。你需要有一致的输入、已知的 profile 产物、可回放的 trace，甚至在需要时还要能把请求到达时间重放出来。

这也是为什么好技术书到后面会开始讲“怎么证明”。没有证据链，优化章节就很容易变成经验随笔；有了证据链，它才会变成可复用的方法。

一个更接近维护者的最小证据链#

发现性能异常
  -> 先看 metrics / trace 判断问题范围
    -> 需要更细粒度分析时打开 profiler
      -> 用 bench_one_batch / bench_serving / benchmark 文档组织输入
        -> 产出 trace / profile / benchmark 结果
          -> 对比前后变化

这条链本质上是在回答：当你怀疑系统慢了，或者觉得自己把它优化快了，到底怎样避免“只凭直觉得出结论”。

本章对应哪些代码路径#

这一章最重要的锚点包括 python/sglang/profiler.py、python/sglang/bench_one_batch.py、python/sglang/bench_serving.py、docs/developer_guide/benchmark_and_profiling.md 与 docs/developer_guide/bench_serving.md。

小结#

到了这一步，扩展与调试这一整个 section 才真正闭合：能看问题、能复现问题、能改问题，也能证明改动前后到底发生了什么。对一本更成熟的技术书来说，这层“证据意识”非常关键。