# NCCL/RDMA fabric failureの観測・診断・復旧設計

CURRENT_STATUS: CURRENT
OBSERVATION: SPEC_ONLY
FRESHNESS: CURRENT
PAGE_TYPE: reference
CANONICAL_URL: /tools/ea-749-nccl-rdma-fabric-failure
CLAIM_IDS: none
EVIDENCE_IDS: EVD-EA-749-URL-FFF3B3BBB6F0, EVD-EA-749-URL-045F80529C89, EVD-EA-749-URL-29D01659A58E, EVD-EA-749-URL-D56263F64718, EVD-EA-749-URL-9D7E75E24ECD, EVD-EA-749-URL-64C290BB7C2D, EA-749-CURRENT-APPROVAL, EA-749-CURRENT-BODY-READBACK
UNKNOWN_IDS: EA-749-UNKNOWN-01
OPS_IDS: none

## Summary
「NCCL/RDMA障害はNCCL errorだけで根因を決めず、RAS/diagnostics、GPU・NVLink・PCIe、NIC/RDMA、fabric、nccl-tests、framework eventを同一incidentで相関し、fault domainを段階的に狭める。正常時baselineを保存し、復旧後も同条件で再検証する。version依存の診断機能と設定はlive環境で確認する。」

## Current judgment
「NCCL/RDMA障害はNCCL errorだけで根因を決めず、RAS/diagnostics、GPU・NVLink・PCIe、NIC/RDMA、fabric、nccl-tests、framework eventを同一incidentで相関し、fault domainを段階的に狭める。正常時baselineを保存し、復旧後も同条件で再検証する。version依存の診断機能と設定はlive環境で確認する。」

## Scope
NCCL/RDMA fabric failureの観測・診断・復旧設計

## Confirmed

## UNKNOWN
- EA-749-UNKNOWN-01: - 実clusterでのNCCL/CUDA/driver/DCGM/NIC firmwareのversion matrix
- 各rail・switch portまでrank/GPU/NICを結ぶinventoryの完全性
- grey failure検知に使うcounterの組織固有threshold
- frameworkごとのrank failure時restart semanticsとcheckpoint loss
- cloud-managed fabricで利用者に公開されないswitch/telemetry範囲
- active diagnosticsの実行costとproduction preflight頻度

## Evidence
- EVD-EA-749-URL-FFF3B3BBB6F0 (RESEARCH): NVIDIA NCCL 2.32.3, Troubleshooting: — https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting.html
- EVD-EA-749-URL-045F80529C89 (RESEARCH): NVIDIA NCCL 2.32.3, RAS: — https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting/ras.html
- EVD-EA-749-URL-29D01659A58E (RESEARCH): NVIDIA NCCL 2.32.3, Diagnostics: — https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting/diagnostics.html
- EVD-EA-749-URL-D56263F64718 (RESEARCH): NVIDIA NCCL 2.32.3, Networking Troubleshooting: — https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting/networking_troubleshooting.html
- EVD-EA-749-URL-9D7E75E24ECD (RESEARCH): NVIDIA GPU Debug Guidelines, GPU Node Triage: — https://docs.nvidia.com/deploy/gpu-debug-guidelines/gpu-node-triage.html
- EVD-EA-749-URL-64C290BB7C2D (RESEARCH): NVIDIA NCCL Documentation Archives (2.30.7 / 2.31.2 / 2.32.3): — https://docs.nvidia.com/deeplearning/nccl/archives/index.html
- EA-749-CURRENT-APPROVAL (RESEARCH): 現行本文の監査・revision対応
- EA-749-CURRENT-BODY-READBACK (IMPL): 現行本文の収録照合

## Failure / limits
典型的なfailureは、NCCL timeoutを見てNCCL環境変数を先に変更し、hardware/fabric degradationを隠すことです。NCCL Networking Troubleshootingは、InfiniBandでは`ibstat`/`ibstatus`によるlink state/rate、`ib_write_bw`/`ib_write_lat`によるbandwidth/latency、`rdma statistic`のretry/error、`perfquery`や`ibdiagnet`によるfabric診断を案内しています。RoCEでは`ethtool -S`、PFC/ECN/CNP/queue drop等のcounter、`rping`等を確認します。

GPU/node側も切り分けます。NVIDIA GPU Debug GuidelinesはDCGM diagnosticsをproduction node health/readiness検査として位置付け、network性能は`nccl-tests`の`all_reduce_perf`等でbaselineを取得し、slow pairを別nodeとのpairwise testで再検証して問題node/railを絞ることを推奨しています。したがって「job失敗時だけ測る」のではなく、正常時baselineを保存して差分で判断する方が有効です。

grey failureにも注意が必要です。linkがUPでもerror増加、tail latency、retransmission、driver/firmware異常でcollective全体が遅くなることがあります。単純なup/down health checkだけでは不足します。
## Failure / limits
active diagnosticsが成功しても、application traffic時だけ発生するcongestion、scale依存、thermal/power、intermittent grey failure、framework-level deadlockを否定できません。逆にdiagnostic failureも、即座に特定hardware部品の故障を証明するとは限りません。

`nccl-tests`のbaselineは有用ですが、collective、message size、node count、topology、GPU/NIC generation、routing、background trafficが違えば性能期待値も変わります。別clusterの数値を固定thresholdとして流用せず、自環境baselineと同条件比較を優先します。
## 主要claim
分散GPU workloadのhang・collective timeout・性能急落を、NCCL errorだけから単一のroot causeへ直結させてはいけません。NCCL 2.32.3の公式Troubleshootingは、built-in Diagnostics、GPU troubleshooting、Networking Troubleshooting、Runtime/MPI、Performance/Tuning、Logging、RASを別レイヤーとして案内しています。NCCL RASは2.24以降、実行中jobの状態を低overheadで収集し、unresponsive process等のoutlierを見つけて「疑わしい箇所を絞る」機構です。NVIDIA自身も、RAS情報からsystem log analysis等の別手法へ進んでroot causeを狭める設計を示しており、RAS単独の自動根因判定器として扱うのは不適切です。

NCCL 2.31以降のbuilt-in diagnosticsは、RAS diagnosticsとactive diagnosticsを分離します。RAS diagnosticsはGPU inventory、CUDA/driver、NCCL configuration等をrank間で比較するreadiness probeであり、NCCL data path自体をexerciseしません。active diagnosticsはcommunicator initialization時に実通信pathへdataを流し、GPU間P2Pやnetwork pathを検証します。したがって「設定整合性」「GPU/NVLink/PCIe」「NIC/RDMA」「fabric」「NCCL collective」「framework/process」の観測を段階化し、どの層で異常が再現するかを記録する必要があります。

## 運用上の意味・failure
典型的なfailureは、NCCL timeoutを見てNCCL環境変数を先に変更し、hardware/fabric degradationを隠すことです。NCCL Networking Troubleshootingは、InfiniBandでは`ibstat`/`ibstatus`によるlink state/rate、`ib_write_bw`/`ib_write_lat`によるbandwidth/latency、`rdma statistic`のretry/error、`perfquery`や`ibdiagnet`によるfabric診断を案内しています。RoCEでは`ethtool -S`、PFC/ECN/CNP/queue drop等のcounter、`rping`等を確認します。

GPU/node側も切り分けます。NVIDIA GPU Debug GuidelinesはDCGM diagnosticsをproduction node health/readiness検査として位置付け、network性能は`nccl-tests`の`all_reduce_perf`等でbaselineを取得し、slow pairを別nodeとのpairwise testで再検証して問題node/railを絞ることを推奨しています。したがって「job失敗時だけ測る」のではなく、正常時baselineを保存して差分で判断する方が有効です。

grey failureにも注意が必要です。linkがUPでもerror増加、tail latency、retransmission、driver/firmware異常でcollective全体が遅くなることがあります。単純なup/down health checkだけでは不足します。

## 具体的control / implementation implication
1. jobごとに `job_id`, `rank`, `host`, `gpu_uuid`, `nic/hca`, `rail`, `NCCL version`, `CUDA/driver`, `NCCL config fingerprint`, `topology snapshot` を紐付けます。
2. NCCL RASを有効なversionでは常時観測面として使い、hang/crash時にprocess/communicator状態とoutlierを取得します。RASの指摘はroot causeではなく「次に調べる対象」として保存します。
3. NCCL 2.31+では、事前readinessにRAS diagnostics、通信path検証にactive diagnosticsを使い分けます。active diagnosticsはdefault disabledなので、実行policyを明示します。
4. node admission/preflightではDCGM diagnosticsとGPU/NVLink/PCIe healthを確認し、failure nodeをschedulerから隔離できる運用へ接続します。
5. InfiniBand/RoCEではlink stateだけでなくbandwidth、latency、retry/error、port/fabric counterをbaseline化します。multi-rail環境ではrail単位で比較します。
6. `nccl-tests`をknown-good topologyで定期実行し、pairwise/group baselineを保存します。異常時はslow pair→片側node交換→rail固定の順でfault domainを狭めます。
7. NCCL log、kernel log、Xid/SXid、DCGM、RDMA/NIC counter、switch telemetry、framework retry/restart eventを同一incident timelineへ結合します。
8. recoveryは原因層ごとに分けます。process/rank failureならframework/job restart、node/GPU/NIC faultならdrain/quarantine、fabric faultならrail/path隔離またはnetwork remediationを選び、原因未確定のままNCCL tuningだけで恒久復旧扱いにしません。
9. 復旧後は同じdiagnosticとbaseline testを再実行し、正常化readbackをincident close条件にします。

## 適用境界
NCCL RAS/Diagnosticsの機能はversion依存です。RASは2.24以降、RAS diagnosticsとactive diagnosticsは2.31以降の機能を含むため、clusterの実NCCL versionを確認してからrunbookへ組み込みます。短命communicatorではRAS diagnosticsが非同期収集のため情報不完全になり得ます。

InfiniBandとRoCEでは確認すべきcounter・tool・fabric設定が異なります。`NCCL_IB_GID_INDEX`等の設定もversion依存で、現行NCCL文書は2.21以降のRoCE GID index動的選択を説明しています。古いrunbookを現行clusterへ機械適用しません。

## counterevidence / limitations
active diagnosticsが成功しても、application traffic時だけ発生するcongestion、scale依存、thermal/power、intermittent grey failure、framework-level deadlockを否定できません。逆にdiagnostic failureも、即座に特定hardware部品の故障を証明するとは限りません。

`nccl-tests`のbaselineは有用ですが、collective、message size、node count、topology、GPU/NIC generation、routing、background trafficが違えば性能期待値も変わります。別clusterの数値を固定thresholdとして流用せず、自環境baselineと同条件比較を優先します。

## OPEN_UNKNOWN
- 実clusterでのNCCL/CUDA/driver/DCGM/NIC firmwareのversion matrix
- 各rail・switch portまでrank/GPU/NICを結ぶinventoryの完全性
- grey failure検知に使うcounterの組織固有threshold
- frameworkごとのrank failure時restart semanticsとcheckpoint loss
- cloud-managed fabricで利用者に公開されないswitch/telemetry範囲
- active diagnosticsの実行costとproduction preflight頻度

## SAFE_WORDING
「NCCL/RDMA障害はNCCL errorだけで根因を決めず、RAS/diagnostics、GPU・NVLink・PCIe、NIC/RDMA、fabric、nccl-tests、framework eventを同一incidentで相関し、fault domainを段階的に狭める。正常時baselineを保存し、復旧後も同条件で再検証する。version依存の診断機能と設定はlive環境で確認する。」

## Source / provenance locators
- NVIDIA NCCL 2.32.3, Troubleshooting: https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting.html
- NVIDIA NCCL 2.32.3, RAS: https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting/ras.html
- NVIDIA NCCL 2.32.3, Diagnostics: https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting/diagnostics.html
- NVIDIA NCCL 2.32.3, Networking Troubleshooting: https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/troubleshooting/networking_troubleshooting.html
- NVIDIA GPU Debug Guidelines, GPU Node Triage: https://docs.nvidia.com/deploy/gpu-debug-guidelines/gpu-node-triage.html
- NVIDIA NCCL Documentation Archives (2.30.7 / 2.31.2 / 2.32.3): https://docs.nvidia.com/deeplearning/nccl/archives/index.html

NEXT: /agent/start.json
STOP: This is a knowledge projection, not an execution order.