Raccogliere e comprendere i log NCCL/gIB

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 ottenere quanto segue:

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

Raccogli 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é il volume dei log potrebbe impedire la prosecuzione 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 di 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>

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

NCCL/gIB è composto da più plug-in sviluppati da Google. Il mancato caricamento di uno dei plug-in può comportare prestazioni scadenti e, in alcuni casi, errori irreversibili.

Ti consigliamo di utilizzare la libreria NCCL integrata nel programma di installazione di gIB per assicurarti di avere 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 integrata nel 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 è 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, segui 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 Tuner (libnccl-tuner.so)

Se il plug-in gIB Tuner è 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, segui 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.

Controlla la versione di NCCL e gIB

Ti consigliamo di utilizzare la libreria NCCL integrata nel programma di installazione di gIB per assicurarti di avere 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 integrata con il framework di machine learning che preferisci. In questo caso, installa il pacchetto nccl-gib-plugins.

Per controllare le versioni di NCCL e gIB utilizzate dal tuo workload, cerca le seguenti voci nei log di 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 che le versioni in esecuzione siano quelle consigliate, confronta le versioni di NCCL e gIB registrate con quelle incluse nell'ultimo pacchetto nccl-gib. Ti consigliamo di mantenere nccl-gib aggiornato su tutti i nodi. Per ulteriori informazioni, consulta Installa NCCL/gIB.

Se hai eseguito l'upgrade manuale di NCCL Core o hai installato nccl-gib-plugins con una libreria NCCL Core personalizzata, verifica che la versione NCCL registrata corrisponda alla versione di destinazione e che il plug-in NET/gIB venga inizializzato:

# Target upgraded NCCL Core version, such as NCCL 2.28 or later.
... NCCL INFO NCCL version 2.28.3+cuda12.8

# gIB network plugin initializing alongside upgraded NCCL Core.
... NCCL INFO NET/gIB : Initializing gIB v1.1.2

Se il log mostra la versione NCCL in bundle precedente anziché la versione di cui hai eseguito l'upgrade, il linker dinamico sta ancora caricando libnccl.so.2 da /usr/local/gib/lib64 o /usr/local/gib/lib. Assicurati di aver rimosso i file libnccl.so* in bundle come descritto in Esegui l'upgrade di NCCL Core su installazioni esistenti.

Verifica 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 il sourcing dello 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 di NCCL siano scarse.

Per verificare che le variabili di ambiente NCCL/gIB siano applicate correttamente, cerca 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.

Controlla 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 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 il networking multiplo GKE configurato e il manifest del workload deve includere le annotazioni di networking multiplo per evitare la necessità di 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

Controlla la tabella GID

In RoCE, la tabella dell'identificatore globale (GID) viene utilizzata per indirizzare in modo univoco il traffico RDMA. Se la tabella GID è danneggiata, non può passare 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, l'installazione è stata eseguita 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 contiene 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 gli indici 0, 1, 2 e 3.
  • Per ogni CX-7, gli indici 2 e 3 hanno un indirizzo IPv4 che corrisponde all'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, tra cui gli avvisi NCCL (NCCL WARN) sono i più gravi. Gli avvisi NCCL di solito indicano errori, che possono essere o meno irreversibili. NCCL non ha un livello di log che interrompe automaticamente il workload.

Impossibile caricare un oggetto condiviso

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

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

Questo errore si verifica anche se rimuovi i file libnccl.so* in bundle durante un upgrade manuale di NCCL Core prima di installare una libreria NCCL Core compatibile o se la directory di installazione della libreria non si trova nel percorso di ricerca del linker dinamico.

Per risolvere il problema, segui questi passaggi:

  1. Verifica che l'oggetto condiviso sia installato nel tuo ambiente.
  2. Verifica che la directory contenente l'oggetto condiviso si trovi nel percorso di ricerca del linker dinamico o 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

Guest Config Checker non riesce a trovare un file di configurazione

Le voci di log come queste vengono visualizzate quando il guest Config Checker 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.

Ti sconsigliamo di disattivare Guest Config Checker perché aiuta a garantire le best practice e la corretta configurazione. Tuttavia, se necessario, puoi disattivare Guest Config Checker impostando la variabile di ambiente NCCL_SHIMNET_SHIM_LAYERS su UNUSED.

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 di Config Checker guest.
  2. Verifica le variabili di ambiente NCCL/gIB.

Tuner non riesce a trovare un file di configurazione

Il seguente errore si verifica quando il plug-in del tuner 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 glibc insufficiente

Il seguente errore si verifica quando la versione glibc locale della distribuzione è troppo vecchia, molto probabilmente perché la distribuzione Linux nel tuo ambiente locale è troppo vecchia. I 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. Ad esempio, questo errore si verifica se esegui l'upgrade di NCCL Core solo su un sottoinsieme di nodi nel cluster, il che causa discrepanze di comunicazione tra i rank di cui è stato eseguito l'upgrade e quelli di cui non è stato eseguito l'upgrade:

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

Per risolvere il problema, controlla la versione di NCCL e gIB e verifica che tutti i nodi del cluster eseguano esattamente la stessa versione di NCCL:

libibverbs non può 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. Ciò non causerà un errore del workload. Tuttavia, NCCL torna a utilizzare TCP e può causare un peggioramento delle prestazioni.

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

Durante la preparazione dei QP per le transazioni di rete effettive da parte del plug-in di rete gIB, potresti riscontrare diversi errori.

Argomento non valido (errno 22)

Il seguente errore si verifica per uno dei seguenti motivi:

  1. L'altra estremità della coppia di code ha una tabella GID danneggiata.
  2. Le variabili di ambiente NCCL/gIB sono configurate in modo errato, 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 sono configurate in modo errato, 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, verifica innanzitutto la causa:

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

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

  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 supporto per una soluzione a lungo termine.

Timeout della connessione (errno 110)

Il seguente errore si verifica quando esiste 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.

QP Got Completion with Error

Il seguente errore si verifica per uno dei seguenti motivi:

  1. Problemi di connessione RDMA sottostanti (link flap 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.