NCCL-/gIB-Logs erfassen und verstehen

In diesem Dokument wird beschrieben, wie Sie NCCL-/gIB-Logs erfassen und interpretieren, um Stabilitäts- und Leistungsprobleme auf dem AI Hypercomputer zu beheben. Außerdem finden Sie hier Anleitungen für Folgendes:

  • NCCL-Logs erfassen.
  • Struktur von NCCL-Logeinträgen
  • Prüfen Sie, ob NCCL-/gIB-Plug-ins korrekt geladen werden.
  • Prüfen Sie, ob die NCCL- und gIB-Versionen korrekt sind.
  • Häufige NCCL-Warnungen und -Fehler beheben.

NCCL-Logs erfassen

Sie können NVIDIA Collective Communications Library-Logs (NCCL) verwenden, um NCCL-Fehler zu beheben. Erfassen Sie für die Fehlerbehebung bei Stabilität oder Leistung NCCL-Logs aus allen Logging-Ebenen, während Sie die problematische Arbeitslast ausführen. Vermeiden Sie es, Logeinträge in der Konsole auszugeben, da die schiere Menge der Logs die Fortsetzung des Jobs verhindern kann.

Legen Sie die folgenden Umgebungsvariablen fest, um NCCL-Logs zu erfassen:

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

Ersetzen Sie Folgendes:

DESIRED_PATH: der Pfad, unter dem Sie Ihre Logdateien speichern möchten

VM_NAME: der VM-Name

RANK_PROCESS_ID: die Prozess-ID des Rangs

NCCL-Logformat

NCCL-Logs sehen in etwa so aus:

# 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

Unabhängig von ihrer Quelle haben NCCL-Logs ein Präfix, das in etwa so aussieht:

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

Prüfen, ob die NCCL-/gIB-Plug-ins richtig geladen sind

NCCL/gIB besteht aus mehreren von Google entwickelten Plug-ins. Wenn eines der Plug-ins nicht geladen werden kann, kann dies zu einer schlechten Leistung und in einigen Fällen zu schwerwiegenden Fehlern führen.

Wir empfehlen, die im gIB-Installationsprogramm enthaltene NCCL zu verwenden, um die neuesten Funktionen, die beste Leistung und die höchste Stabilität zu erhalten. Wenn Sie eine benutzerdefinierte NCCL-Version zum Testen verwenden, z. B. eine NCCL-Version, die mit dem von Ihnen ausgewählten Framework für maschinelles Lernen gebündelt ist, müssen Sie auch das Paket nccl-gib-plugins installieren.

Netzwerk-Plug-in (libnccl-net.so)

Wenn das gIB-Netzwerk-Plug-in korrekt geladen wurde, sollten NCCL-Logeinträge angezeigt werden, die in etwa so aussehen:

... NCCL INFO Using network gIB

Wenn Sie Logeinträge sehen, die den folgenden ähneln, führen Sie die Schritte im Abschnitt Ein freigegebenes Objekt kann nicht geladen werden aus, um das Problem zu beheben.

# 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

Tuner-Plug-in (libnccl-tuner.so)

Wenn das gIB-Tuner-Plug-in korrekt geladen wurde, sollten Sie NCCL-Logeinträge sehen, die in etwa so aussehen:

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

Wenn Sie einen Logeintrag wie den folgenden sehen, führen Sie die Schritte im Abschnitt Ein freigegebenes Objekt kann nicht geladen werden aus, um das Problem zu beheben.

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

CollNet-Plug-in

Obwohl diese Logeinträge auf einen Fehler hinweisen, sind sie zu erwarten und kein Grund zur Sorge:

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- und gIB-Version prüfen

Wir empfehlen, die im gIB-Installationsprogramm enthaltene NCCL zu verwenden, um die neuesten Funktionen, die beste Leistung und die höchste Stabilität zu erhalten. Sie können jedoch eine benutzerdefinierte NCCL-Version für Tests verwenden, z. B. eine NCCL-Version, die mit dem von Ihnen ausgewählten Framework für maschinelles Lernen gebündelt ist. Installieren Sie in diesem Fall das Paket nccl-gib-plugins.

Suchen Sie in Ihren NCCL-Logs nach den folgenden Einträgen, um die NCCL- und gIB-Versionen zu prüfen, die Ihre Arbeitslast verwendet:

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

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

Vergleichen Sie die protokollierten NCCL- und gIB-Versionen mit den im neuesten nccl-gib-Paket enthaltenen Versionen, um zu prüfen, ob Sie die empfohlenen Versionen ausführen. Wir empfehlen, nccl-gib auf allen Knoten auf dem neuesten Stand zu halten. Weitere Informationen finden Sie unter NCCL/gIB installieren.

Wenn Sie NCCL Core manuell aktualisiert oder nccl-gib-plugins mit einer benutzerdefinierten NCCL Core-Bibliothek installiert haben, prüfen Sie, ob die protokollierte NCCL-Version mit Ihrer Zielversion übereinstimmt und ob das NET/gIB-Plug-in initialisiert wird:

# 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

Wenn im Log die ältere gebündelte NCCL-Version anstelle der aktualisierten Version angezeigt wird, lädt der dynamische Linker weiterhin libnccl.so.2 aus /usr/local/gib/lib64 oder /usr/local/gib/lib. Achten Sie darauf, dass Sie die gebündelten libnccl.so*-Dateien wie unter NCCL Core bei vorhandenen Installationen aktualisieren beschrieben entfernt haben.

NCCL-/gIB-Umgebungsvariablen prüfen

Damit Sie eine gute NCCL-Leistung erzielen, stellen wir ein Script bereit, mit dem Sie die empfohlenen NCCL-Umgebungsvariablen festlegen können. Bevor Sie Ihre Arbeitslast ausführen, rufen Sie das Script in derselben Umgebung wie die Arbeitslast auf. Im NCCL/gIB-Installationsprogramm befindet sich das Script unter /usr/local/gib/set_nccl_env.sh. Wenn Sie dieses Script nicht verwenden und NCCL-Umgebungsvariablen daher falsch festgelegt sind, kann es sein, dass die gIB-NCCL-Konfigurationsprüfung die Arbeitslast beendet, NCCL abstürzt oder die NCCL-Leistung schlecht ist.

Wenn Sie prüfen möchten, ob die NCCL-/gIB-Umgebungsvariablen richtig angewendet wurden, suchen Sie nach NCCL-Logeinträgen, die in etwa so aussehen:

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

Vergleichen Sie die folgenden Werte mit den empfohlenen NCCL-Umgebungsvariablen.

GKE-Arbeitslastmanifest prüfen

In GKE sind für Ihr Kubernetes-Arbeitslastmanifest mehrere erforderliche Konfigurationen erforderlich, damit NCCL/gIB reibungslos genutzt werden kann:

  • Im Manifest müssen die NCCL-/gIB-Binärdateien von /home/kubernetes/bin/gib auf der VM in /usr/local/gib in Ihrem Arbeitslastcontainer bereitgestellt werden. Beachten Sie, dass /home/kubernetes/bin/nvidia auf der VM automatisch in /usr/local/nvidia in Ihrem Arbeitslastcontainer bereitgestellt wird.
  • In Ihrem Arbeitslastcontainer muss LD_LIBRARY_PATH auf /usr/local/gib/lib64:/usr/local/nvidia/lib64 festgelegt sein.
  • Für Ihren Cluster und Ihre Knotenpools muss GKE-Multi-Netzwerke eingerichtet sein und Ihr Arbeitslastmanifest muss die Multi-Netzwerk-Annotationen enthalten, damit hostNetwork: true nicht festgelegt werden muss.

Ein tatsächliches Kubernetes-Arbeitslastmanifest in GKE sieht in etwa so aus:

...
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-Tabelle prüfen

In RoCE wird die GID-Tabelle (Global Identifier) verwendet, um RDMA-Traffic eindeutig zu adressieren. Wenn die GID-Tabelle beschädigt ist, kann kein RDMA-Traffic übertragen werden.

Wir stellen ein Skript show_gids.sh bereit, mit dem die GID-Tabelle angezeigt werden kann. Im Installationsprogramm befindet sie sich unter /usr/local/gib/scripts. Wenn Sie unser Installationsprogramm ohne Änderungen verwendet haben, wird es auf der VM unter /var/lib/gib/scripts installiert.

Wenn Sie das Script in der VM ausführen, sollte die Ausgabe in etwa so aussehen:

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

Prüfen Sie die Ausgabe und bestätigen Sie Folgendes:

  • Die GID-Tabelle hat die richtige Anzahl von Einträgen:
    • Für A3 Ultra oder A4 32 Einträge mit 4 Einträgen pro CX-7.
    • Für A3 Mega 32 Einträge mit 4 Einträgen pro CX-7.
    • Für A3 High (8 GPUs) 16 Einträge mit 4 Einträgen pro CX-7.
    • Für A4X: 16 Einträge mit 4 Einträgen pro CX-7.
  • Die GID-Einträge jeder CX-7 haben die Indexe 0, 1, 2 und 3.
  • Für jeden CX-7 haben die Indexe 2 und 3 eine IPv4-Adresse, die mit der IPv4-Adresse dieses Geräts übereinstimmt (z. B. aus ip a).

Wenn eines dieser Elemente falsch ist, ist die GID-Tabelle fehlerhaft. Starten Sie die VM oder den Netzwerkmanager im Gastbetriebssystem neu.

NCCL-Warnungen

NCCL-Logs haben mehrere Stufen, wobei NCCL-Warnungen (NCCL WARN) die schwerwiegendsten sind. NCCL-Warnungen weisen in der Regel auf Fehler hin, die schwerwiegend sein können oder auch nicht. NCCL hat keine Logebene, die die Arbeitslast automatisch beendet.

Ein freigegebenes Objekt kann nicht geladen werden

Der folgende Fehler tritt auf, wenn ein freigegebenes Objekt aufgrund Ihrer Einrichtung nicht geladen werden kann:

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

Dieser Fehler tritt auch auf, wenn Sie die gebündelten libnccl.so*-Dateien während eines manuellen NCCL Core-Upgrades entfernen, bevor Sie eine kompatible NCCL Core-Bibliothek installieren, oder wenn sich das Installationsverzeichnis der Bibliothek nicht im Suchpfad des dynamischen Linkers befindet.

So beheben Sie das Problem:

  1. Prüfen Sie, ob das freigegebene Objekt in Ihrer Umgebung installiert ist.
  2. Prüfen Sie, ob sich das Verzeichnis mit dem freigegebenen Objekt im Suchpfad des dynamischen Linkers oder in der Umgebungsvariablen $LD_LIBRARY_PATH befindet.

Segment konnte nicht aus freigegebenem Objekt zugeordnet werden

Der folgende Fehler tritt auf, wenn das Verzeichnis des freigegebenen Objekts nicht ausführbar ist.

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

Führen Sie die folgenden Befehle aus, um das Problem zu beheben. In diesen Beispielen wird davon ausgegangen, dass die gIB-Binärdateien auf den VMs in /var/lib/gib installiert sind:

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

Guest Config Checker kann keine Konfigurationsdatei finden

Solche Logeinträge werden angezeigt, wenn der Gast-Konfigurationsprüfer keine Konfigurationsdatei findet, die er verwenden kann.

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

Um das Problem zu beheben, können Sie die Umgebungsvariable NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE so festlegen, dass sie auf den Speicherort von guest_config.txtpb verweist. Der Standardspeicherort für die Konfigurationsdatei des NCCL/gIB-Installationsprogramms ist /usr/local/gib/configs/guest_config.txtpb.

Wir raten davon ab, den Gast-Konfigurationsprüfer zu deaktivieren, da er dazu beiträgt, Best Practices und eine ordnungsgemäße Konfiguration zu gewährleisten. Bei Bedarf können Sie den Gast-Config Checker jedoch deaktivieren, indem Sie die Umgebungsvariable NCCL_SHIMNET_SHIM_LAYERS auf UNUSED setzen.

Die folgenden Fehler treten auf, wenn die NCCL-/gIB-Umgebungsvariablen nicht wie empfohlen festgelegt sind.

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

So beheben Sie das Problem:

  1. Folgen Sie der Anleitung in den Config Checker-Logs des Gastes.
  2. Prüfen Sie die NCCL-/gIB-Umgebungsvariablen.

Tuner kann keine Konfigurationsdatei finden

Der folgende Fehler tritt auf, wenn das Tuner-Plug-in keine Konfigurationsdatei findet, die verwendet werden kann.

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

So beheben Sie das Problem:

  1. Legen Sie die Umgebungsvariable NCCL_TUNER_CONFIG_PATH so fest, dass sie auf den Speicherort von tuner_config.txtpb verweist. Der Standardspeicherort für die Konfigurationsdatei des NCCL/gIB-Installationsprogramms ist /usr/local/gib/configs/guest_config.txtpb.
  2. Prüfen Sie die NCCL-/gIB-Umgebungsvariablen.

Unzureichende glibc-Version

Der folgende Fehler tritt auf, wenn die glibc-Version Ihrer lokalen Distribution zu alt ist. Das liegt wahrscheinlich daran, dass die Linux-Distribution in Ihrer lokalen Umgebung zu alt ist. Für die NCCL-/gIB-Binärdateien ist die glibc-Version 2.29 erforderlich.

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

Führen Sie zur Problembehebung ein Upgrade Ihrer Image-Distribution durch (z. B. Ubuntu 20.04 oder höher, RockyLinux 9 oder höher).

Nachricht gekürzt

Der folgende Fehler tritt auf, wenn Sie gemischte NCCL-Versionen über Ränge hinweg verwenden. Dieser Fehler tritt beispielsweise auf, wenn Sie NCCL Core nur auf einer Teilmenge der Knoten im Cluster aktualisieren. Dies führt zu Kommunikationsfehlern zwischen aktualisierten und nicht aktualisierten Rängen:

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

Prüfen Sie zur Behebung dieses Problems Ihre NCCL- und gIB-Version und vergewissern Sie sich, dass auf allen Clusterknoten genau dieselbe NCCL-Version ausgeführt wird:

libibverbs kann die Anbieterkonfiguration nicht laden

Der folgende Fehler tritt auf, wenn Sie das Verzeichnis mit den gIB-Binärdateien nicht in /usr/local/gib bereitgestellt haben. Dies führt nicht zu einem Ausfall der Arbeitslast. NCCL greift jedoch auf TCP zurück, was zu einer schlechten Leistung führen kann.

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

Wenn Sie GKE verwenden, prüfen Sie Ihr Arbeitslastmanifest, um das Problem zu beheben.

ibv_modify_qp-Fehler

Es gibt eine Reihe von Fehlern, die auftreten können, wenn das gIB-Netzwerk-Plug-in QPs für tatsächliche Netzwerktransaktionen vorbereitet.

Ungültiges Argument (errno 22)

Der folgende Fehler tritt aus einem der folgenden Gründe auf:

  1. Das andere Ende des QP hat eine fehlerhafte GID-Tabelle.
  2. NCCL/gIB-Umgebungsvariablen sind falsch konfiguriert, insbesondere NCCL_IB_GID_INDEX, NCCL_IB_TC und NCCL_IB_FIFO_TC.
... NCCL WARN Call to ibv_modify_qp failed with error Invalid argument errno 22

So beheben Sie das Problem:

  1. Suchen Sie nach anderen ibv_modify_qp-Fehlern mit der Signatur No data available error 61 und folgen Sie der Anleitung zur Fehlerbehebung für Fehler 61.
  2. Prüfen Sie die NCCL-/gIB-Umgebungsvariablen.

Keine Daten verfügbar (errno 61)

Der folgende Fehler tritt aus einem der folgenden Gründe auf:

  1. Diese VM hat eine fehlerhafte GID-Tabelle.
  2. NCCL-/gIB-Umgebungsvariablen sind falsch konfiguriert, insbesondere NCCL_IB_GID_INDEX, NCCL_IB_TC und NCCL_IB_FIFO_TC.
... NCCL WARN Call to ibv_modify_qp failed with error No data available errno 61

Prüfen Sie zuerst, was die Ursache des Problems ist:

  1. Prüfen Sie die GID-Tabelle.
  2. NCCL-/gIB-Umgebungsvariablen prüfen

Wenn die GID-Tabelle beschädigt ist, versuchen Sie Folgendes:

  1. (Kurzfristig) Starten Sie den Netzwerkmanager (z. B. networkd) auf der VM neu, bis die IP-Adresse der problematischen Schnittstelle aktualisiert wird.
    1. Sie können networkd auf der VM mit sudo systemctl restart systemd-networkd neu starten.
    2. Sie können die IP-Adresse aller Schnittstellen mit ip a aufrufen.
    3. Prüfen Sie, ob die GID-Tabelle wiederhergestellt wurde.
  2. Wenden Sie sich an den Google-Support, um Unterstützung bei einer langfristigen Lösung zu erhalten.

Zeitüberschreitung der Verbindung (errno 110)

Der folgende Fehler tritt auf, wenn ein grundlegendes Verbindungsproblem zwischen den VMs vorliegt.

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

Wenden Sie sich an den Google-Support, um das Problem zu beheben.

QP Got Completion with Error

Der folgende Fehler tritt aus einem der folgenden Gründe auf:

  1. Zugrunde liegende RDMA-Verbindungsprobleme (Link-Flaps usw.)
  2. NCCL/gIB-Umgebungsvariablen sind falsch konfiguriert, insbesondere NCCL_IB_TIMEOUT und 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

Wenden Sie sich an den Google-Support, um das Problem zu beheben.