用途
本技能用于把 SGLang 线上服务问题转化为可重放的调试路径。适用于：/health 或 /health_generate 不健康；服务负载下延迟或吞吐回退；队列增长但健康检查仍显示正常；某一类请求超时或挂起；服务器仅在某些请求之后崩溃；部署、拓扑变更或权重切换后输出发生变化；已知某旧提交正常而某新提交异常。
核心原则是采用单一循环：采集基线包、保存失败请求或崩溃转储、在干净目标上重放，之后才切换工具。不要一上来就做性能剖析（profiling）。本技能设计为与更聚焦的技能配合使用，而非重复实现它们：当重放加 coredump 指向 CUDA 崩溃路径时用 debug-cuda-crash；问题明显是 TP/PP/DP/EP 挂起时用 debug-distributed-hang；问题已收窄到计算侧路径时用 llm-torch-profiler-analysis。文中包含三个示例：低队列时间下的 TTFT 尖峰、重放优先的 CUDA 崩溃流程、请求形态相关的分布式挂起流程。
输出约定
需返回：问题类别、已检查内容、目前最强信号、当前最佳猜测、已排除项、下一步、生产风险。
工作流程
1. 采集基线包
若能访问线上服务器，在采取更具侵入性操作前采集只读包：
python3 scripts/incident_artifact_tool.py collect-bundle \
--base-url http://127.0.0.1:30000 \
--outdir /tmp/incident_bundle
python3 scripts/incident_artifact_tool.py summarize-bundle \
/tmp/incident_bundle
若服务器受保护：
python3 scripts/incident_artifact_tool.py collect-bundle \
--base-url http://127.0.0.1:30000 \
--token "$SGLANG_BEARER_TOKEN" \
--outdir /tmp/incident_bundle
采集脚本收集：/health、/health_generate、/model_info、/server_info、/v1/loads?include=all、/v1/loads?include=core,queues,disagg,spec、/metrics，以及尽力收集 /hicache/storage-backend。摘要用于快速查看：健康与实际健康状态、拓扑与运行时标志、某时点的队列与 token 使用、来自 Prometheus 指标的 TTFT / E2E / 队列时间启发式判断。若摘要显示服务器空闲时采集，应在有流量时重采，或快速转向转储加重放。若无线上服务器可访问，则从已有的最佳转储或日志开始：崩溃转储、请求转储、日志、CUDA coredump、OTel trace、torch profile。
2. 保存失败请求
仅在问题类别仍不清晰时阅读 references/decision-tree.md：服务器宕机或不健康、延迟或吞吐回退、输出或行为错误回退、间歇性超时或挂起。随后保存真正触发问题的请求负载：崩溃路径使用 --crash-dump-folder；非崩溃路径启用请求转储或保存确切的触发请求。不要从线上症状直接跳到低层调试而未先保存可重放内容。
3. 在干净目标上重放
需要帮助读取基线包或重放目标时阅读 references/endpoints-and-signals.md；需要重放、trace、profile 或二分路径时阅读 references/replay-trace-profile.md。标准顺序：采集基线包；捕获请求转储或崩溃转储；必要时重启干净调试目标；重放同一问题；采集重放时的日志与转储。
4. 仅在重放之后再深入
重放：存在崩溃转储、存在请求转储、问题依赖请求形态或负载组合时使用。若存在崩溃转储，先摘要：
python3 scripts/incident_artifact_tool.py summarize-dump \
--input-file /path/to/crash_dump.pkl
然后重放：
python3 /path/to/sglang/scripts/playground/replay_request_dump.py \
--input-file /path/to/crash_dump.pkl \
--host 127.0.0.1 \
--port 30000 \
--parallel 128
若 safe_pickle_load 阻止本地采集的可信转储，使用：
python3 scripts/replay_trusted_request_dump.py \
--input-file /path/to/request_dump.pkl \
--host 127.0.0.1 \
--port 30000 \
--parallel 1
若重放指向 CUDA 崩溃路径，在再次复现前以启用 coredump 的方式重启同一构建：
SGLANG_CUDA_COREDUMP=1 \
SGLANG_CUDA_COREDUMP_DIR=/tmp/sglang_cuda_coredumps \
python -m sglang.launch_server \
--model-path ... \
--crash-dump-folder /tmp/sglang_crash_dump \
...
随后检查生成的 coredump：
cuda-gdb "$(which python3)" \
-ex "target cudacore /tmp/sglang_cuda_coredumps/cuda_coredump_<host>.<pid>.<ts>"
重放优先的崩溃示例见 references/case-studies.md。
OTel trace：请求阶段时序不清、路由与 worker 归因不清、可能涉及 PD prefill/decode 传输时使用。若启动时已启用 tracing，可不重启改级别：
curl "http://127.0.0.1:30000/set_trace_level?level=1"
curl "http://127.0.0.1:30000/set_trace_level?level=2"
Torch profile：问题已收窄到计算侧归属、重放已能复现问题、指标与负载无法解释回退时使用。此时切换到 llm-torch-profiler-analysis，不要在此重复其剖析流程。低噪声延迟示例见 references/case-studies.md。
分布式挂起：若看起来是集合通信停滞，保存失败请求，在干净目标上重放，采集重放时的包与堆栈，然后切换到 debug-distributed-hang。该流程示例见 references/case-studies.md。
两个提交之间的回退：若已知一个提交正常、另一个异常，在深入手工调试前先构建确定性测试装置：选择稳定复现器（请求重放、基准命令或正确性检查）；让装置在正常行为时返回 0、异常行为时返回非零；运行 git bisect start <bad> <good>；运行 git bisect run <harness>；仅在隔离出候选提交后返回此处。当回退依赖请求形态或长时间运行的服务状态时，优先使用重放支持的二分。
6. 边界清晰时切换工具
故障类别清晰后切换：内核与重叠归因用 llm-torch-profiler-analysis；集合通信或 rank 分歧挂起用 debug-distributed-hang；CUDA 崩溃复现与内核 API 日志用 debug-cuda-crash。除非用户已有决定性日志或转储，否则不要在采集第一个包之前切换工具。
参考文档
仅按当前步骤需要加载：references/decision-tree.md（问题类别、工具切换点、返回形态）、references/endpoints-and-signals.md（端点行为、认证说明、字段解读）、references/replay-trace-profile.md（请求转储、崩溃转储、重放、trace、profiler 步骤、二分）、references/case-studies.md（重放优先 CUDA 崩溃、延迟、分布式挂起分诊的紧凑示例）。
脚本
scripts/incident_artifact_tool.py：采集只读线上包；把采集到的包摘要为精简调试记录；在重放前摘要可信请求转储或崩溃转储。
scripts/replay_trusted_request_dump.py：当 safe_pickle_load 阻止原版重放时，重放可信请求转储。
若已采集线上包，需包含其路径。若选择了重放、trace 或剖析，需说明为何包加转储仍不足够。