Collecter et comprendre les journaux NCCL/gIB

GPU en cluster

Ce document explique comment collecter et interpréter les journaux NCCL/gIB pour résoudre les problèmes de stabilité et de performances sur AI Hypercomputer, y compris des conseils sur la façon de procéder comme suit :

• Collecter les journaux NCCL
• Comprendre la structure des entrées de journal NCCL
• Vérifier que les plug-ins NCCL/gIB sont correctement chargés
• Vérifier que les versions de NCCL et de gIB sont correctes
• Résoudre les avertissements et les erreurs NCCL courants

Collecter les journaux NCCL

Vous pouvez utiliser les journaux NVIDIA Collective Communications Library (NCCL) pour déboguer les échecs NCCL. Pour tout débogage de stabilité ou de performances, collectez les journaux NCCL à tous les niveaux de journalisation lorsque vous exécutez la charge de travail problématique. Évitez de vider les entrées de journal dans la console, car le volume important des journaux peut empêcher la tâche de se poursuivre.

Pour collecter les journaux NCCL, définissez les variables d'environnement suivantes :

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

Remplacez les éléments suivants :

DESIRED_PATH : chemin d'accès où vous souhaitez stocker vos fichiers journaux

VM_NAME : nom de la VM

RANK_PROCESS_ID : ID de processus du rang

Format des journaux NCCL

Les journaux NCCL sont semblables à ce qui suit :

# 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

Quelle que soit leur source, les journaux NCCL ont un préfixe semblable à ce qui suit :

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

Vérifier que les plug-ins NCCL/gIB sont correctement chargés

NCCL/gIB est composé de plusieurs plug-ins développés par Google. Le fait de ne pas charger l'un des plug-ins peut entraîner de mauvaises performances et, dans certains cas, des erreurs fatales.

Nous vous recommandons d'utiliser la bibliothèque NCCL fournie avec le programme d'installation gIB pour bénéficier des dernières fonctionnalités, des meilleures performances et de la plus grande stabilité. Si vous choisissez d'utiliser une version NCCL personnalisée à des fins de test, par exemple une version NCCL fournie avec le framework de machine learning de votre choix, vous devez également installer le package nccl-gib-plugins.

Plug-in réseau (libnccl-net.so)

Si le plug-in réseau gIB est correctement chargé, vous devriez voir des entrées de journal NCCL semblables à ce qui suit :

... NCCL INFO Using network gIB

Si vous voyez des entrées de journal semblables à l'une des suivantes, suivez les étapes de la section Un objet partagé ne peut pas être chargé pour résoudre le problème.

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

Si le plug-in Tuner gIB est correctement chargé, vous devriez voir des entrées de journal NCCL semblables à ce qui suit :

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

Si vous voyez une entrée de journal semblable à ce qui suit, suivez les étapes de la section Un objet partagé ne peut pas être chargé pour résoudre le problème.

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

Plug-in CollNet

Bien que ces entrées de journal indiquent un échec, elles sont attendues et ne sont pas une source d'inquiétude :

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.

Vérifier la version de NCCL et de gIB

Nous vous recommandons d'utiliser la bibliothèque NCCL fournie avec le programme d'installation gIB pour bénéficier des dernières fonctionnalités, des meilleures performances et de la plus grande stabilité. Toutefois, vous pouvez choisir d'utiliser une version NCCL personnalisée à des fins de test, par exemple une version NCCL fournie avec le framework de machine learning de votre choix. Dans ce cas, installez le package nccl-gib-plugins.

Pour vérifier la version de NCCL et de gIB utilisée, recherchez les entrées de journal NCCL suivantes :

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

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

Pour confirmer que vous exécutez les versions recommandées, comparez les versions NCCL et gIB enregistrées avec celles fournies dans le dernier package nccl-gib. Nous vous recommandons de maintenir nccl-gib à jour sur tous les nœuds. Consultez Installer NCCL/gIB.

Vérifier les variables d'environnement NCCL/gIB

Pour obtenir de bonnes performances NCCL, nous fournissons un script que vous pouvez utiliser pour définir les variables d'environnement NCCL recommandées. Avant d'exécuter votre charge de travail, sourcez le script dans le même environnement que la charge de travail. Dans le programme d'installation NCCL/gIB, le script se trouve à l'emplacement /usr/local/gib/set_nccl_env.sh. Si vous n'utilisez pas ce script et que, par conséquent, les variables d'environnement NCCL sont définies de manière incorrecte, il est possible que le vérificateur de configuration gIB NCCL mette fin à la charge de travail, que NCCL plante ou que les performances de NCCL soient médiocres.

Pour vérifier que les variables d'environnement NCCL/gIB sont correctement appliquées, recherchez les entrées de journal NCCL semblables à ce qui suit :

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

Comparez les valeurs suivantes avec les variables d'environnement NCCL recommandées.

Vérifier le fichier manifeste de la charge de travail GKE

Sur GKE, le fichier manifeste de votre charge de travail Kubernetes nécessite plusieurs configurations pour consommer correctement NCCL/gIB :

• Le fichier manifeste doit installer les binaires NCCL/gIB à partir de /home/kubernetes/bin/gib sur la VM vers /usr/local/gib dans le conteneur de votre charge de travail. Notez que /home/kubernetes/bin/nvidia sur la VM est automatiquement installé sur /usr/local/nvidia dans le conteneur de votre charge de travail.
• Le conteneur de votre charge de travail doit définir LD_LIBRARY_PATH sur /usr/local/gib/lib64:/usr/local/nvidia/lib64.
• Le multiréseau GKE doit être configuré pour votre cluster et vos pools de nœuds, et le fichier manifeste de votre charge de travail doit inclure les annotations multiréseau pour éviter de définir hostNetwork: true.

Un fichier manifeste de charge de travail Kubernetes réel sur GKE est semblable à ce qui suit :

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

Vérifier la table GID

Dans RoCE, la table d'identifiants globaux (GID) est utilisée pour adresser de manière unique le trafic RDMA. Si la table GID est endommagée, aucun trafic RDMA ne peut passer.

Nous fournissons un script show_gids.sh pour afficher la table GID. Dans le programme d'installation, il se trouve à l'emplacement /usr/local/gib/scripts. Si vous avez utilisé notre programme d'installation sans aucune modification, il est installé dans /var/lib/gib/scripts sur la VM.

Lorsque vous exécutez le script dans la VM, vous devriez voir un résultat semblable à ce qui suit :

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

Examinez le résultat et vérifiez les points suivants :

• La table GID comporte le nombre d'entrées approprié :
  • Pour A3 Ultra ou A4, 32 entrées avec 4 entrées par CX-7.
  • Pour A3 Mega, 32 entrées avec 4 entrées par CX-7.
  • Pour A3 High (8 GPU), 16 entrées avec 4 entrées par CX-7.
  • Pour A4X, 16 entrées avec 4 entrées par CX-7.
• Les entrées GID de chaque CX-7 ont les index 0, 1, 2 et 3.
• Pour chaque CX-7, les index 2 et 3 ont une adresse IPv4, et cette adresse IP correspond à l'adresse IPv4 de cet appareil (par exemple, à partir de ip a).

Si l'un de ces éléments est faux, la table GID est endommagée. Envisagez de redémarrer votre VM ou de redémarrer le gestionnaire de réseau dans votre OS invité.

Avertissements NCCL

Les journaux NCCL comportent plusieurs niveaux, les avertissements NCCL (NCCL WARN) étant les plus graves. Les avertissements NCCL indiquent généralement des échecs, qui peuvent ou non être fatals. NCCL ne dispose pas d'un niveau de journalisation qui arrête automatiquement la charge de travail.

Un objet partagé ne peut pas être chargé

L'erreur suivante se produit lorsqu'un objet partagé ne peut pas être chargé en raison de votre configuration.

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

Pour résoudre le problème :

1. Assurez-vous que l'objet partagé est installé dans votre environnement.
2. Assurez-vous que le répertoire de l'objet partagé se trouve dans la variable d'environnement $LD_LIBRARY_PATH.

Échec du mappage du segment à partir de l'objet partagé

L'erreur suivante se produit lorsque le répertoire de l'objet partagé n'est pas exécutable.

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

Pour résoudre le problème, exécutez les commandes suivantes (ces exemples supposent que les binaires gIB sont installés dans /var/lib/gib sur les VM) :

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

Le vérificateur de configuration invité ne trouve pas de fichier de configuration

Des entrées de journal comme celles-ci s'affichent lorsque le vérificateur de configuration invité ne trouve pas de fichier de configuration à utiliser.

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

Pour résoudre le problème, vous pouvez définir la variable d'environnement NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE pour qu'elle pointe vers l'emplacement de guest_config.txtpb. L'emplacement par défaut du fichier de configuration du programme d'installation NCCL/gIB est /usr/local/gib/configs/guest_config.txtpb.

Nous vous déconseillons de désactiver le vérificateur de configuration invité, car il permet de garantir les bonnes pratiques et une configuration appropriée. Toutefois, si nécessaire, vous pouvez désactiver le vérificateur de configuration invité en définissant la variable d'environnement NCCL_SHIMNET_SHIM_LAYERS sur UNUSED.

Le vérificateur de configuration invité a appliqué ou recommandé un paramètre

Les erreurs suivantes se produisent lorsque les variables d'environnement NCCL/gIB ne sont pas définies comme recommandé.

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

Pour résoudre le problème :

1. Suivez les conseils des journaux du vérificateur de configuration invité.
2. Vérifiez les variables d'environnement NCCL/gIB.

Le tuner ne trouve pas de fichier de configuration

L'erreur suivante se produit lorsque le plug-in Tuner ne trouve pas de fichier de configuration à utiliser.

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

Pour résoudre le problème :

1. Définissez la variable d'environnement NCCL_TUNER_CONFIG_PATH pour qu'elle pointe vers l'emplacement de tuner_config.txtpb. L'emplacement par défaut du fichier de configuration du programme d'installation NCCL/gIB est /usr/local/gib/configs/guest_config.txtpb.
2. Vérifiez les variables d'environnement NCCL/gIB.

Version glibc insuffisante

L'erreur suivante se produit lorsque la version glibc locale de votre distribution est trop ancienne, très probablement parce que la distribution Linux de votre environnement local est trop ancienne. Les binaires NCCL/gIB nécessitent la version 2.29 de 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)

Pour résoudre le problème, mettez à niveau la distribution de votre image (par exemple, Ubuntu 20.04 ou version ultérieure, RockyLinux 9 ou version ultérieure).

Message tronqué

L'erreur suivante se produit lorsque vous utilisez des versions NCCL mixtes sur plusieurs rangs.

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

Pour résoudre le problème, vérifiez votre version de NCCL et de gIB. Si vous utilisez GKE, vérifiez ou réinstallez votre daemonset du programme d'installation NCCL/gIB (consultez les instructions pour A3U et A4 ou les instructions pour A4X).

libibverbs ne peut pas charger la configuration du fournisseur

L'erreur suivante se produit lorsque vous n'avez pas installé le répertoire contenant les binaires gIB sur /usr/local/gib. Cela n'entraînera pas d'échec de la charge de travail. Toutefois, NCCL revient à l'utilisation de TCP et peut entraîner de mauvaises performances.

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

Pour résoudre le problème, si vous utilisez GKE, vérifiez le fichier manifeste de votre charge de travail.

Erreurs ibv_modify_qp

Vous pouvez rencontrer un certain nombre d'erreurs lorsque le plug-in réseau gIB prépare les QP pour les transactions réseau réelles.

Argument non valide (errno 22)

L'erreur suivante se produit pour l'une des raisons suivantes :

1. L'autre extrémité du QP comporte une table GID endommagée.
2. Les variables d'environnement NCCL/gIB sont mal configurées, en particulier NCCL_IB_GID_INDEX, NCCL_IB_TC et NCCL_IB_FIFO_TC.

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

Pour résoudre le problème :

1. Recherchez d'autres erreurs ibv_modify_qp avec la signature No data available error 61 et suivez les instructions de correction pour l'erreur 61.
2. Vérifiez les variables d'environnement NCCL/gIB.

Aucune donnée disponible (errno 61)

L'erreur suivante se produit pour l'une des raisons suivantes :

1. Cette VM comporte une table GID endommagée.
2. Les variables d'environnement NCCL/gIB sont mal configurées, en particulier NCCL_IB_GID_INDEX, NCCL_IB_TC et NCCL_IB_FIFO_TC.

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

Pour résoudre le problème, vérifiez d'abord la cause :

1. Vérifiez la table GID.
2. Vérifiez les variables d'environnement NCCL/gIB.

Si la table GID est endommagée, essayez les atténuations suivantes :

1. (À court terme) Redémarrez le gestionnaire de réseau (par exemple, networkd) sur la VM jusqu'à ce que l'adresse IP de l'interface problématique soit actualisée.
   1. Vous pouvez redémarrer networkd sur la VM à l'aide de sudo systemctl restart systemd-networkd.
   2. Vous pouvez afficher l'adresse IP de toutes les interfaces à l'aide de ip a.
   3. Vérifiez que la table GID a été récupérée.
2. Contactez l'assistance Google pour obtenir de l'aide concernant une solution à long terme.

Connexion expirée (errno 110)

L'erreur suivante se produit lorsqu'il existe un problème de connectivité de base entre les VM.

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

Pour résoudre le problème, contactez l'assistance Google.

QP a reçu une finalisation avec une erreur

L'erreur suivante se produit pour l'une des raisons suivantes :

1. Problèmes de connexion RDMA sous-jacents (instabilité des liens, etc.)
2. Les variables d'environnement NCCL/gIB sont mal configurées, en particulier NCCL_IB_TIMEOUT et 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

Pour résoudre le problème, contactez l'assistance Google.