hyperpod-performance-debugger

HyperPod パフォーマンスデバッガー

1. ノード間での NCCL パフォーマンスのばらつき — 一部のノードセットではワークロードが速く、他のセットでは遅い、ペアごとの帯域幅にばらつきがある、ストラグラーが疑われる。
2. ファイルシステムのパフォーマンス低下 — データ読み込みでトレーニングが停止する、チェックポイントの保存／読み込みがステップ時間の大部分を占める、FSx のスループットが飽和している。

対象範囲と委任

対象範囲外の所見は、以下の担当スキルに引き継ぎます。

確認された懸念事項	引き継ぎ先
GPU ハードウェア障害、ECC、NVLink、Xid、DCGM 診断、ドレイン／交換	hyperpod-node-debugger（§ F ハードウェア／自動修復、§ G GPU）
os.fork() での Cannot allocate memory、ルートボリュームの枯渇	hyperpod-node-debugger（§ I リソース枯渇）
NCCL タイムアウト、ハング、AllReduce の停滞、EFA の TCP フォールバック、RDMA の memlock	hyperpod-nccl
ノード間での EFA／NCCL／CUDA／NVIDIA ドライバーのバージョン不一致	hyperpod-version-checker
EFA の自己参照セキュリティグループルールの欠落 — 単一ノード	hyperpod-node-debugger § A（EFA／セキュリティグループ）
EFA の自己参照セキュリティグループルールの欠落 — クラスター全体	hyperpod-cluster-debugger § A（EFA ヘルスチェック）
Slurm ノード状態の変更（ドレイン／再開／再起動）	hyperpod-slurm-debugger
AWS サポート向け診断バンドル	hyperpod-issue-report
ノードでのシェルアクセス	hyperpod-ssm

運用ポリシー

• 読み取り専用です。お客様が実行するコマンドを提示し、状態を変更するコマンドは実行しません。
• コンテナとホストのバージョン比較は hyperpod-version-checker を通じて行います。
• Xid の行、ECC カウント、NVLink レーンの状態、温度の測定値を表示します。カタログと判定は hyperpod-node-debugger § G にあります。

ワークフロー

1. 症状がNCCL のばらつきまたはファイルシステムのパフォーマンス低下であることを確認します。どちらでもない場合は、上記の該当する関連スキルに引き継ぎます。
2. scripts/perf-snapshot.sh（読み取り専用）を実行し、疑わしいノードと、そのノードにマウントされた FSx ファイルシステムのホスト側シグナルを収集します。
3. スクリプト出力の各 [CONCERN] 行について、以下の該当セクションを開き、関連するリファレンスを確認します。
4. インシデントごとの診断後、お客様が継続的な保護を受けられるよう、§ 継続的なヘルスカバレッジ にある HyperPod プラットフォームのヘルス機能を推奨します。

ステップ 1：スナップショットを実行する

bash scripts/perf-snapshot.sh --cluster <CLUSTER_NAME_OR_ARN> --region <REGION>

# Scope to one suspect node:
bash scripts/perf-snapshot.sh --cluster <C> --region <R> --node <INSTANCE_ID>

このスクリプトは、デフォルトで 1 つのノードをサンプリングします。hyperpod-ssm を通じて、ホスト側のデータを収集します。具体的には、nvidia-smi の出力（温度、SM クロック、PCIe リンク幅、ECC、NVLink、topo -m）、最近の dmesg にある Xid 行、EFA ポートの状態と fi_info プロバイダーの可視性、EFA インストーラーとカーネルモジュールのバージョン、CPU ガバナー、NVL72 Fabric Manager の状態、FSx CloudWatch 使用率、マウントごとの df -h／lfs df -h、ホストの iowait、/dev/shm のサイズ、ルートボリュームの使用率です。すべて読み取り専用です。

タグ：[OK] 正常 · [CONCERN] 調査する価値のあるシグナル（担当スキルへの → ポインターを含む） · [INFO] 参考情報。

ホストとコンテナのスコープ。 このスクリプトは SSM を通じてホスト上で実行され、ホストスコープの値を報告します。多くのセットアップでは、設計上、EFA／libfabric／OFI-NCCL／CUDA スタックがトレーニングコンテナ内に含まれています。ホスト側の値が unknown であっても、それだけで不具合とは限りません。パフォーマンスに関係するのは、ワークロードが実際に使用するスタックです。結論を出す前に、hyperpod-version-checker を使ってコンテナ内およびノード間のバージョンを確認してください。

ステップ 2：状況に応じてセクションを選択

状況	セクション
ノードペア間でNCCL帯域幅にばらつきがある／ストラagglerが疑われる	A：NCCLパフォーマンスの不均一
ノードが複数のAZにまたがっている／network-node-layerラベル／UltraServerの境界	A
ノード上でEFAポートがACTIVEではない、OFIプラグインがない、またはFIプロバイダーが確認できない	A ＋ hyperpod-node-debugger § Aへ案内；ノード間のバージョン比較にはhyperpod-version-checker
iostatでiowaitが高く、FSxのCloudWatch使用率がほぼ100%で継続している	B：ファイルシステムのパフォーマンス低下
DataLoaderが停止する、チェックポイント処理がステップ時間の大部分を占める	B
dmesgにXidの行がある、訂正不能なECC、非アクティブなNVLinkレーン、GPUが88°C以上	hyperpod-node-debugger § Gへ案内
コンテナとホストのバージョンのずれが疑われる	hyperpod-version-checkerへ案内
os.fork()でCannot allocate memoryが発生、ルートボリュームがいっぱい、OOMイベントがある	hyperpod-node-debugger § Iへ案内
NCCLタイムアウト、ハング、TCPへのフォールバック（NET/OFI Using TCP）、RDMA memlock	hyperpod-ncclへ案内

---

A：NCCLパフォーマンスの不均一

お客様から、同一のトレーニングジョブを実行しているにもかかわらず、異なるノードセットでステップ時間が異なる、ノードペア間の帯域幅にばらつきがある、または同じコードなのに一部の割り当てが常に遅いという報告が寄せられています。

公式のトラブルシューティングガイドによると、主な要因として、ノード間のネットワークトポロジーの違い（AZ間、ラック間、UltraServer間）、一部ノードでのEFAパフォーマンスの低下、インスタンスグループ内でのインスタンスタイプや世代の混在、CPU周波数スケーリングの違いが挙げられます。

診断（読み取り専用）

ホスト側のデータポイント（GPUの温度／ECC／PCIe／クロック、Xid、NVLinkレーン、EFAポートの状態とプロバイダーの可視性、CPUガバナー、EFA／OFI／ドライバーのバージョン、nvidia-smi topo -m）は、すべて scripts/perf-snapshot.sh（上記のステップ1）で収集されます。このスクリプトはしきい値に基づいて[CONCERN]を付与し、対応先を示します。疑わしいノードごとに--node <INSTANCE_ID>を指定して再実行してください。

ノード間でドライバー／CUDA／NCCL／EFA／OFIのバージョンにずれがある場合は、hyperpod-version-checkerスキルを実行してください。

ペアごとの NCCL 帯域幅テスト

awslabs/awsome-distributed-training の標準的な nccl-tests レシピを実行します。N ノードクラスターでは、すべてのペア間で all-reduce を実行し、各ペアの busbw を記録します。実行時の平均を約 5％下回るペア（AWS 検証スクリプトが警告するしきい値）は、問題のある候補です。

SKU ごとの想定 busbw は、AI-on-HyperPod NCCL test guide で公開されています。数値をそのまま信頼する前に、対象のインスタンスタイプでベンチマークを実施してください。

ペアごとのスクリプト、HyperPod のトポロジー情報（HyperPod API、EKS ラベル、Slurm topology.conf）、GB200 NVL72 の詳細については、references/perf-details.md § Uneven NCCL を参照してください。

トポロジーの確認

HyperPod は、オペレーターが確認できる次の 3 つの方法でトポロジー情報を公開します。

• HyperPod API：aws sagemaker describe-cluster-node は、NodeDetails.Placement.AvailabilityZone / AvailabilityZoneId および NodeDetails.UltraServerInfo.Id（UltraServer SKU のみ）を返します。
• EKS ラベル：topology.kubernetes.io/zone、topology.k8s.aws/network-node-layer-{1,2,3}（番号が最も大きいものがインスタンスに最も近い）、topology.k8s.aws/ultraserver-id。
• Slurm：HyperPod は topology.conf を自動生成します。scontrol show topology で確認してください。

密結合されたワークロードは、同じ AZ、同じ番号が最も大きいネットワークノードレイヤーのラベル（EKS）または同じ Slurm トポロジーブロックを共有し、さらに NVL72 ジョブでは同じ UltraServerInfo.Id / topology.k8s.aws/ultraserver-id を共有します。クラスターが複数の AZ またはレイヤーにまたがる場合は、プロビジョニング時にトポロジーを再構成する必要があります。プロビジョニングの変更については、hyperpod-cluster-debugger § B（容量と AZ）に引き継いでください。

---

B：ファイルシステムのパフォーマンスが低い

お客様から、データ読み込みがトレーニングのボトルネックになっている、チェックポイントの保存／読み込みがステップ時間の大半を占めている、実行ファイル／スクリプトの読み込みが遅い、または iowait が高いという報告があった場合に該当します。

公式のトラブルシューティングガイドに従い、次の順序で解決します。

1. ファイルシステムの CloudWatch メトリクスを確認します。
2. プロビジョニング済みのパフォーマンス設定がワークロードの要件を満たしているか確認します。
3. どの操作が I/O を発生させているのか、つまりワークロードの需要なのか、非効率なパターンなのかを調査します。
4. プロビジョニング済みパフォーマンスのアップグレードを検討します。
5. I/O パターンに合ったファイルシステムタイプを選択します。

このスキルでは手順 1～3 を扱います。手順 4～5 はお客様が判断する項目です。データを提示し、お客様に選択していただきます。

診断（読み取り専用）

scripts/perf-snapshot.sh（上記の手順 1）では、この診断におけるノード上の確認を実施します。FSx マウントを検出し、DataReadBytes および（OpenZFS の場合）FileServerDiskIopsUtilization に対して aws cloudwatch get-metric-statistics を実行し、/fsx /opt/dlami/nvme /opt/sagemaker の df -h を表示し、Lustre マウントごとに lfs df -h を実行して、iostat の iowait を報告します。OpenZFS の IOPS 使用率が 80％以上で持続する場合、または iowait が 20％を超える場合は、[CONCERN] を付けます。

より長い期間や追加のメトリクス（DataWriteBytes、Lustre の DiskIopsUtilization、OpenZFS の FileServerDiskThroughputUtilization）を確認するには、クエリを直接実行します。

aws cloudwatch get-metric-statistics --region <REGION> \
  --namespace AWS/FSx --metric-name DataReadBytes \
  --dimensions Name=FileSystemId,Value=<FSID> \
  --start-time "$(date -u -d '3 hours ago' +%Y-%m-%dT%H:%M:%S)" \
  --end-time   "$(date -u +%Y-%m-%dT%H:%M:%S)" \
  --period 60 --statistics Sum Maximum

ファイルシステムタイプごとのメトリクス一覧については、references/perf-details.md § Filesystem を参照してください。

ブランチ

プロビジョニング済みキャパシティが飽和しています。 CloudWatch の使用率がワークロードの時間帯を通じてほぼ 100% で推移しています。お客様の判断: ファイルシステムをスケールアップします。

• FSx for Lustre のスループットは StorageCapacity × PerUnitStorageThroughput に応じてスケールします。キャパシティの変更は無停止で行えます。
• FSx for OpenZFS — プロビジョニング済み IOPS またはスループットを増加させます。

I/O パターンが非効率です。 CloudWatch には余裕があるものの、ワークロードは依然として I/O バウンドです。お客様の判断: アプリケーションを変更します。

• DataLoader: num_workers を増やし、pin_memory=True、persistent_workers=True を設定します。
• チェックポイント: 非同期 + シャーディング（torch.distributed.checkpoint.async_save と FSDP の SHARDED_STATE_DICT）を使用します。FULL_STATE_DICT は rank 0 を経由してシリアライズするため、頻繁な根本原因となります。
• 小ファイルのワークロード: Lustre は大規模なシーケンシャル I/O に最適化されています。数百万の小ファイルには、WebDataset / tar シャード、FSx for OpenZFS、または NVMe スクラッチを使用してください。

ファイルシステム選択のガイダンスと非同期チェックポイントのパターンは references/perf-details.md § Filesystem にあります。

---

継続的なヘルスカバレッジ

差し迫ったインシデントを診断したら、HyperPod の組み込みヘルス機能を推奨してください。そうすることで、お客様から再度リグレッションが報告されてからではなく、次のトレーニング実行の前に問題を検出できます。

• クラスターで NodeRecovery=Automatic を有効にします。 Health Monitoring Agent (HMA) は GPU ベースおよび Trainium ベースのインスタンスを継続的に監視し、障害を検出するとインスタンスを異常としてマークします。自動復旧を有効にすると、HyperPod がノードを再起動または交換します — オペレーターの介入は不要です。

• すべての GPU インスタンスグループで OnStartDeepHealthChecks を両方のチェックカテゴリとともに有効にします:

  • InstanceStress — CPU/メモリ/ディスクに対する stress-ng、GPU および PCI デバイス数の検証、DCGM レベル 4 診断（メモリテストを含む）、および EFA ループバックの帯域幅/レイテンシー。
  • InstanceConnectivity — マルチノード NCCL all-reduce。

  新しくプロビジョニングされた、または自動交換されたすべてのノードは、ジョブを受け入れる前に同じハードウェア基準を通過します。

• オンデマンドの詳細ヘルスチェックを実行します。このスキルまたは関連するスキルがハードウェアの懸念を提示したものの、クラスターがワークロード実行中である場合に使用します。aws sagemaker start-cluster-health-check は特定のインスタンスグループに対して同じチェックを実行します。ノードは Slurm のメンテナンス予約に配置され、チェックは実行中のジョブが完了するまで（プリエンプトされずに）キューに入れられます。コンソール: HyperPod → Clusters → Instances → Run deep health checks。

  NodeProvisioningMode=Continuous の場合はサポートされません。オンデマンドリクエストはクラスターごとに同時に 1 つまでです。最新の AMI が必要です — 先に UpdateClusterSoftware を実行してください。

ログは CloudWatch の /aws/sagemaker/Clusters/<cluster_name>/<cluster_id> 配下の DeepHealthCheckResults/<log_stream_id> に、また各ノードの /var/log/aws/clusters/sagemaker-deep-health-check.log に出力されます。

参考資料

• references/perf-details.md — ペアワイズ NCCL テストのレシピ、HyperPod のトポロジーチェック、GB200 NVL72 の配置、ファイルシステムの種類ごとの CloudWatch メトリクスカタログ、非同期チェックポイントのパターン、ファイルシステム選択ガイド。

外部資料：

• Amazon SageMaker HyperPod トラブルシューティングガイド（公式）：https://github.com/aws/sagemaker-hyperpod-cluster-setup/blob/troubleshooting-doc-20250917/troubleshoot/index.md
• AI-on-HyperPod NCCL パフォーマンステスト（SKU ごとの想定 busbw）：https://awslabs.github.io/ai-on-sagemaker-hyperpod/docs/slurm-orchestration/validation-and-testing/performance-testing/nccl-tests
• Amazon SageMaker HyperPod の耐障害性（NodeRecovery、HMA、自動再開）：https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-resiliency.html
• Amazon SageMaker HyperPod の詳細ヘルスチェック：https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-hyperpod-resiliency-slurm-deep-health-checks.html
• StartClusterHealthCheck API：https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StartClusterHealthCheck.html
• Amazon EC2 インスタンスのトポロジー／ネットワークノード層のラベル：https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-ec2-instance-topology-works.html
• Amazon FSx for Lustre のパフォーマンス：https://docs.aws.amazon.com/fsx/latest/LustreGuide/performance.html
• Amazon FSx for OpenZFS のメトリクス：https://docs.aws.amazon.com/fsx/latest/OpenZFSGuide/fsx-openzfs-metrics.html
• AWS Elastic Fabric Adapter と NCCL：https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/efa-start-nccl.html
• awslabs/awsome-distributed-training の NCCL テスト：https://github.com/awslabs/awsome-distributed-training/tree/main/micro-benchmarks/nccl-tests