トラブルシューティングのために NCCL/gIB ログを収集して理解する

このドキュメントでは、NCCL/gIB ログを収集して解釈し、AI Hypercomputer の安定性とパフォーマンスの問題をトラブルシューティングする方法について説明します。また、次のことを行う方法についても説明します。

NCCL ログを収集します。
NCCL ログエントリの構造を理解する。
NCCL/gIB プラグインが正しく読み込まれていることを確認します。
NCCL と gIB のバージョンが正しいことを確認します。
一般的な NCCL の警告とエラーのトラブルシューティングを行います。

NCCL ログを収集する

NVIDIA Collective Communications Library（NCCL）ログを使用して、NCCL の障害をデバッグできます。安定性やパフォーマンスのデバッグを行う場合は、問題のあるワークロードを実行しながら、すべてのロギングレベルから NCCL ログを収集します。ログエントリをコンソールにダンプしないでください。ログの量が多すぎて、ジョブが続行できなくなる可能性があります。

NCCL ログを収集するには、次の環境変数を設定します。

NCCL_DEBUG=INFO
NCCL_DEBUG_SUBSYS=INIT,ENV,GRAPH,NET,COLL,TUNING
NCCL_DEBUG_FILE=DESIRED_PATH/nccl_logs.VM_NAME.RANK_PROCESS_ID

次のように置き換えます。

DESIRED_PATH: ログファイルを保存するパス

VM_NAME: VM 名

RANK_PROCESS_ID: ランクのプロセス ID

NCCL ログ形式

NCCL ログは次のようになります。

# A sample log entry from NCCL core.
a3ultra-vm-0:606:642 [6] NCCL INFO Using network gIB

# A sample log entry from the gIB network plugin.
a3ultra-vm-0:606:642 [6] NCCL INFO NET/gIB : Initializing gIB v1.0.2

NCCL ログには、ソースに関係なく、次のような接頭辞が付いています。

<VM name>:<pid>:<tid> [<GPU device ID>] <log level> <log content>

NCCL/gIB プラグインが正しく読み込まれていることを確認する

NCCL/gIB は、Google が開発した複数のプラグインで構成されています。プラグインの読み込みに失敗すると、パフォーマンスが低下し、場合によっては致命的なエラーが発生することがあります。

ネットワークプラグイン（libnccl-net.so）

gIB ネットワークプラグインが正しく読み込まれると、次のような NCCL ログエントリが表示されます。

... NCCL INFO Using network gIB

次のいずれかに類似したログエントリが表示された場合は、共有オブジェクトを読み込めないセクションの手順に沿って問題を解決してください。

# Cannot find the gIB network plugin.
... NCCL INFO NET/Plugin: Could not find: libnccl-net.so. Using internal network plugin.

# Using the built-in TCP plugin.
... NCCL INFO Using network Socket

# Using the built-in IB plugin.
... NCCL INFO Using network IB

チューナープラグイン（libnccl-tuner.so）

gIB チューナープラグインが正しく読み込まれると、次のような NCCL ログエントリが表示されます。

NCCL INFO TUNER/Plugin: Failed to find ncclTunerPlugin_v3 symbol.
NCCL INFO TUNER/Plugin: Using tuner plugin A3xTunerPlugin_v2

次のようなログエントリが表示された場合は、共有オブジェクトを読み込めないセクションの手順に沿って問題を解決します。

NCCL INFO TUNER/Plugin: Failed to find ncclTunerPlugin_v2 symbol, using internal tuner instead.

CollNet プラグイン

これらのログエントリは障害を示していますが、想定されたものであり、懸念する必要はありません。

NCCL INFO NET/Plugin: Failed to find ncclCollNetPlugin_v8 symbol.
NCCL INFO NET/Plugin: Failed to find ncclCollNetPlugin symbol (>= v5). ncclCollNetPlugin symbols v4 and lower are not supported.

NCCL と gIB のバージョンを確認する

最新の機能、最高のパフォーマンス、最高の安定性を確保するため、gIB インストーラにバンドルされている NCCL を使用することをおすすめします。ただし、テストにカスタム NCCL バージョン（選択した ML フレームワークにバンドルされている NCCL バージョンなど）を使用することもできます。

使用されている NCCL と gIB のバージョンを確認するには、次の NCCL ログエントリを探します。

# NCCL version.
... NCCL INFO NCCL version 2.23.4+cuda12.2

# gIB version.
... NCCL INFO NET/gIB : Initializing gIB v1.0.2

NCCL/gIB 環境変数を確認する

NCCL のパフォーマンスを向上させるために、推奨される NCCL 環境変数を設定するために使用できるスクリプトを提供します。ワークロードを実行する前に、ワークロードと同じ環境でスクリプトをソースとして指定します。NCCL/gIB インストーラ内では、スクリプトは /usr/local/gib/set_nccl_env.sh にあります。このスクリプトを使用せず、その結果 NCCL 環境変数が正しく設定されていない場合、gIB NCCL 構成チェッカーがワークロードを終了したり、NCCL がクラッシュしたり、NCCL のパフォーマンスが低下したりする可能性があります。

NCCL/gIB 環境変数が正しく適用されていることを確認するには、次のような NCCL ログエントリを探します。

# Explicitly set values.
... NCCL INFO NCCL_P2P_PCI_CHUNKSIZE set by environment to 131072.

# Using default values because the set value is invalid.
... NCCL INFO Invalid value INVALID_VALUE for NCCL_P2P_PCI_CHUNKSIZE, using default 131072.

次の値を、推奨される NCCL 環境変数と比較します。

GKE ワークロードマニフェストを確認する

GKE では、Kubernetes ワークロードマニフェストに、NCCL/gIB をスムーズに利用するために必要な設定がいくつかあります。

マニフェストは、VM の /home/kubernetes/bin/gib からワークロードコンテナの /usr/local/gib に NCCL/gIB バイナリをマウントする必要があります。VM の /home/kubernetes/bin/nvidia は、ワークロードコンテナの /usr/local/nvidia に自動的にマウントされます。
ワークロードコンテナは LD_LIBRARY_PATH を /usr/local/gib/lib64:/usr/local/nvidia/lib64 に設定する必要があります。
クラスタとノードプールで GKE マルチネットワーキングが設定されている必要があります。また、ワークロードマニフェストにマルチネットワーキングアノテーションを含めて、hostNetwork: true の設定を回避する必要があります。

GKE の実際の Kubernetes ワークロードマニフェストは次のようになります。

...
metadata:
  annotations:
    networking.gke.io/default-interface: 'eth0'
    networking.gke.io/interfaces: |
      [
        {"interfaceName":"eth0","network":"default"},
        {"interfaceName":"eth1","network":"gvnic-1"},
        {"interfaceName":"gpu0rdma0","network":"rdma-0"},
        {"interfaceName":"gpu1rdma0","network":"rdma-1"},
        {"interfaceName":"gpu2rdma0","network":"rdma-2"},
        {"interfaceName":"gpu3rdma0","network":"rdma-3"},
        {"interfaceName":"gpu4rdma0","network":"rdma-4"},
        {"interfaceName":"gpu5rdma0","network":"rdma-5"},
        {"interfaceName":"gpu6rdma0","network":"rdma-6"},
        {"interfaceName":"gpu7rdma0","network":"rdma-7"}
      ]
spec:
  volumes:
    - name: gib
      hostPath:
        path: /home/kubernetes/bin/gib
...
containers:
  - name: my-container
    volumeMounts:
      - name: gib
     mountPath: /usr/local/gib
    env:
      - name: LD_LIBRARY_PATH
        value: /usr/local/gib/lib64:/usr/local/nvidia/lib64
    resources:
      limits:
        nvidia.com/gpu: 8

GID テーブルを確認する

RoCE では、グローバル識別子（GID）テーブルを使用して RDMA トラフィックを一意にアドレス指定します。GID テーブルが破損している場合、RDMA トラフィックは通過できません。

GID テーブルを表示するスクリプト show_gids.sh を提供しています。インストーラでは、/usr/local/gib/scripts にあります。インストーラをそのまま使用した場合、VM の /var/lib/gib/scripts にインストールされます。

VM でスクリプトを実行すると、次のような出力が表示されます。

DEV     PORT  INDEX  GID                                      IPv4         VER  DEV
---     ----  -----  ---                                      ----         ---  ---
mlx5_0  1     0      fe80:0000:0000:0000:689c:b8ff:fedf:3b01               v1   gp0rdma0
mlx5_0  1     1      fe80:0000:0000:0000:689c:b8ff:fedf:3b01               v2   gp0rdma0
mlx5_0  1     2      0000:0000:0000:0000:0000:ffff:c0a8:0202  192.168.2.2  v1   gp0rdma0
mlx5_0  1     3      0000:0000:0000:0000:0000:ffff:c0a8:0202  192.168.2.2  v2   gp0rdma0
...

出力を確認し、次のことを確認します。

GID テーブルに適切な数のエントリがある。
- A3 Ultra または A4 の場合、32 個のエントリ（CX-7 あたり 4 個のエントリ）。
- A3 Mega の場合、32 個のエントリ（CX-7 あたり 4 個のエントリ）。
- A3 High（8 個の GPU）の場合、16 個のエントリ（CX-7 あたり 4 個のエントリ）。
- A4X の場合、CX-7 あたり 4 エントリで 16 エントリ。
各 CX-7 の GID エントリには、インデックス 0、1、2、3 があります。
各 CX-7 のインデックス 2 と 3 には IPv4 アドレスがあり、その IP アドレスはデバイスの IPv4（ip a など）と一致します。

これらのいずれかが false の場合、GID テーブルは破損しています。VM を再起動するか、ゲスト OS でネットワークマネージャーを再起動することを検討してください。

NCCL の警告

NCCL ログには複数のレベルがあり、NCCL 警告（NCCL WARN）が最も重大です。NCCL 警告は通常、失敗を示します。これは致命的な場合もあれば、そうでない場合もあります。NCCL には、ワークロードを自動的に停止するログレベルはありません。

共有オブジェクトを読み込めない

設定が原因で共有オブジェクトを読み込めない場合、次のエラーが発生します。

error while loading shared libraries: libnccl.so.2: cannot open shared object file: No such file or directory

問題を解決するには:

共有オブジェクトが環境にインストールされていることを確認します。
共有オブジェクトのディレクトリが $LD_LIBRARY_PATH 環境変数に含まれていることを確認します。

共有オブジェクトからセグメントをマッピングできませんでした

共有オブジェクトのディレクトリが実行可能でない場合、次のエラーが発生します。

error while loading shared libraries: libnccl.so.2: failed to map segment from shared object: Operation not permitted

この問題を解決するには、次のコマンドを実行します（次の例では、gIB バイナリが VM の /var/lib/gib にインストールされていることを前提としています）。

sudo mount --bind /var/lib/gib /var/lib/gib
sudo mount -o remount,exec /var/lib/gib

ゲスト構成チェッカーが構成ファイルを見つけられない

ゲスト Config Checker が使用する構成ファイルを見つけられない場合、次のようなログエントリが表示されます。

... NCCL WARN cannot find config file at default paths; you must specify NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE

... NCCL WARN NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE does not exist: /path/to/guest_config.txtpb

この問題を解決するには、guest_config.txtpb の場所を指すように環境変数 NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE を設定します。NCCL/gIB インストーラの構成ファイルのデフォルトの場所は /usr/local/gib/configs/guest_config.txtpb です。

ゲスト構成チェッカーは、ベストプラクティスと適切な構成を確保するのに役立つため、無効にすることはおすすめしません。ただし、必要に応じて、環境変数 NCCL_SHIMNET_SHIM_LAYERS を UNUSED に設定して、ゲスト構成チェッカーを無効にできます。

ゲスト構成チェッカーが設定を適用または推奨した

NCCL/gIB 環境変数が推奨どおりに設定されていない場合、次のエラーが発生します。

# The guest Config Checker enforcing an environment variable.
# This ends the workload.
... NCCL WARN NCCL/NET (shim) mismatch enforced: NCCL_P2P_NVL_CHUNKSIZE=524288 (expected 262144)

# The guest Config Checker recommending an environment variable.
# This does not end the workload.
... NCCL WARN NCCL/NET (shim) mismatch recommended: NCCL_MAX_P2P_NCHANNELS=8 (expected unset)

問題を解決するには:

ゲスト構成チェッカーのログのガイダンスに従います。
NCCL/gIB 環境変数を確認します。

チューナーが構成ファイルを見つけられない

チューナープラグインが使用する構成ファイルを見つけられないと、次のエラーが発生します。

... NCCL WARN No NCCL_TUNER_CONFIG_PATH provided. Please populate NCCL_TUNER_CONFIG_PATH to use config-based tuner plugin.

問題を解決するには:

環境変数 NCCL_TUNER_CONFIG_PATH を設定して、tuner_config.txtpb の場所を指すようにします。NCCL/gIB インストーラの構成ファイルのデフォルトの場所は /usr/local/gib/configs/guest_config.txtpb です。
NCCL/gIB 環境変数を確認します。

glibc のバージョンが不十分

このエラーは、ディストリビューションローカルの glibc バージョンが古すぎる場合に発生します。これは、ローカル環境の Linux ディストリビューションが古すぎることが原因である可能性が最も高いです。NCCL/gIB バイナリには glibc バージョン 2.29 が必要です。

/usr/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by /usr/local/gib/lib64/libnccl.so.2)

この問題を解決するには、イメージディストリビューション（Ubuntu 20.04 以降、RockyLinux 9 以降など）をアップグレードします。

メッセージが切り捨てられた

ランク間で異なる NCCL バージョンを使用している場合、次のエラーが発生します。

... NCCL WARN Message truncated : received ### bytes instead of ###

この問題を解決するには、NCCL と gIB のバージョンを確認します。GKE を使用している場合は、NCCL/gIB インストーラ DaemonSet を確認するか、再インストールします（A3U と A4 の手順または A4X の手順をご覧ください）。

libibverbs がプロバイダ構成を読み込めない

gIB バイナリを含むディレクトリを /usr/local/gib にマウントしていない場合、次のエラーが発生します。これにより、ワークロードが失敗することはありません。ただし、NCCL は TCP の使用にフォールバックするため、パフォーマンスが低下する可能性があります。

libibverbs: Warning: couldn't open config directory '/usr/local/gib/rdma-core/build/etc/libibverbs.d'.

この問題を解決するには、GKE を使用している場合は、ワークロードマニフェストを確認します。

ibv_modify_qp エラー

gIB ネットワークプラグインが実際のネットワークトランザクション用に QP を準備する際に、さまざまなエラーが発生する可能性があります。

引数が無効です（errno 22）

次のエラーは、次のいずれかの理由で発生します。

QP のもう一方の端には、破損した GID テーブルがあります。
NCCL/gIB 環境変数（特に NCCL_IB_GID_INDEX、NCCL_IB_TC、NCCL_IB_FIFO_TC）が正しく構成されていない。

... NCCL WARN Call to ibv_modify_qp failed with error Invalid argument errno 22

問題を解決するには:

署名 No data available error 61 の他の ibv_modify_qp エラーを探し、エラー 61 の軽減手順に沿って対応します。
NCCL/gIB 環境変数を確認します。

データがありません（errno 61）

次のエラーは、次のいずれかの理由で発生します。

この VM の GID テーブルが破損しています。
NCCL/gIB 環境変数（特に NCCL_IB_GID_INDEX、NCCL_IB_TC、NCCL_IB_FIFO_TC）が正しく構成されていない。

... NCCL WARN Call to ibv_modify_qp failed with error No data available errno 61

この問題を解決するには、まず原因を確認します。

GID の表を確認します。
NCCL/gIB 環境変数を確認します。

GID テーブルが破損している場合は、次の緩和策を試してください。

（短期的な解決策）問題のあるインターフェースの IP アドレスが更新されるまで、VM でネットワークマネージャー（networkd など）を再起動します。
1. VM で sudo systemctl restart systemd-networkd を使用して networkd を再起動できます。
2. ip a を使用すると、すべてのインターフェースの IP アドレスを確認できます。
3. GID テーブルが復元されたことを確認します。
長期的な解決策については、Google サポートにお問い合わせください。

接続がタイムアウトしました（errno 110）

次のエラーは、VM 間の基本的な接続に問題がある場合に発生します。

... NCCL WARN Call to ibv_modify_qp failed with error Connection timed out errno 110

この問題を解決するには、Google サポートにお問い合わせください。

QP Got Completion with Error

次のエラーは、次のいずれかの理由で発生します。

基盤となる RDMA 接続の問題（リンクフラップなど）。
NCCL/gIB 環境変数（特に NCCL_IB_TIMEOUT と NCCL_IB_RETRY_CNT）が正しく構成されていません。

... NCCL WARN NET/gIB : Got completion from peer 192.168.0.9<55224> with status=12 opcode=0 len=0 vendor err 129 (Recv) localGid ::ffff:192.168.3.6 remoteGids::ffff:192.168.3.9

この問題を解決するには、Google サポートにお問い合わせください。

トラブルシューティングのために NCCL/gIB ログを収集して理解する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

NCCL ログを収集する

NCCL ログ形式

NCCL/gIB プラグインが正しく読み込まれていることを確認する

ネットワーク プラグイン（libnccl-net.so）

チューナー プラグイン（libnccl-tuner.so）

CollNet プラグイン

NCCL と gIB のバージョンを確認する

NCCL/gIB 環境変数を確認する

GKE ワークロード マニフェストを確認する

GID テーブルを確認する

NCCL の警告

共有オブジェクトを読み込めない

共有オブジェクトからセグメントをマッピングできませんでした

ゲスト構成チェッカーが構成ファイルを見つけられない

ゲスト構成チェッカーが設定を適用または推奨した

チューナーが構成ファイルを見つけられない

glibc のバージョンが不十分

メッセージが切り捨てられた

libibverbs がプロバイダ構成を読み込めない

ibv_modify_qp エラー

引数が無効です（errno 22）

データがありません（errno 61）

接続がタイムアウトしました（errno 110）

QP Got Completion with Error

トラブルシューティングのために NCCL/gIB ログを収集して理解する

ネットワークプラグイン（libnccl-net.so）

チューナープラグイン（libnccl-tuner.so）

GKE ワークロードマニフェストを確認する