HCCL故障定位思路：三阶段定界、多级检索关键字与故障码体系详解
【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl
本篇技术文章基于 HCCL 用户指南中的《定位思路》文档展开，系统讲解昇腾集群上 HCCL 通信故障的定位方法论：如何借助故障码体系与 CANN 日志完成快速定界，如何依据"通信域初始化、参数面建链、通信算子执行"三大阶段划分排查路径，以及如何运用 HCCL 多级检索关键字、算子级入参日志与环境变量生效值查询等手段锁定根因。读完后，你将掌握一套从"看到报错"到"定位根节点"的完整故障诊断工作流，并了解各诊断能力在 HCCL 源码中的实现落点。
一、定位前必须掌握的基础认知
在开始故障定位之前，需要先建立两个基础认知。
故障码覆盖大部分常见问题。HCCL 的故障码（EI****/EJ****）覆盖了大部分常见故障场景。如果报错中未包含故障码信息，或故障码为EI9999，则可能是较为少见的故障场景或 HCCL 内部问题，此时需要基于实际的 CANN 日志和代码进行分析；如果仍无法解决，应联系技术支持。
大集群需要定位"根节点"。对于没有清晰首报错的问题（尤其是大集群），需要梳理每个 rank 的行为，通过 rank 之间的依赖关系找到根节点——即真正先出错的 rank，其余 rank 往往只是"被等待方超时"。面对这个难题，HCCL 提供了建链根节点定位能力和集群心跳能力，并会在对应的常见问题章节中给出诊断结果，相关原理可参见 建链失败定位思路 与 集群心跳机制。
此外需要注意该定位方法文档的适用边界：
- 文档中对 HCCL 实现机制的描述，仅用于解释各类故障模式的机理，辅助分析故障现象和定位原因；若运行机制方面的内容与运行机制对应介绍文档不符，请优先参考运行机制文档；
- 部分 CANN 日志示例会随版本更新而调整，用户可重点关注日志中的关键信息，如有较大差异，请以实际日志信息为准；
- 当业务发生 HCCL 异常时，CANN 日志中会有 HCCL 组件的报错日志；若在 CANN 日志中没有发现 HCCL 组件的报错日志，需排查是否有其他组件的报错信息；若无任何报错，则要注意训练脚本本身有无异常、是否存在 core dump 或进程卡住等情况。
二、故障诊断相关环境变量
故障定位依赖的关键环境变量共有四个，它们决定了 HCCL 在异常场景下的上报行为与可观测性。
2.1 HCCL_CONNECT_TIMEOUT 与 HCCL_EXEC_TIMEOUT
HCCL_CONNECT_TIMEOUT 和 HCCL_EXEC_TIMEOUT 分别控制 HCCL 在建链阶段和执行阶段的超时时间。官方建议HCCL_CONNECT_TIMEOUT 配置的时间小于 HCCL_EXEC_TIMEOUT，以保证在复杂场景下能够正确上报首报错信息，从而区分"异常业务进程被阻塞"的原因是本端还是远端。
这一点在定位大集群问题时尤为关键：如果执行超时时间配置得过短，算子执行阶段的超时会先于建链阶段的超时触发，首报错就会指向执行阶段，误导排查方向。
2.2 HCCL_ENTRY_LOG_ENABLE：算子级入参记录
HCCL_ENTRY_LOG_ENABLE 是 HCCL 的算子级入参记录开关（默认关闭）。当集群行为一致性问题无法通过其他手段锁定异常原因时，可以开启此环境变量，记录不同 rank 上的集合通信行为，通过卡间横向比对辅助找到行为差异的引入点。
在源码层面，该开关由环境变量解析模块 ParseEntryLogEnable 解析（仅接受0或1，非法取值会回退默认值并打印告警），解析结果通过 GetExternalInputHcclEnableEntryLog 对外提供。以 AllReduce 为例，AllReduceEntryLog 会在开关打开（或强制记录）时，通过HCCL_RUN_INFO打印形如Entry-HcclAllReduce: tag[...], sendBuf[...], recvBuf[...], count[...], dataType[...], streamId[...], deviceId[...]的入参日志；对于 AllToAllV 等携带变长数组参数的算子，src/common/hccl_common.h 中的 PrintEntryArrayLog 会按 rank 区间分片打印 u64 数组，以规避 512 字节栈缓冲截断。这一实现细节说明：开启该开关后，日志体积会随 rank 数增长，建议在定位行为不一致问题时按需开启。
2.3 HCCL_DEBUG_CONFIG：模块级日志开关
HCCL_DEBUG_CONFIG 是 HCCL 模块级日志开关，进行算子开发调试时可以通过此配置分析算子内部的算法选择、任务编排等日志信息。需要注意的是，该环境变量仅支持以下产品：
- Atlas A3 训练系列产品/Atlas A3 推理系列产品
- Atlas A2 训练系列产品/Atlas A2 推理系列产品
2.4 HCCL_DFS_CONFIG：高级故障探测
HCCL_DFS_CONFIG 是 HCCL 的高级故障探测配置能力，详见环境变量说明，建议保持默认值。
三、HCCL 相关日志说明
HCCL 的日志信息会记录在 CANN 日志中，CANN 的相关日志说明可参考官方《日志参考》文档。HCCL 的日志分布有以下规律：
- debug 目录：HCCL 报错时，会在 CANN 日志的 debug 目录下打印关键的故障信息；同时在使用部分训练框架的业务场景下，HCCL 也会在业务日志中打印关键的报错信息；
- run 目录：HCCL 在 CANN 日志的 run 目录下会默认记录一些关键运行日志，如通信域的初始化与析构（默认打印）、通信算子的下发（需开启
HCCL_ENTRY_LOG_ENABLE）等。
3.1 通信域初始化日志
通信域初始化时会打印如下关键日志：
Entry-HcclGetRootInfo:rootInfo[0x7fffcd65f130], deviceLogicId[0] Entry-HcclCommInitRootInfoConfigInner:ranks[16], rank[0], rootinfo: host ip[127.10.0.1] port[60000] nicDeploy[1] identifier[group_name_0], deviceLogicId[0]各字段含义：
| 字段 | 含义 |
|---|---|
| ranks | 通信域大小 |
| rank | 当前 rank 在通信域内的 rank 编号 |
| rootinfo | root 节点的信息 |
| identifier | 通信域名 |
3.2 通信域析构日志
Entry-HcclCommDestroy: op_base comm destroy begin该日志可作为判断某 rank 是否正常进入通信域销毁流程的依据。
3.3 通信算子下发日志（需开启 HCCL_ENTRY_LOG_ENABLE）
Entry-HcclAllReduce: tag[AllReduce_127.10.0.1%eth1_30000_0_1736576907435382], sendBuf[0x12e7bf550000], recvBuf[0x12e7bf550000], count[531260224], dataType[float32], op[sum], localRank[0], streamId[5],comm[0x331c9c00], deviceLogicId[0]各字段含义：
| 字段 | 含义 |
|---|---|
| tag | 通信算子标识符 |
| sendBuf | 输入数据地址指针 |
| recvBuf | 输出数据地址指针 |
| count | 数据量 |
| dataType | 数据类型 |
| op | reduce 计算类型 |
| localRank | 本端 rank 号 |
| streamId | 通信算子执行流 |
| comm | 通信域指针 |
| deviceLogicId | 通信算子下发的设备逻辑 ID |
横向比对不同 rank 上同一通信域的算子下发日志（tag、count、streamId 是否一致），是定位"集群行为不一致"类问题最常用的手段。
3.4 快速检索关键字：Communicator Key Info 与 LocalRank Key Info
为了方便快速检索和识别通信域及本端的相关信息，HCCL 提供了两个快速检索关键字：Communicator Key Info和LocalRank Key Info。
例如执行grep -r "Communicator Key Info"可得到如下信息：
run/plog/plog-858941_20251210195327204.log:[INFO] HCCL(858941,all_reduce_test):2025-12-10-19:53:28.131.350 [hccl_communicator_attrs.cc:327] [858941][Communicator Key Info]identifier[127.0.0.1%enp_60000_0_1765367607599032] rankSize[8] serverNum[1] moduleNum[1] superPodNum[0] multiModuleDiffDeviceNumMode[0] multiSuperPodDiffServerNumMode[0]通信域关键信息字段：
identifier：通信域名rankSize：通信域大小serverNum：通信域内节点数moduleNum：通信域内模组个数superPodNum：通信域内超节点个数multiModuleDiffDeviceNumMode：是否模组间卡数不一致multiSuperPodDiffServerNumMode：是否超节点间节点数不一致
信息中"1"表示是，"0"表示否。从日志示例可见，该信息由通信属性模块（hccl_communicator_attrs.cc）在通信域建立时打印，一次检索即可拿到该 rank 所处通信域的完整拓扑画像。
例如执行grep -r "LocalRank Key Info"可得到如下信息：
run/plog/plog-858941_20251210195327204.log:[INFO] HCCL(858941,all_reduce_test):2025-12-10-19:53:28.131.357 [hccl_communicator_attrs.cc:330] [858941][LocalRank Key Info]userRank[6] hostIp[127.0.0.1] devicePhyId[6] server[127.0.0.1] deviceIp[0.0.0.0] superPodId[0] useSuperPodMode[0] isStandardCard[0]本端关键信息字段：
userRank：通信域内的 Rank 号hostIp：host 侧 IPdevicePhyId：物理 IDserver：节点信息deviceIp：device 侧 IPsuperPodId：超节点 IDuseSuperPodMode：是否为超节点模式isStandardCard：是否为标卡场景
同样地，"1"表示是，"0"表示否。两个关键字配合使用，可以无需逐个翻日志就确认"这个 rank 属于哪个通信域、在哪个节点上、拓扑形态是否正常"。
3.5 查询环境变量实际生效值
如果想要查询已经配置成功的环境变量，其配置及实际生效值会被打印在 CANN 日志的 run/plog 目录下。
针对 Atlas A3/A2 训练与推理系列产品、Atlas 训练系列、Atlas 推理系列产品，可以通过检索HCCL_ENV关键字查询每个进程的环境变量实际生效值，例如执行：
grep -r "HCCL_ENV" run/plog/plog-xxx.log命令执行后得到类似如下信息（从日志示例看，这些信息由环境变量解析模块externalinput.cc在进程启动初始化阶段统一打印，既包含set by default的默认值，也包含set by environment的用户配置值）：
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.877 [externalinput.cc:598] [1595259][HCCL_ENV] HCCL_CONNECT_TIMEOUT set by default to [120]s [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.882 [externalinput.cc:558] [1595259][HCCL_ENV] HCCL_EXEC_TIMEOUT set by default to [1836]s [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.886 [externalinput.cc:663] [1595259][HCCL_ENV] HCCL_INTRA_PCIE_ENABLE set by default to [1], HCCL_INTRA_ROCE_ENABLE set by default to [0] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.895 [externalinput.cc:833] [1595259][HCCL_ENV] HCCL_WHITELIST_DISABLE set by environment to [0] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.912 [externalinput.cc:880] [1595259][HCCL_ENV] HCCL_IF_IP is not set [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.915 [externalinput.cc:936] [1595259][HCCL_ENV] HCCL_SOCKET_IFNAME set by default to [EmptyString] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.917 [externalinput.cc:903] [1595259][HCCL_ENV] HCCL_SOCKET_FAMILY is not set and is used by default [AF_INET] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.920 [externalinput.cc:865] [1595259][HCCL_ENV] HCCL_IF_BASE_PORT set by default to [60000] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.148 [externalinput.cc:1736] [1595259][HCCL_ENV] HCCL_OP_RETRY_PARAMS is not set, default value MaxCnt is [1], HoldTime is [5000]ms, IntervalTime is [1000]ms [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.180 [externalinput.cc:1800] [1595259][HCCL_ENV] HCCL_DEBUG_CONFIG is not set, debugConfig set by default to 0x0（以上示例为节选，完整列表中还包括HCCL_RDMA_TC、HCCL_RDMA_SL、HCCL_RDMA_TIMEOUT、HCCL_RDMA_RETRY_CNT、HCCL_BUFFSIZE、HCCL_DETERMINISTIC、HCCL_DIAGNOSE_ENABLE、HCCL_ENTRY_LOG_ENABLE、HCCL_INTER_HCCS_DISABLE、HCCL_OP_EXPANSION_MODE、HCCL_RDMA_QPS_PER_CONNECTION、HCCL_MULTI_QP_THRESHOLD、HCCL_OP_RETRY_ENABLE、HCCL_LOGIC_SUPERPOD_ID、HCCL_RDMA_PCIE_DIRECT_POST_NOSTRICT、HCCL_RDMA_QP_PORT_CONFIG_PATH等变量的生效值。）
针对Ascend 950PR/Ascend 950DT，则可通过检索关键字base_config查询当前已设置的环境变量：
[INFO] HCCL(229424,python3.8):2025-12-23-22:31:40.239.170[base_config.cc:33][229424][Init][EnvVarParam]Env config "HCCL_IF_IP" is not set. Default value is used. [INFO] HCCL(229424,python3.8):2025-12-23-22:31:40.239.166[base_config.cc:33][229424][Init][EnvVarParam]Env config "HCCL_CONNECT_TIMEOUT" is parsed.这一步可以确认"你以为配置的环境变量，进程实际是否真的收到了"，对多节点环境配置不一致类问题非常有用。
四、快速定位定界思路
HCCL 故障定位的主流程分为三步。
4.1 第一步：确认是否为 HCCL 相关的异常报错
- HCCL 针对常见的报错场景，会在业务打屏日志中上报错误信息及故障信息。若在业务日志中存在
EI****或EJ****的故障码，则可根据对应的故障信息排查故障，或结合 CANN 日志中的报错信息到对应章节排查；故障码列表见本文 第六节。 - 除了打屏的故障码信息，HCCL 在 CANN 日志中会打印 HCCL 组件的 ERROR 级别日志。因此若 CANN 日志中没有 HCCL 组件的报错日志，需排查是否有其他组件的报错信息；若无任何报错，则注意训练脚本本身有无异常、是否存在 core dump 或进程卡住等其他异常。
4.2 第二步：收集全量 CANN 日志
由于 HCCL 集合通信是通信域下全局的协同行为，某个节点上有 HCCL 异常报错，往往是因为在等待某个对端超时——报错节点未必是根因节点。此时需要结合对端的日志信息一起排查根因。因此，对 HCCL 问题的定位定界需要收集集群下所有节点的 CANN 日志，包括 debug 目录和 run 目录的日志。
4.3 第三步：确认当前报错阶段
HCCL 业务存在三个阶段：通信域初始化、参数面建链和通信算子执行。由于不同阶段使用的硬件资源、通信拓扑和同步方式有明显差异，因此可先确认当前 HCCL 报错所在的阶段，再根据不同阶段找到对应章节做进一步排查。
HCCL 在常见的报错场景增加了多级检索关键字，可以根据报错日志中的关键字快速识别当前报错阶段。多级检索关键字详见 第五节。例如如下日志表明在算子执行阶段发生了超时报错，且当前算子展开方式为 HOST 模式：
[ERROR] HCCL(858209,all_reduce_test):2025-12-10-19:52:32.589.097 [task_exception_handler.cc:27] [858274][TaskExecStage][Timeout][HOST]Task run failed, base information is streamID:[1740], taskID[23], tag[AllReduce_127.0.0.1%enp_60000_0_1765367469951573], AlgType(level 0-1-2):[fullmesh-ring-NHR].注意：多级检索关键字功能仅在 CANN 8.5.0 版本及后续版本支持；对于不支持的版本或没有检索到关键字的场景，可根据其他方法判断当前报错阶段。
除了检索关键字，HCCL 提供了通信域创建接口和通信算子接口，且接口均为同步下发、异步执行，因此也可按以下接口行为场景判断阶段：
- 若业务在调用通信域创建接口失败时，或在报错日志中有
topoinfo、ranktable关键字打印，可参考 通信域初始化阶段 章节进一步排查； - 若业务在调用通信算子接口失败时，或在报错日志中有
transport关键字打印，可参考 参数面建链阶段 章节进一步排查； - 若业务创建通信域接口和通信算子下发均成功，而是在触发流同步时有 HCCL 的算子执行失败，或在报错日志中有
TaskExceptionHandler、FFTS+ run failed、Task run failed关键字打印，可参考 任务下发执行阶段 章节做进一步排查。
除此三个阶段的关键信息外，若业务打屏日志中有明确的错误码信息（如EI0001），可直接根据错误码在故障码表中找到对应章节，并进一步排查。
五、HCCL 多级检索关键字
以下表格汇总了 HCCL 报错日志中的多级检索关键字（一级关键字标识报错阶段，二级关键字标识具体故障场景）：
| 一级关键字 | 二级检索关键字 | 故障场景 |
|---|---|---|
| InitGroupStage | EnvConfig | 通信域初始化阶段环境变量配置异常 |
| RanktableConfig | 通信域初始化阶段 rankTable 文件读取失败 | |
| RanktableCheck | 通信域初始化阶段 rankTable 集群信息校验失败 | |
| RanktableDetect | 通信域初始化阶段集群信息探测失败 | |
| Resource | 通信域初始化节点资源初始化失败 | |
| InitChannelStage | ParameterConflict | 参数面建链阶段参数一致性校验失败 |
| VersionConflict | 参数面建链阶段 HCCL 版本不一致校验失败 | |
| Timeout | 参数面建链阶段超时报错 | |
| TaskExecStage | InvalidArgument | 算子执行阶段入参校验失败 |
| Not Supported | 算子执行阶段不支持场景 | |
| Timeout | 算子执行阶段执行超时 | |
| RunFailed | 算子执行阶段执行失败 | |
| HeartbeatAbnormal | 算子执行阶段发现心跳异常事件 |
六、HCCL 相关故障码
| 故障码 | 故障码说明 |
|---|---|
| EI0001 | 环境变量配置异常 |
| EI0002 | 通信算子执行超时 |
| EI0003 | 集合通信算子入参校验失败，请根据报错信息中的具体入参判断 |
| EI0004 | rankTable 文件加载失败 |
| EI0005 | 参数一致性校验失败 |
| EI0006 | 通信算子参数面建链超时 |
| EI0007 | 资源初始化失败，请根据报错信息判断具体失败原因 |
| EI0008 | HCCL 版本不一致，校验失败，请根据报错信息中的版本信息判断 |
| EI0011 | QP 内存资源申请失败 |
| EI0012 | 算子执行时发生 SDMA 任务异常 |
| EI0013 | 算子执行时发生 ROCE CQE ERROR 异常 |
| EI0014 | 集群信息校验失败 |
| EI0015 | 通信域集群信息协商阶段超时 |
| EI0019 | 通信域创建阶段 server 节点端口绑定失败 或 参数面建链阶段端口绑定失败 |
七、实战排查路径小结
将上述能力组合起来，一次典型的 HCCL 故障排查可以按以下顺序执行：
- 看打屏日志：业务日志中是否出现
EI****/EJ****故障码？有则直接对照 故障码表 跳转对应章节； - 确认报错阶段：在 CANN 日志 debug 目录中检索一级关键字（
InitGroupStage/InitChannelStage/TaskExecStage）或topoinfo、ranktable、transport、Task run failed等特征字，确定是通信域初始化、参数面建链还是算子执行阶段的问题； - 收集全量日志：拉取集群所有节点的 CANN 日志（debug + run 目录），避免只看报错节点；
- 比对环境配置：用
grep -r "HCCL_ENV" run/plog/逐节点核对超时、网络等关键变量的实际生效值，确认HCCL_CONNECT_TIMEOUT小于HCCL_EXEC_TIMEOUT； - 锁定行为差异：对行为不一致类问题，开启 HCCL_ENTRY_LOG_ENABLE 复现，用
grep -r "Communicator Key Info"与grep -r "LocalRank Key Info"确认各 rank 的通信域画像与算子下发入参，横向比对找出第一个出现偏差的 rank； - 深挖根节点：对无清晰首报错的大集群问题，结合建链根节点定位能力与集群心跳机制，沿 rank 依赖关系回溯到首个异常 rank，再依据该 rank 的日志与源码级日志做深入分析。
掌握这套"故障码 → 阶段定界 → 全量日志 → 关键字比对 → 根节点回溯"的流程后，绝大多数 HCCL 通信问题都能在有限步骤内收敛到具体阶段与具体节点，再配合各阶段对应的专题排查文档完成最终定位。
【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
