PCCL: 多卡异常问题分析指南（v2.1）

2.1 应用 log 分析

在上层应用所报的 log 中我们主要关注 pccl init 阶段的日志信息与上层应用（含框架/模型训练代码）中的Error/Warning等信息。其中通信库的 log 需要应用启动前配置环境变量NCCL_DEBUG 为 INFO 方可显示。

• pccl 日志:

  • 关注通信 ranks 间使用的传输类型，一般高效的单机内通信会发生在 ICN 链路上，而高效的多机间通信则会通过 IB 网卡参与的 RDMA 链路来进行。当 logs 中出现其他类型的 path type 时，就需要保持警惕，可以怀疑节点内的 icn link 状态或者节点之间网络是否存在问题。

    • 当发现机内 ICN 连接问题时，在问题机器上使用 ppu-smi topo -m观察机内 topo 是否符合预期。

    • 当出现 IB 相关问题时，在问题机器上使用 ib 相关工具检查网络是否正常。

  • 关注 topo 创建的情况。进一步可以通过设置 NCCL_TOPO_DUMP_FILE和 NCCL_GRAPH_DUMP_FILE将init 阶段生成的 topo 或 graph dump 到文件中做离线分析。

  • 特别地，当任务配置了 NCCL_DEBUG_SUBSYS=ALL或者 NCCL_DEBUG_SUBSYS=COLL时，可以请 pccl 团队解析通信 op 的执行序列，以便于后续问题进一步定位。

• 框架日志中的 Error 情况：

  • 通过检查参与通信的各个进程执行的状态，可以看是否有某 rank 对应的进程或线程提前退出的情况，此时其他 peer rank 对应的进程或线程因某步通信同步未能得到响应一般会陷入 hang 的状态，乃至可能会 timeout 退出。当上述情况发生时，一般需要先检查异常 rank 提前退出的原因。

下面2.1.1 与2.1.2 小节中我们将重点说明下如何得到 pccl 执行时生成 logs 及 关键 topo / graph dump files 以进一步做分析的方法。

2.2 系统 dmesg -T分析

在 kernel 日志中，我们主要关注 PPU 和 RDMA NIC 相关的错误和报警信息。可通过如下 shell 命令过滤。

dmesg -T | grep IH
dmesg -T | grep Error
dmesg -T | grep mlx5

注：需要确保 dmesg 信息的开始时间早于应用启动时间。如果有异常信息，它的发生时间应晚于任务启动时间。

与 PPU 相关的 exceptions 信息类型介绍可见下面文档：PPU XID定义

3.1 crash in host

建议使能操作系统的 coredump。通过配置ulimit -c unlimited打开。应用 crash 后会在相应的路径下生成host coredump 文件。此时建议用户先 high level 做上层应用逻辑出错排查。当 crash 发生在 PPU 软件栈上时则可联系 PPU 同学协助做排查。

3.2 crash in PPU

export ALIPPU_ENABLE_COREDUMP_ON_EXCEPTION=1
export ALIPPU_ENABLE_LIGHTWEIGHT_COREDUMP=1
export ALIPPU_COREDUMP_FILE=${HOME}/hggc.core.%h.%p.%t

4.1 状态监控（timeout state monitor）

pccl 内部会记录每个 rank 每次通信操作 kernel launch 到 PPU 上后持续的时间，超过 5 分钟 （默认配置，可通过环境变量 PCCL_STATE_MONITOR_TIMEOUT_MS 配置，单位为毫秒）后无状态更新，会报 WARNING（配置 NCCL_DEBUG=INFO/WARN 后可见），并触发状态保存，所有状态保存文件都默认位于 $HOME/.pccl路径下。

状态保存包括 comm_dump、state_monitor_dump、proxy_dump 三个子目录，其中 proxy_dump 只在多机场景会产生。comm_dump 下每个文件对应一个 rank 在某一时刻产生的 dump 文件，文件内容包含当前的 workfifo 执行状态。state_monitor_dump 下每个文件对应一个 rank，文件内容包含该 rank 主动检测到 timeout 的日志。proxy_dump 与 comm_dump 类似，文件内容包含当前跨机收发状态。

更多可配置环境变量如下：

• PCCL_DEBUG_DUMP_DIR=指定保存状态文件的目录。状态文件将保存在 /.pccl 目录下。默认保存在 $HOME/.pccl 目录下。

• PCCL_STATE_MONITOR_LEVEL=[0,1,2]状态监控级别。0: 关闭状态监控；1: device 侧监控，能应对绝大部分 hang 场景且性能友好；2: host 侧监控，能应对所有 hang 场景但可能影响 latency。默认值为 1。

  • level 1 监控日志示例

    

  • level 2 监控日志示例

    

• PCCL_STATE_MONITOR_DISABLE=[0,1]是否关闭状态监控。1: 关闭状态监控；0: 开启状态监控。配置 PCCL_STATE_MONITOR_DISABLE=1 或PCCL_STATE_MONITOR_LEVEL=0状态监控都会被关闭，前者在 1.4 rel 开始支持，后者 1.5 rel 开始支持，建议 1.5 rel 及之后的版本使用后者。

• PCCL_STATE_MONITOR_DUMP_WHEN_EXCEPTION_DISABLE=1是否关闭自动状态保存。

  • 0: 不关闭，检测到 timeout 后会打印 warning 并且保存 comm/proxy dump 状态文件；

  • 1: 关闭，检测到 timeout 后只打印 warning 但是不保存任何状态文件。

• PCCL_STATE_MONITOR_LOG_EVERY_MS=xx是否要显示实时的执行进度，以及每隔 xx 毫秒打印一次。xx=0: 不打印；xx>0: 每隔 xx 毫秒打印一次当前已入队和已结束的 op 数。

• PCCL_STATE_MONITOR_DUMP_DIR_SIZE_LIMIT_MB= 指定 dump 目录最大空间限制，默认 2GB.

2.0 release 版本新增 RAS 功能支持，工具位于 PPU_SDK/pccl_tools/pcclras，支持在运行时由用户主动查询执行状态、触发 comm/proxy dump.

2.1 release 版本开始，PPU_SDK 不再包含通信库相关工具 pccl_tools，需要从独立发布的 pccl 包下找到 pcclras 工具，独立发布链接：https://art-pub.eng.t-head.cn/artifactory/generic-local/SAIL/v2.1.0/COMM ，发布包命名为pccl_2.1.0_<hggcrt_version>_<os_version>.tar.gz，请根据实际场景所需的系统版本和 hggc runtime 版本下载对应包。

使用方法：

• 查询状态：pcclras

• 触发 dump: pcclras -d 0x1

4.2 状态保存

目前支持保存 3 种不同的状态文件：

• DUMP_ROUGH ： 包含 communicator 中每个 channel 的 workFifo 与 peers（head/tail/step 等）信息，可直接打开。

• DUMP_RAW ： 导出 communicator 整个 binary 空间，包含更多数据，二进制文件，需要特定解析程序打开。

• DUMP_HWINFO ： core dump 文件，需要使用 ppu-gdb 解析。

通过配置 PCCL_COMM_DUMP_LEVEL 可以配置保存哪些文件，默认为 DUMP_ROUGH。例如：export PCCL_COMM_DUMP_LEVEL=DUMP_ROUGH,DUMP_RAW可同时保存 ROUGH 和 RAW 文件。

多机时还会额外 dump proxy 的状态文件，位于 $HOME/.pccl/proxy_dump 路径下。

所有状态文件默认位于用户 $HOME/.pccl/comm_dump 路径下，如：

触发状态保存有以下 2 种方法：

4.3 状态分析

目前上述状态文件收集后尚不能自动去解析并对问题类型做判断，尚需要转交给平头哥研发同学进一步做问题分析与定位。