Raccogliere e comprendere i log NCCL/gIB

GPU in cluster

Questo documento descrive come raccogliere e interpretare i log NCCL/gIB per risolvere i problemi di stabilità e prestazioni su AI Hypercomputer, incluse indicazioni su come eseguire le seguenti operazioni:

• Raccogliere i log NCCL.
• Comprendere la struttura delle voci di log NCCL.
• Verificare che i plug-in NCCL/gIB siano caricati correttamente.
• Verificare che le versioni di NCCL e gIB siano corrette.
• Risolvere i problemi relativi agli avvisi e agli errori NCCL comuni.

Raccogliere i log NCCL

Puoi utilizzare i log della NVIDIA Collective Communications Library (NCCL) per eseguire il debug degli errori NCCL. Per il debug di stabilità o prestazioni, raccogli i log NCCL da tutti i livelli di logging mentre esegui il workload problematico. Evita di scaricare le voci di log nella console, perché l'enorme volume dei log potrebbe impedire la continuazione del job.

Per raccogliere i log NCCL, imposta le seguenti variabili di ambiente:

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

Sostituisci quanto segue:

DESIRED_PATH: il percorso in cui vuoi archiviare i file di log

VM_NAME: il nome della VM

RANK_PROCESS_ID: l'ID processo del rank

Formato dei log NCCL

I log NCCL sono simili ai seguenti:

# 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

Indipendentemente dalla loro origine, i log NCCL hanno un prefisso simile al seguente:

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

Verificare che i plug-in NCCL/gIB siano caricati correttamente

NCCL/gIB è composto da più plug-in sviluppati da Google. Se non riesci a caricare uno dei plug-in, le prestazioni potrebbero essere scarse e, in alcuni casi, potrebbero verificarsi errori irreversibili.

Ti consigliamo di utilizzare NCCL in bundle con il programma di installazione gIB per garantire le funzionalità più recenti, le migliori prestazioni e la massima stabilità. Se scegli di utilizzare una versione NCCL personalizzata per i test, ad esempio una versione NCCL in bundle con il framework di machine learning che preferisci, devi anche installare il pacchetto nccl-gib-plugins.

Plug-in di rete (libnccl-net.so)

Se il plug-in di rete gIB viene caricato correttamente, dovresti visualizzare voci di log NCCL simili alle seguenti:

... NCCL INFO Using network gIB

Se vedi voci di log simili a una delle seguenti, utilizza i passaggi nella sezione Impossibile caricare un oggetto condiviso per risolvere il problema.

# 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

Plug-in del sintonizzatore (libnccl-tuner.so)

Se il plug-in del sintonizzatore gIB viene caricato correttamente, dovresti visualizzare voci di log NCCL simili alle seguenti:

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

Se vedi una voce di log simile alla seguente, utilizza i passaggi nella sezione Impossibile caricare un oggetto condiviso per risolvere il problema.

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

Plug-in CollNet

Sebbene queste voci di log indichino un errore, sono previste e non sono motivo di preoccupazione:

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.

Controllare la versione di NCCL e gIB

Ti consigliamo di utilizzare NCCL in bundle con il programma di installazione gIB per garantire le funzionalità più recenti, le migliori prestazioni e la massima stabilità. Tuttavia, puoi scegliere di utilizzare una versione NCCL personalizzata per i test, ad esempio una versione NCCL in bundle con il framework di machine learning che preferisci. In questo caso, installa il pacchetto nccl-gib-plugins.

Per controllare la versione di NCCL e gIB utilizzata, cerca le seguenti voci di log NCCL:

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

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

Per verificare di utilizzare le versioni consigliate, confronta le versioni di NCCL e gIB registrate con le versioni in bundle nel pacchetto nccl-gib più recente. Ti consigliamo di mantenere aggiornato nccl-gib su tutti i nodi. Consulta Installare NCCL/gIB.

Verificare le variabili di ambiente NCCL/gIB

Per ottenere buone prestazioni NCCL, forniamo uno script che puoi utilizzare per impostare le variabili di ambiente NCCL consigliate. Prima di eseguire il workload, esegui lo script nello stesso ambiente del workload. All'interno del programma di installazione NCCL/gIB, lo script si trova in /usr/local/gib/set_nccl_env.sh. Se non utilizzi questo script e, di conseguenza, le variabili di ambiente NCCL sono impostate in modo errato, è possibile che il controllo della configurazione NCCL gIB termini il workload, che NCCL si arresti in modo anomalo o che le prestazioni NCCL siano scarse.

Per verificare che le variabili di ambiente NCCL/gIB siano applicate correttamente, cerca le voci di log NCCL simili alle seguenti:

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

Confronta i seguenti valori con le variabili di ambiente NCCL consigliate.

Controllare il manifest del workload GKE

Su GKE, il manifest del workload Kubernetes ha diverse configurazioni obbligatorie per utilizzare NCCL/gIB senza problemi:

• Il manifest deve montare i file binari NCCL/gIB da /home/kubernetes/bin/gib sulla VM a /usr/local/gib nel container del workload. Tieni presente che /home/kubernetes/bin/nvidia sulla VM viene montato automaticamente su /usr/local/nvidia nel container del workload.
• Il container del workload deve impostare LD_LIBRARY_PATH su /usr/local/gib/lib64:/usr/local/nvidia/lib64.
• Il cluster e i node pool devono avere configurato il multi-networking GKE e il manifest del workload deve includere le annotazioni multi-networking per evitare di dover impostare hostNetwork: true.

Un manifest del workload Kubernetes effettivo su GKE è simile al seguente:

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

Controllare la tabella GID

In RoCE, la tabella degli identificatori globali (GID) viene utilizzata per indirizzare in modo univoco il traffico RDMA. Se la tabella GID è danneggiata, non può passare alcun traffico RDMA.

Forniamo uno script show_gids.sh per mostrare la tabella GID. Nel programma di installazione, si trova in /usr/local/gib/scripts. Se hai utilizzato il nostro programma di installazione senza modifiche, viene installato in /var/lib/gib/scripts sulla VM.

Quando esegui lo script nella VM, dovresti vedere un output simile al seguente:

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

Esamina l'output e verifica quanto segue:

• La tabella GID ha il numero corretto di voci:
  • Per A3 Ultra o A4, 32 voci con 4 voci per CX-7.
  • Per A3 Mega, 32 voci con 4 voci per CX-7.
  • Per A3 High (8 GPU), 16 voci con 4 voci per CX-7.
  • Per A4X, 16 voci con 4 voci per CX-7.
• Le voci GID di ogni CX-7 hanno indici 0, 1, 2 e 3.
• Per ogni CX-7, gli indici 2 e 3 hanno un indirizzo IPv4 e questo indirizzo IP corrisponde all'indirizzo IPv4 del dispositivo (ad esempio da ip a).

Se uno di questi elementi è falso, la tabella GID è danneggiata. Valuta la possibilità di riavviare la VM o il gestore di rete nel sistema operativo guest.

Avvisi NCCL

I log NCCL hanno diversi livelli, con gli avvisi NCCL (NCCL WARN) che sono i più gravi. Gli avvisi NCCL in genere indicano errori, che possono essere irreversibili o meno. NCCL non ha un livello di log che arresta automaticamente il workload.

Impossibile caricare un oggetto condiviso

Il seguente errore si verifica quando non è possibile caricare un oggetto condiviso a causa della configurazione.

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

Per risolvere il problema:

1. Assicurati che l'oggetto condiviso sia installato nel tuo ambiente.
2. Assicurati che la directory dell'oggetto condiviso si trovi nella variabile di ambiente $LD_LIBRARY_PATH.

Impossibile mappare il segmento dall'oggetto condiviso

Il seguente errore si verifica quando la directory dell'oggetto condiviso non è eseguibile.

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

Per risolvere il problema, esegui i seguenti comandi (questi esempi presuppongono che i file binari gIB siano installati in /var/lib/gib sulle VM):

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

Il controllo della configurazione guest non riesce a trovare un file di configurazione

Vengono visualizzate voci di log come queste quando il controllo della configurazione guest non riesce a trovare un file di configurazione da utilizzare.

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

Per risolvere il problema, puoi impostare la variabile di ambiente NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE in modo che punti alla posizione di guest_config.txtpb. La posizione predefinita del file di configurazione del programma di installazione NCCL/gIB è /usr/local/gib/configs/guest_config.txtpb.

Non ti consigliamo di disattivare il controllo della configurazione guest perché ti aiuta a garantire le best practice e la configurazione corretta. Tuttavia, se necessario, puoi disattivare il controllo della configurazione guest impostando la variabile di ambiente NCCL_SHIMNET_SHIM_LAYERS su UNUSED.

Il controllo della configurazione guest ha applicato o consigliato un'impostazione

I seguenti errori si verificano quando le variabili di ambiente NCCL/gIB non sono impostate come consigliato.

# 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)

Per risolvere il problema:

1. Segui le indicazioni dei log del controllo della configurazione guest.
2. Verifica le variabili di ambiente NCCL/gIB.

Il sintonizzatore non riesce a trovare un file di configurazione

Il seguente errore si verifica quando il plug-in del sintonizzatore non riesce a trovare un file di configurazione da utilizzare.

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

Per risolvere il problema:

1. Imposta la variabile di ambiente NCCL_TUNER_CONFIG_PATH in modo che punti alla posizione di tuner_config.txtpb. La posizione predefinita del file di configurazione del programma di installazione NCCL/gIB è /usr/local/gib/configs/guest_config.txtpb.
2. Verifica le variabili di ambiente NCCL/gIB.

Versione di glibc insufficiente

Il seguente errore si verifica quando la versione di glibc locale della distribuzione è troppo vecchia, molto probabilmente perché la distribuzione Linux nel tuo ambiente locale è troppo vecchia. I file binari NCCL/gIB richiedono la versione 2.29 di glibc.

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

Per risolvere il problema, esegui l'upgrade della distribuzione delle immagini (ad esempio Ubuntu 20.04 o versioni successive, RockyLinux 9 o versioni successive).

Messaggio troncato

Il seguente errore si verifica quando utilizzi versioni NCCL miste tra i rank.

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

Per risolvere il problema, controlla la versione di NCCL e gIB. Se utilizzi GKE, controlla o reinstalla il daemonset del programma di installazione NCCL/gIB (vedi le istruzioni per A3U e A4 o le istruzioni per A4X).

libibverbs non riesce a caricare la configurazione del provider

Il seguente errore si verifica quando non hai montato la directory contenente i file binari gIB in /usr/local/gib. Questo non causerà un errore del workload. Tuttavia, NCCL torna a utilizzare TCP e può causare prestazioni scarse.

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

Per risolvere il problema, se utilizzi GKE, controlla il manifest del workload.

Errori ibv_modify_qp

Esistono diversi errori che potresti riscontrare quando il plug-in di rete gIB prepara le QP per le transazioni di rete effettive.

Argomento non valido (errno 22)

Il seguente errore si verifica per uno dei seguenti motivi:

1. L'altra estremità della QP ha una tabella GID danneggiata.
2. Le variabili di ambiente NCCL/gIB non sono configurate correttamente, in particolare NCCL_IB_GID_INDEX, NCCL_IB_TC e NCCL_IB_FIFO_TC.

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

Per risolvere il problema:

1. Cerca altri errori ibv_modify_qp con la firma No data available error 61 e segui le istruzioni di mitigazione per l'errore 61.
2. Verifica le variabili di ambiente NCCL/gIB.

Nessun dato disponibile (errno 61)

Il seguente errore si verifica per uno dei seguenti motivi:

1. Questa VM ha una tabella GID danneggiata.
2. Le variabili di ambiente NCCL/gIB non sono configurate correttamente, in particolare NCCL_IB_GID_INDEX, NCCL_IB_TC e NCCL_IB_FIFO_TC.

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

Per risolvere il problema, controlla innanzitutto la causa:

1. Controlla la tabella GID.
2. Verifica le variabili di ambiente NCCL/gIB.

Se la tabella GID è danneggiata, prova le seguenti mitigazioni:

1. (A breve termine) Riavvia il gestore di rete (ad esempio networkd) sulla VM finché l'indirizzo IP dell'interfaccia problematica non viene aggiornato.
   1. Puoi riavviare networkd sulla VM utilizzando sudo systemctl restart systemd-networkd.
   2. Puoi visualizzare l'indirizzo IP di tutte le interfacce utilizzando ip a.
   3. Verifica che la tabella GID sia stata ripristinata.
2. Contatta l'Assistenza Google per ricevere assistenza con una soluzione a lungo termine.

Timeout della connessione (errno 110)

Il seguente errore si verifica quando si verifica un problema di connettività di base tra le VM.

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

Per risolvere il problema, contatta l'Assistenza Google per ricevere assistenza.

QP ha ricevuto il completamento con errore

Il seguente errore si verifica per uno dei seguenti motivi:

1. Problemi di connessione RDMA sottostanti (link flaps e così via).
2. Le variabili di ambiente NCCL/gIB non sono configurate correttamente, in particolare NCCL_IB_TIMEOUT e 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

Per risolvere il problema, contatta l'Assistenza Google per ricevere assistenza.