Collecter et comprendre les journaux NCCL/gIB

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. Il explique également comment :

  • Collectez les journaux NCCL.
  • Comprendre la structure des entrées de journal NCCL
  • Vérifiez que les plug-ins NCCL/gIB sont correctement chargés.
  • Vérifiez 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 de la bibliothèque NVIDIA Collective Communications Library (NCCL) pour déboguer les échecs NCCL. Pour tout débogage de stabilité ou de performances, collectez les journaux NCCL à partir de tous les niveaux de journalisation pendant que 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 se présentent comme 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 à celui-ci :

<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. L'échec du chargement de l'un des plug-ins peut entraîner des performances médiocres 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 d'une stabilité optimale. Si vous choisissez d'utiliser une version NCCL personnalisée pour les tests, telle qu'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 à celles-ci :

... NCCL INFO Using network gIB

Si vous voyez des entrées de journal semblables à l'une des suivantes, suivez les étapes de la section Impossible de charger un objet partagé 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 de réglage (libnccl-tuner.so)

Si le plug-in de réglage gIB est correctement chargé, vous devriez voir des entrées de journal NCCL semblables à celles-ci :

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

Si une entrée de journal semblable à la suivante s'affiche, suivez les étapes de la section Impossible de charger un objet partagé 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 doivent pas vous inquiéter :

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 d'une stabilité optimale. Toutefois, vous pouvez choisir d'utiliser une version NCCL personnalisée pour les tests, 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 les versions de NCCL et de gIB utilisées par votre charge de travail, recherchez les entrées suivantes dans vos journaux NCCL :

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

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

Pour vérifier que vous exécutez les versions recommandées, comparez les versions de NCCL et de gIB enregistrées avec les versions incluses dans le dernier package nccl-gib. Nous vous recommandons de maintenir nccl-gib à jour sur tous les nœuds. Pour en savoir plus, consultez Installer NCCL/gIB.

Si vous avez mis à niveau NCCL Core manuellement ou installé nccl-gib-plugins avec une bibliothèque NCCL Core personnalisée, vérifiez que la version de NCCL enregistrée correspond à votre version cible et que le plug-in NET/gIB s'initialise :

# 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

Si le journal affiche la version NCCL groupée précédente au lieu de la version mise à niveau, l'éditeur de liens dynamique charge toujours libnccl.so.2 à partir de /usr/local/gib/lib64 ou /usr/local/gib/lib. Assurez-vous d'avoir supprimé les fichiers libnccl.so* groupés, comme décrit dans Mettre à niveau NCCL Core sur les installations existantes.

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 mal définies, il est possible que le vérificateur de configuration NCCL gIB 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 des entrées de journal NCCL semblables aux suivantes :

# 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 utiliser NCCL/gIB de manière fluide :

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

Un fichier manifeste de charge de travail Kubernetes réel sur GKE ressemble à ceci :

...
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) permet d'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 dans /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, un résultat semblable à celui-ci doit s'afficher :

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 bon nombre d'entrées :
    • 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'IPv4 de cet appareil (par exemple, à partir de ip a).

Si l'un de ces éléments est faux, la table GID est défectueuse. Envisagez de redémarrer votre VM ou 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 être fatals ou non. NCCL ne dispose pas d'un niveau de journalisation qui arrête automatiquement la charge de travail.

Impossible de charger un objet partagé

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

Cette erreur se produit également si vous supprimez les fichiers libnccl.so* groupés lors d'une mise à niveau manuelle de NCCL Core avant d'installer une bibliothèque NCCL Core compatible, ou si le répertoire d'installation de la bibliothèque ne se trouve pas dans le chemin de recherche de l'éditeur de liens dynamique.

Pour résoudre ce problème, procédez comme suit :

  1. Vérifiez que l'objet partagé est installé dans votre environnement.
  2. Vérifiez que le répertoire contenant l'objet partagé se trouve dans le chemin de recherche de l'éditeur de liens dynamique ou 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

Guest Config Checker 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 de sorte qu'elle pointe vers l'emplacement de guest_config.txtpb. L'emplacement par défaut du fichier de configuration pour le 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 le respect des 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.

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 instructions des journaux de l'outil de vérification de la configuration de l'invité.
  2. Vérifiez les variables d'environnement NCCL/gIB.

Tuner ne trouve pas de fichier de configuration

L'erreur suivante se produit lorsque le plug-in de réglage 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 pour le programme d'installation NCCL/gIB est /usr/local/gib/configs/guest_config.txtpb.
  2. Vérifiez les variables d'environnement NCCL/gIB.

Version de glibc insuffisante

L'erreur suivante se produit lorsque la version glibc locale de votre distribution est trop ancienne, 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 votre distribution d'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 différentes versions de NCCL sur plusieurs rangs. Par exemple, cette erreur se produit si vous mettez à niveau NCCL Core sur un sous-ensemble de nœuds du cluster, ce qui entraîne des incohérences de communication entre les rangs mis à niveau et ceux qui ne le sont pas :

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

Pour résoudre ce problème, vérifiez votre version de NCCL et de gIB, et assurez-vous que tous les nœuds du cluster exécutent exactement la même version de NCCL :

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 dans /usr/local/gib. Cela n'entraînera pas l'échec de la charge de travail. Toutefois, NCCL utilise TCP par défaut, ce qui 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é de la QP comporte une table GID défectueuse.
  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, puis 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. La table GID de cette VM est défectueuse.
  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, commencez par en rechercher 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 solutions 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 afin de trouver une solution à long terme.

Connexion expirée (errno 110)

L'erreur suivante se produit en cas de 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 Got Completion with Error

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

  1. Problèmes de connexion RDMA sous-jacents (battements de liaison, 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.