收集并了解 NCCL/gIB 日志以进行问题排查

本文档介绍了如何收集和解读 NCCL/gIB 日志，以排查 AI Hypercomputer 上的稳定性和性能问题，包括有关如何实现以下目标的指南：

收集 NCCL 日志。
了解 NCCL 日志条目的结构。
验证 NCCL/gIB 插件是否已正确加载。
检查 NCCL 和 gIB 版本是否正确。
排查常见的 NCCL 警告和错误。

收集 NCCL 日志

您可以使用 NVIDIA Collective Communications Library (NCCL) 日志来调试 NCCL 故障。对于任何稳定性或性能调试，请在运行有问题的工作负载时，从所有日志记录级别收集 NCCL 日志。避免将日志条目转储到控制台，因为大量日志可能会阻止作业继续运行。

如需收集 NCCL 日志，请设置以下环境变量：

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

替换以下内容：

DESIRED_PATH：您要存储日志文件的路径

VM_NAME：虚拟机的名称

RANK_PROCESS_ID：排名的进程 ID

NCCL 日志格式

NCCL 日志类似于以下内容：

# 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

无论来源如何，NCCL 日志都具有类似以下内容的前缀：

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

验证 NCCL/gIB 插件是否已正确加载

NCCL/gIB 由多个 Google 开发的插件组成。如果未能加载任何插件，可能会导致性能不佳，在某些情况下还会出现严重错误。

网络插件 (libnccl-net.so)

如果 gIB 网络插件已正确加载，您应该会看到类似于以下内容的 NCCL 日志条目：

... NCCL INFO Using network gIB

如果您看到类似于以下任何一种的日志条目，请按照无法加载共享对象部分中的步骤解决问题。

# 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

调谐器插件 (libnccl-tuner.so)

如果 gIB 调谐器插件已正确加载，您应该会看到类似于以下内容的 NCCL 日志条目：

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

如果您看到类似于以下内容的日志条目，请按照无法加载共享对象部分中的步骤来解决此问题。

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

CollNet 插件

虽然这些日志条目表明存在失败情况，但这是预期行为，不必担心：

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 和 gIB 版本

我们建议您使用 gIB 安装程序捆绑的 NCCL，以确保获得最新功能、最佳性能和最高稳定性。不过，您可以选择使用自定义 NCCL 版本进行测试，例如与您选择的机器学习框架捆绑在一起的 NCCL 版本。

如需检查所用的 NCCL 和 gIB 版本，请查找以下 NCCL 日志条目：

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

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

验证 NCCL/gIB 环境变量

为了获得良好的 NCCL 性能，我们提供了一个脚本，您可以使用该脚本设置推荐的 NCCL 环境变量。在运行工作负载之前，请在与工作负载相同的环境中获取脚本的源代码。在 NCCL/gIB 安装程序中，脚本位于 /usr/local/gib/set_nccl_env.sh。如果您不使用此脚本，导致 NCCL 环境变量设置不正确，则 gIB NCCL 配置检查器可能会终止工作负载，NCCL 可能会崩溃，或者 NCCL 性能可能会很差。

如需检查 NCCL/gIB 环境变量是否已正确应用，请查找类似于以下内容的 NCCL 日志条目：

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

将以下值与建议的 NCCL 环境变量进行比较。

检查 GKE 工作负载清单

在 GKE 上，您的 Kubernetes 工作负载清单需要进行多项设置，才能顺利使用 NCCL/gIB：

清单必须将虚拟机上 /home/kubernetes/bin/gib 中的 NCCL/gIB 二进制文件装载到工作负载容器中的 /usr/local/gib。请注意，虚拟机上的 /home/kubernetes/bin/nvidia 会自动装载到工作负载容器中的 /usr/local/nvidia。
工作负载容器必须将 LD_LIBRARY_PATH 设置为 /usr/local/gib/lib64:/usr/local/nvidia/lib64。
您的集群和节点池必须设置 GKE 多网络，并且您的工作负载清单必须包含多网络注解，以避免需要设置 hostNetwork: true。

GKE 上的实际 Kubernetes 工作负载清单类似于以下内容：

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

在 RoCE 中，全局标识符 (GID) 表用于唯一寻址 RDMA 流量。如果 GID 表损坏，则无法传递任何 RDMA 流量。

我们提供了一个脚本 show_gids.sh 来显示 GID 表。在安装程序中，它位于 /usr/local/gib/scripts。如果您使用我们的安装程序且未进行任何修改，则该程序会安装到虚拟机上的 /var/lib/gib/scripts。

在虚拟机中运行脚本时，您应该会看到类似如下内容的输出：

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

查看输出并确认以下内容：

GID 表具有适当数量的条目：
- 对于 A3 Ultra 或 A4，32 个条目，每个 CX-7 有 4 个条目。
- 对于 A3 Mega，32 个条目，每个 CX-7 有 4 个条目。
- 对于 A3 High（8 个 GPU），有 16 个条目，每个 CX-7 有 4 个条目。
- 对于 A4X，16 个条目，每个 CX-7 有 4 个条目。
每个 CX-7 的 GID 条目都有索引 0、1、2 和 3。
对于每个 CX-7，索引 2 和 3 都有一个 IPv4 地址，并且该 IP 地址与相应设备的 IPv4 地址（例如来自 ip a）相匹配。

如果其中任何一项为 false，则 GID 表已损坏。考虑重新启动虚拟机或重新启动客机操作系统中的网络管理器。

NCCL 警告

NCCL 日志有多个级别，其中 NCCL 警告 (NCCL WARN) 的严重程度最高。NCCL 警告通常表示失败，可能是致命的，也可能不是。NCCL 没有可自动停止工作负载的日志级别。

无法加载共享对象

如果由于您的设置而无法加载共享对象，则会发生以下错误。

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

若要解决此问题，请执行以下操作：

确保已在环境中安装共享对象。
确保共享对象的目录位于 $LD_LIBRARY_PATH 环境变量中。

未能映射共享对象中的段

如果共享对象的目录不可执行，则会发生以下错误。

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

如需解决此问题，请运行以下命令（以下示例假设 gIB 二进制文件安装在虚拟机上的 /var/lib/gib 中）：

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

Guest Config Checker 找不到配置文件

当 Guest 配置检查器找不到要使用的配置文件时，系统会显示此类日志条目。

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

如需解决此问题，您可以设置环境变量 NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE 以指向 guest_config.txtpb 的位置。NCCL/gIB 安装程序的配置文件的默认位置为 /usr/local/gib/configs/guest_config.txtpb。

我们不建议您停用 Guest 配置检查器，因为它可以帮助确保最佳实践和正确配置。不过，如有必要，您可以通过将环境变量 NCCL_SHIMNET_SHIM_LAYERS 设置为 UNUSED 来停用 Guest 配置检查器。

访客配置检查工具强制执行或推荐了某项设置

如果未按建议设置 NCCL/gIB 环境变量，则会发生以下错误。

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

若要解决此问题，请执行以下操作：

按照访客配置检查器日志的指导操作。
验证 NCCL/gIB 环境变量。

调谐器找不到配置文件

如果调谐器插件找不到要使用的配置文件，则会发生以下错误。

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

若要解决此问题，请执行以下操作：

将环境变量 NCCL_TUNER_CONFIG_PATH 设置为指向 tuner_config.txtpb 的位置。NCCL/gIB 安装程序的配置文件的默认位置为 /usr/local/gib/configs/guest_config.txtpb。
验证 NCCL/gIB 环境变量。

glibc 版本过低

当您的发行版本地 glibc 版本过旧时，会发生以下错误，这很可能是因为您本地环境中的 Linux 发行版过旧。NCCL/gIB 二进制文件需要 glibc 版本 2.29。

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

如需解决此问题，请升级映像分发版本（例如 Ubuntu 20.04 或更高版本、RockyLinux 9 或更高版本）。

消息被截断

当您在不同 rank 中使用混合 NCCL 版本时，会发生以下错误。

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

如需解决此问题，请检查您的 NCCL 和 gIB 版本。如果您使用的是 GKE，请检查或重新安装 NCCL/gIB 安装程序 DaemonSet（请参阅 A3U 和 A4 的相关说明或 A4X 的相关说明）。

libibverbs 无法加载提供程序配置

如果您未将包含 gIB 二进制文件的目录装载到 /usr/local/gib，则会发生以下错误。这不会导致工作负载失败。不过，NCCL 会回退到使用 TCP，这可能会导致性能不佳。

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

如需解决此问题，如果您使用的是 GKE，请检查您的工作负载清单。

ibv_modify_qp 错误

当 gIB 网络插件为实际网络事务准备 QP 时，您可能会遇到许多错误。

实参无效 (errno 22)

出现以下错误的原因如下：

QP 的另一端具有损坏的 GID 表。
NCCL/gIB 环境变量配置错误，尤其是 NCCL_IB_GID_INDEX、NCCL_IB_TC 和 NCCL_IB_FIFO_TC。

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

若要解决此问题，请执行以下操作：

查找具有签名 No data available error 61 的其他 ibv_modify_qp 错误，然后按照针对错误 61 的缓解说明操作。
验证 NCCL/gIB 环境变量。

无可用数据 (errno 61)

出现以下错误的原因如下：

此虚拟机的 GID 表已损坏。
NCCL/gIB 环境变量配置错误，尤其是 NCCL_IB_GID_INDEX、NCCL_IB_TC 和 NCCL_IB_FIFO_TC。

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

如需解决此问题，请先检查原因：

检查 GID 表。
验证 NCCL/gIB 环境变量。

如果 GID 表损坏，请尝试以下缓解措施：

（短期）在虚拟机上重启网络管理器（例如 networkd），直到问题接口的 IP 地址刷新为止。
1. 您可以使用 sudo systemctl restart systemd-networkd 在虚拟机上重启 networkd。
2. 您可以使用 ip a 查看所有接口的 IP 地址。
3. 检查 GID 表是否已恢复。
如需有关长期解决方案的帮助，请与 Google 支持团队联系。

连接超时 (errno 110)

当虚拟机之间存在基本连接问题时，会发生以下错误。

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

如需解决此问题，请与 Google 支持团队联系以寻求帮助。

QP 收到“完成（有错误）”消息

出现以下错误的原因如下：

底层 RDMA 连接问题（链路抖动等）。
NCCL/gIB 环境变量配置错误，尤其是 NCCL_IB_TIMEOUT 和 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

如需解决此问题，请与 Google 支持团队联系以寻求帮助。

收集并了解 NCCL/gIB 日志以进行问题排查 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

收集 NCCL 日志

NCCL 日志格式

验证 NCCL/gIB 插件是否已正确加载

网络插件 (libnccl-net.so)

调谐器插件 (libnccl-tuner.so)

CollNet 插件

检查 NCCL 和 gIB 版本

验证 NCCL/gIB 环境变量

检查 GKE 工作负载清单

检查 GID 表

NCCL 警告

无法加载共享对象

未能映射共享对象中的段

Guest Config Checker 找不到配置文件

访客配置检查工具强制执行或推荐了某项设置

调谐器找不到配置文件

glibc 版本过低

消息被截断

libibverbs 无法加载提供程序配置

ibv_modify_qp 错误

实参无效 (errno 22)

无可用数据 (errno 61)

连接超时 (errno 110)

QP 收到“完成（有错误）”消息

收集并了解 NCCL/gIB 日志以进行问题排查