mcpField
S
sglang-prod-incident-triage

sglang-prod-incident-triage

github.com/bbufクラウド・DevOps1.1k94 回インストール今日更新
リポジトリ

sglang-prod-incident-triage について

SGLang の運用担当者向けに、ヘルス状態、性能、出力、クラッシュの問題を調べるデバッグスキルです。証拠の収集と問題リクエストの再生を優先し、その後に詳細分析や専門的なデバッグへ進みます。

主な機能

  1. 01稼働中の障害バンドルの収集と要約
  2. 02リクエストやクラッシュダンプの保存と再生
  3. 03トレース、プロファイル、コミット二分探索の案内
  4. 04構造化された障害レポートの定義

活用シーン

  1. 01サービングの遅延やスループット低下の調査
  2. 02保存したリクエストやダンプによるクラッシュ再現
  3. 03断続的なハングやタイムアウトの特定
  4. 04正常・異常が判明したコミットの比較

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/bbuf/ai-infra-auto-driven-skills --skill sglang-prod-incident-triage

インストール後、Claude Code で/sglang-prod-incident-triageを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
case-studies.md
decision-tree.md
endpoints-and-signals.md
replay-trace-profile.md
scripts/
incident_artifact_tool.py
replay_trusted_request_dump.py

詳細

SGLang サービングのデバッグ

過去の証拠を現在のブランチに適用する際は、メンテナンスされている ソースコントラクトを使用してください。レビュー／履歴のコーパスには、それぞれ独自の取得日が記録されています。今日のディスパッチや数値のデフォルト値を証明するものではありません。カーネルを置き換える場合は、エンドツーエンドテストでカバレッジを確認する前に、実際のモデルで候補が実行されることを検証してください。

概要

このスキルを使用して、稼働中のサービングの問題を、再実行可能なデバッグ手順に変換します。

次のループを使用します。

  • ベースラインバンドルを収集する
  • 失敗するリクエストまたはクラッシュダンプを保存する
  • クリーンな対象環境で再実行する
  • その後にのみ、ツールを切り替える

プロファイリングから始めないでください。

SGLang v0.5.21（2026-09-29）時点で、稼働中のサーバーに関して次の2つの追加シグナルが重要です。

  • --enable-session-radix-cache と /close_session：セッションを閉じ忘れたエージェントまたはRLロールアウトにより、原因不明のKV増加が発生しているように見える場合があります
  • オプトインのRust ingress（SGLANG_RUST_SERVER=1）にはAPIキーによる境界がありません。インシデントが認証関連の場合は、アプリケーションのトークンを疑う前に、実際にどのサーバーバイナリがリクエストを処理しているか確認してください

このスキルは、より対象を絞ったスキルを再実装せず、それらと連携して動作するようにしてください。

  • 再実行とコアダンプからCUDAクラッシュ経路が示された場合は、debug-cuda-crash
  • 問題が明らかにTP／PP／DP／EPのハングである場合は、debug-distributed-hang
  • 問題がすでに計算側の経路に絞り込まれている場合は、llm-torch-profiler-analysis

次の3つの例が含まれています。

  • キュー時間が短い状態でのTTFTの急増
  • 再実行を優先するCUDAクラッシュのフロー
  • リクエスト形状に応じた分散ハングのフロー

出力契約

次を返します。

  • 問題の分類
  • 確認した内容
  • 現時点で最も強いシグナル
  • 現時点での最有力な推測
  • 除外した可能性
  • 次のステップ
  • 本番環境へのリスク

使用するタイミング

  • /health または /health_generate が正常でない
  • サービング負荷時にレイテンシやスループットが低下した
  • ヘルス状態は正常に見えるのに、キューサイズが増加する
  • 特定のリクエストクラスだけタイムアウトまたはハングする
  • サーバーが特定のリクエストの後にのみクラッシュする
  • デプロイ、トポロジー変更、または重みの切り替え後に出力が変わった
  • 以前のコミットの1つは正常と分かっており、新しいコミットは異常と分かっている

ワークフロー

1. ベースラインバンドルを収集する

まずイングレスを確認します。Python の /server_info.frontend は python です。Rust イングレスには /v1/loads、/metrics、/configure_logging、/hicache/*、 /set_trace_level、/start_profile、/ready がありません。そこでの404は、イングレスの 制限によるものです。Rustのヘルス状態は、起動時のウォームアップが成功するまで503のままです。

稼働中のサーバーにアクセスできる場合は、より侵襲的な操作を行う前に、読み取り専用のバンドルを収集します。

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

バンドルスクリプトは次を収集します。

  • /ready
  • /health
  • /health_generate
  • /model_info
  • /server_info
  • /v1/loads?include=all
  • /v1/loads?include=core,queues,disagg,spec
  • /metrics
  • ベストエフォートでの /hicache/storage-backend

HiCacheの内容が古い、または破損しているという診断が有力な場合は、 POST /hicache/storage-backend/clear を呼び出す前に、バンドルと関連するリクエストダンプを取得してください。このエンドポイントは、接続されたバックエンドを切り離さずに、その内容を消去します。破壊的な操作として扱い、キャッシュされた内容を失っても問題ない場合に限って使用してください。アタッチ、デタッチ、消去の詳細については、 references/endpoints-and-signals.mdを参照してください。

概要を使用して、次をすばやく確認します。

  • ヘルス状態とアクティブなヘルス状態
  • トポロジーとランタイムフラグ
  • 特定時点でのキューとトークンの使用状況
  • Prometheusメトリクスから推測されるTTFT／E2E／キュー時間

サーバーがアイドル状態のときにバンドルを取得したと概要に記載されている場合は、トラフィックがあるときに再取得するか、速やかにダンプの取得と再実行に進んでください。

稼働中のサーバーにアクセスできない場合は、すでに利用可能な最良のダンプまたはログから開始します。

  • クラッシュダンプ
  • リクエストダンプ
  • ログ
  • CUDAコアダンプ
  • OTelトレース
  • torchプロファイル
2. 失敗するリクエストを保存する

問題の分類がまだ不明な場合にのみ、references/decision-tree.md を読んでください。

  • サーバーの停止または異常
  • レイテンシまたはスループットの低下
  • 出力の誤りまたは動作の回帰
  • 一時的なタイムアウトまたはハング

次に、問題を実際に引き起こすリクエストのペイロードを保存します。

  • クラッシュする場合：--crash-dump-folder を使用します
  • クラッシュしない場合：リクエストダンプを有効にするか、問題を引き起こすリクエストを正確に保存します

再生可能なものを保存する前に、実環境で発生している症状からいきなり低レベルのデバッグに進まないでください。

3. クリーンなターゲットで再生する

ベースラインバンドルまたは再生ターゲットの確認方法については、references/endpoints-and-signals.md を読んでください。

再生、トレース、プロファイル、または二分探索の方法が必要な場合は、references/replay-trace-profile.md を読んでください。

標準的な手順：

  1. ベースラインバンドルを収集する
  2. リクエストダンプまたはクラッシュダンプを取得する
  3. 必要に応じて、クリーンなデバッグターゲットを再起動する
  4. 同じ問題を再生する
  5. 再生中のログとダンプを収集する
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 のクラッシュ経路が示された場合は、コアダンプを有効にして同じビルドを再起動してから、もう一度再現します。

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 \
  ...

次に、生成されたコアダンプを調べます。

cuda-gdb "$(which python3)" \
  -ex "target cudacore /tmp/sglang_cuda_coredumps/cuda_coredump_<host>.<pid>.<ts>"

まず再生するクラッシュの例については、references/case-studies.md を読んでください。

OTel トレース

次の場合はトレースを使用します。

  • リクエストの各段階にかかる時間が不明
  • ルーターとワーカーのどちらに原因があるか不明
  • PD のプリフィル／デコード間の転送が関係している可能性がある

起動時にトレースが有効になっていた場合は、再起動せずにレベルを変更できます。

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 プロファイル

次の場合はプロファイリングを使用します。

  • 問題の原因がすでにコンピュート側に絞り込まれている
  • 再生で問題がすでに再現している
  • メトリクスと負荷では回帰を説明できない

この段階で、llm-torch-profiler-analysis に切り替えます。ここでそのプロファイリングワークフローを重複して説明しないでください。

ノイズの少ないレイテンシの例については、references/case-studies.md を読んでください。

分散ハング

集合通信の停止と思われる場合は、失敗するリクエストを保存し、クリーンなターゲットで再生して、再生中のバンドルとスタックを収集してから、debug-distributed-hang に切り替えます。

この手順の例については、references/case-studies.md を読んでください。

2 つのコミット間の回帰

あるコミットでは正常に動作し、別のコミットでは異常が発生することが分かっている場合は、さらに詳しく手動でデバッグする前に、決定論的なハーネスを作成します。

  1. 安定した再現方法を選びます：リクエストの再生、ベンチマークコマンド、または正当性チェック
  2. 正常な動作では 0、異常な動作では 0 以外を返すようにハーネスを作成します
  3. git bisect start <bad> <good> を実行します
  4. git bisect run <harness> を実行します
  5. 候補となるコミットが特定できたら、ここに戻ります

回帰がリクエストの形状または長時間稼働するサービング状態に依存する場合は、再生ベースの二分探索を優先します。

5. 原因の分類が明確になったらツールを切り替える

障害の分類が明確になった時点でツールを切り替えます。

  • カーネルとオーバーラップの原因特定には llm-torch-profiler-analysis
  • 集合通信またはランク間の不一致によるハングには debug-distributed-hang
  • CUDA クラッシュの再現とカーネル API のログ記録には debug-cuda-crash

ユーザーがすでに決定的なログまたはダンプを持っている場合を除き、最初のバンドルを収集する前にツールを切り替えないでください。

参考資料

現在のステップで必要なものだけを読み込みます。

スクリプト

  • scripts/incident_artifact_tool.py
    • 読み取り専用のライブバンドルを収集する
    • 収集したバンドルを簡潔なデバッグメモに要約する
    • 信頼できるリクエストダンプまたはクラッシュダンプをリプレイ前に要約する
  • scripts/replay_trusted_request_dump.py
    • safe_pickle_load によって標準のリプレイがブロックされる場合に、信頼できるリクエストダンプをリプレイする

ライブバンドルを収集した場合は、そのパスを記載してください。

リプレイ、トレース、またはプロファイリングを選択した場合は、バンドルとダンプだけでは不十分だった理由を説明してください。

現在のアップストリームのデバッグ制御 — 2026-10-05

SGLang リポジトリのコンパニオンスキルは、現在 .agents/skills/ にあります（#40515）。 debug-cuda-crash、debug-distributed-hang、generate-profile、および sglang-bisect-ci-regression です。実行する前に、リポジトリ内のコピーを確認してください。

環境キーが設定されていない場合、--crash-dump-folder X は CUDA コアダンプを設定し、 CUDA_COREDUMP_FILE=X/%h/core.cuda.%t.%p および CUDA_COREDUMP_PIPE=/tmp/corepipe.cuda.%h.%p を指定します。クラッシュ前は、py-spy と ユーザーが起動する CUDA ダンプがデフォルトで有効になり、コアダンプの待機時間は 60 s です。 SGLANG_CUDA_COREDUMP=1 は別の命名規則 cuda_coredump_%h.%p.%t を使用します。 インポート順に基づくコードの読み取りでは、すでに設定済みのパスが優先されます。この優先順位は GPU ではテストされていません。設定済みのパイプは、応答しなくなったカーネルもキャプチャできます。

出典：クラッシュダンプフック、 Rust のイングレス。

コメント

Markdown 対応