HCCL 任务下发执行阶段故障定位指南：集群心跳机制与 Task Exception 排查实践-育师

HCCL 任务下发执行阶段故障定位指南：集群心跳机制与 Task Exception 排查实践

【免费下载链接】hccl集合通信库（Huawei Collective Communication Library，简称HCCL）是基于昇腾AI处理器的高性能集合通信库，为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl

导读：本文基于 CANN/HCCL 开源仓库的故障诊断文档，系统讲解集合通信算子任务编排与下发执行阶段的故障定位方法。通信域初始化与参数面建链完成后，HCCL 依赖 notify 同步机制保证对端就绪，一旦个别 rank 进程卡死、退出、网络故障或算子调用不一致，就会引发集群范围的任务执行等待超时。读完本文，你将掌握如何利用**集群心跳机制（HeartbeatAbnormal）**与 **task exception 机制（Task run failed）**两大 DFX 手段定位故障根节点，并学会对 EI0002（算子执行超时）、EI0012（SDMA ERROR）等典型问题进行分级排查与处置。

一、为什么需要"任务下发执行阶段"专项定位

HCCL（Huawei Collective Communication Library）在完成通信域初始化及参数面建链后，会进入通信算子的任务编排与下发阶段。在算子任务编排上，HCCL 在进行数据通信之前引入了notify 同步机制，确保对端已经准备好接收本端数据。

正是这一同步机制的引入，使得一旦出现以下任何一种异常，都会导致大部分 rank 出现执行等待超时：

某个 rank 由于进程卡死或退出，无法完成 notify 的 Post 操作；
节点间网络故障导致同步报文丢失；
各 rank 调用的通信算子不一致（数量、顺序、参数不同）。

遇到此类问题，定位的首要条件是找到故障点位置，即先判断异常发生在哪个节点、属于哪种异常类型，再针对性地开展根因分析。整体定位思路如下图所示。

HCCL 在通信算子任务下发执行阶段提供了以下 DFX（Design For eXcellence，可维测性）机制来辅助问题快速定位：

集群心跳机制：当某个 rank 节点发现异常时，通过心跳机制将异常扩散到集群的每个节点上，因此可以在集群中任意节点的 CANN 日志中检索是否有心跳的异常事件信息打印；
task exception 机制：若未检索到心跳异常事件信息日志，可通过 task exception 报错信息排查是否有集群行为不一致问题。

下文分别对这两套机制的原理、日志特征与排查步骤展开说明。

二、集群心跳机制：单点故障的全集群广播扩散

2.1 机制原理与故障探测能力

HCCL 会基于已有的通信域信息，与邻近的 rank 建立起独立的维测链路，以此提供集群的单点故障广播扩散能力。这样设计的好处是：任意 rank 的 plog 日志中均包含故障根节点信息，用户不需要登录每一台服务器逐一翻查日志。

注：HCCL 会控制维测链路数量和通信数据量，用户无需担心该机制对通信链路造成性能损失。

当前支持的故障探测能力如下表所示：

优先级	异常类型	status（运行日志 run/plog）	ExceptionType（调试日志 debug/plog）	判断标准
1	网络问题	ERROR CQE	Error cqe Occurred	定期轮询 ROCE 驱动重传超次事件，通过 QPN 映射远端 IP
2	进程卡死	STUCK	Stuck Occurred	每隔 1/3 的 HCCL_EXEC_TIMEOUT 时间轮询所有算子的入/出次数，分析是否卡住
3	进程退出	LOST	Heartbeat Lost Occurred	30s 时间内未收到远端的心跳报文

为控制打印数量，当前 Cluster Exception ERROR 日志只打印有效事件的前三个，且优先级为ERROR CQE > STUCK > LOST。若需要确认全量的心跳事件，可在 run 目录日志中检索。

从源码结构看，心跳与任务执行阶段的异常打印逻辑集中在任务执行异常处理器中，例如src目录下task_exception_handler.cc对应的日志（文档日志示例中[task_exception_handler.cc:610]、[task_exception_handler.cc:908]等行号均出自该文件）；超时相关的配置项在 alg_env_config.cc 与 alg_env_config.h 中定义与解析。

2.2 异常事件的集群扩散与日志解读

HCCL 在检测到异常事件后，会在集群中进行信息的扩散转发，并在运行过程中将收到的异常事件打印到 run 日志。

日志格式：

[HeartbeatAbnormal]local rank[IP/ID]：crimer rank[IP/ID] status[4异常事件类型]by informer rank[IP/ID]

各字段含义：

HeartbeatAbnormal：代表心跳异常事件；
local rank：当前节点的信息；
crimer rank：根节点（故障发生源）信息；
status：异常事件类型；
by informer rank：集群故障上报者信息。

用户可结合关键字HeartbeatAbnormal与 status 状态进行检索，日志示例如下：

[INFO] HCCL(686,python):2025-10-23-07:52:59.191.363 [heartbeat.cc:951] [8970][TaskExecStage][HeartbeatAbnormal]local rank [127.10.0.1/1]: crimer rank [127.10.0.2/2] status[LOST] by informer rank [127.10.0.3/3]

上述日志表明：节点127.10.0.3/3发现节点127.10.0.2/2发生 LOST（心跳丢失）事件，并扩散到本端127.10.0.1/1。

2.3 Cluster Exception Location：单点故障原因汇总

如果后续出现算子执行报错，并且调用了 task exception 回调函数通知 HCCL，HCCL 会根据已经收到的异常事件，结合 HCCL_EXEC_TIMEOUT 等超时事件配置，推测出最可能的单点故障原因，打印在 ERROR 日志中。

日志格式：

[TaskExecStage][HeartbeatAbnormal]Cluster Exception Location[IP/ID], Arrival Time:[星期 月 日 时:分:秒 年], Discoverer:[IP/ID], ExceptionType:[异常类型], Possible Reason:可能原因

各字段含义：

[TaskExecStage][HeartbeatAbnormal]：代表集群故障发生在算子执行阶段，为心跳异常事件；
Cluster Exception Location：集群故障发生位置；
Arrival Time：集群故障发生时间；
Discoverer：集群故障发现节点；
ExceptionType：集群故障的异常类型；
Possible Reason：集群故障发生的可能原因。

用户可检索关键字HeartbeatAbnormal，日志示例如下：

[ERROR]HCCL(835695,all_reduce_test):2025-10-23-17:28:06.049.385[task_exception_handler.cc:610][835695][TaskExecStage][HeartbeatAbnormal]Cluster Exception Location[IP/ID]:[127.10.0.1/1], Arrival Time:[Thu Oct 23 17:25:58 2025], Discoverer:[127.10.0.1/2], ExceptionType:[Heartbeat Lost Occurred], Possible Reason:1. Process has exited, 2. Network Disconnected

2.4 进程卡死或对端心跳丢失的典型排查

当 CANN 日志中存在关键字Cluster Exception Location时，可按异常类型进一步区分两种典型场景：

对端心跳丢失（Heartbeat Lost Occurred）：

[ERROR]HCCL(835695,all_reduce_test):2025-10-23-17:28:06.049.385[task_exception_handler.cc:610][835695][TaskExecStage][HeartbeatAbnormal]Cluster Exception Location[IP/ID]:[127.10.0.1/1], Arrival Time:[Thu Oct 23 17:25:58 2025], Discoverer:[127.10.0.1/2], ExceptionType:[Heartbeat Lost Occurred], Possible Reason:1. Process has exited, 2. Network Disconnected

进程卡死（Stuck Occurred）：

[ERROR]HCCL(1219039,all_reduce_test):2025-10-23-21:05:09.859.568[task_exception_handler.cc:610] [1219039][TaskExecStage][HeartbeatAbnormal]Cluster Exception Location[IP/ID]:[127.10.0.1/1], Arrival Time:[Thu Oct 23 21:03:19 2025], ExceptionType:[Stuck Occurred], Possible Reason:1.Host process is stuck, 2.Device task is stuck

排查要点：根据Cluster Exception Location定位异常节点后，结合Possible Reason给出的方向逐项核查：

Heartbeat Lost Occurred：排查异常所在节点在Arrival Time时刻是否已提前退出，或节点间网络异常导致无法连接；
Stuck Occurred：排查异常所在节点的业务进程是否卡死或发生死锁；
Error cqe Occurred：排查异常所在节点是否发生了 CQE error（参见下文 SDMA ERROR 场景）。

2.5 无异常事件时的甄别技巧与注意事项

如果训练/推理任务在 notify 超时前被提前杀掉，或 task exception 机制由于某种原因未及时调用 callback 函数通知 HCCL，HCCL 可能没有打印异常信息。此时用户依然可以通过 run 日志中系统运行过程中的异常事件进行根节点定位，但需要对异常事件进行甄别：

一般可以认为，对于系统卡住时间附近的 LOST / ERROR CQE 事件，即为导致系统停止的原因；
而STUCK 检测时间为（1/3 ~ 2/3）× HCCL_EXEC_TIMEOUT，需要注意该时间窗口；
网络异常和进程退出均有可能同时导致 LOST 和 ERROR CQE 事件，需结合心跳事件的具体情况判断。例如：如果两端 rank 互报对端 LOST，则更倾向于网络链路问题。

如果超时后未伴随异常事件，则有可能为集群行为一致性问题，应优先排查脚本、版本、数据集等因素；如有需要，可以通过开启HCCL_ENTRY_LOG_ENABLE环境变量进行算子级行为跟踪（详见 4.3 节）。

三、task exception 机制：失败任务的信息回溯

3.1 机制原理

HCCL 通信算子的任务编排完成后会下发到 Device 侧异步执行。若此时 HCCL 下发的任务执行失败，Device 侧会通过调用回调函数通知 HCCL 异常 task 信息（stream 和 taskId），HCCL 以此检索下发时的 task 信息，打印失败 task 的详细信息及其所在的算子信息。

针对如下产品，如果要跟踪 task 级信息，需要通过 HCCL_DIAGNOSE_ENABLE 手动开启：

Atlas A3 训练系列产品 / Atlas A3 推理系列产品；
Atlas A2 训练系列产品 / Atlas A2 推理系列产品。

此时 CANN 日志中打印的 task exception 关键日志为"Task run failed" 或 "TaskExecStage"，如下所示：

[ERROR] HCCL(2111667,all_reduce_test):2025-10-24-11:18:29.597.044 [task_exception_handler.cc:908] [2111667][TaskExecStage][Timeout][Host]Task run failed, base information is streamID:[2], taskID[21], tag[AllReduce_127.10.0.1%enp_60000_0_1761275812718970], AlgType(level 0-1-2):[fullmesh-ring-NHR]. [ERROR] HCCL(2111667,all_reduce_test):2025-10-24-11:18:29.597.054 [task_exception_handler.cc:771] [2111667][TaskExecStage][Timeout][Host]Task run failed, groupRank information is group:[127.10.0.1%enp_60000_0_1761275812718970], user define information[], rankSize[4], rankId[2]. [ERROR] HCCL(2111667,all_reduce_test):2025-10-24-11:18:29.597.083 [task_exception_handler.cc:704] [2111667][TaskExecStage][Timeout][Host]Task run failed, opData information is timeStamp:[2025-10-24-11:16:55.490.253], deviceId[2], index[21], count[256], reduceType[sum], src[0x12c0c0013000], dst[0x12c0c0014000], dataType[float32].

3.2 从三段日志中识别算子关键信息

task exception 信息分三段打印，可依次识别出通信算子的关键信息：

base information：HCCL 算子所在的 stream、taskid，以及算子的tag。tag 的命名规则形如AllReduce_通信域名，可根据 tag 识别当前报错的 HCCL 算子；AlgType(level 0-1-2)则给出了当前算法在三个层级上的选择，例如fullmesh-ring-NHR；
groupRank information：通信域名（group）、通信域的大小（rankSize）以及当前卡在通信域内的 rankId；
opData information：当前算子的入参信息，包括所在的 deviceId、该通信域下的第几个算子（index）、数据量（count）、reduce 类型（reduceType）以及输入（src）和输出（dst）的地址。

一般情况下，当前只有两种 task 可能出现失败：

Notify：常见于算子执行阶段等待远端超时；
SDMA：一般在 HCCS 链路异常、多 bit ECC 等场景出现，也有较低概率在远端 core dump 时被触发。

四、典型场景一：算子执行超时（EI0002）

4.1 超时本质：通信双方同步关系失配

一次卡间数据搬运包含前同步、数据传输、尾同步三个阶段（以 SDMA 为例）：

前同步（Post / Wait Ack）：Rank0 读取 Rank1 数据前，需要等待 Rank1 发送 Ack，表示数据已准备完成；
数据传输：Rank0 开始读取 Rank1 数据；
尾同步（Post / Wait DataSignal）：Rank1 等待 Rank0 发送 DataSignal，表示数据已读取完成。

如果 Rank1 未执行 Post Ack，Rank0 的 Wait Ack 任务将一直等待直到超时。因此，算子执行超时的本质是通信双方同步关系失配。

执行超时的常见原因包括：

某个 Rank 未下发通信算子；
各 Rank 下发的通信算子不一致；
数据量、数据类型、算法选择等参数不一致。

4.2 分级排查步骤

发生算子执行超时时，CANN 日志中通常会出现Task run failed和task_exception_handler.cc等关键字，报错日志中的group 字段为通信域名称（例如127.10.0.1%enp_60000_0_1761275812718970），该参数将作用于后续所有排查步骤。

第 1 步：获取通信域内所有 Rank 位置

根据通信域名称检索所有参与 Rank，执行以下命令检索到该通信域所有 rank 所在的位置，再根据 run 日志找到对应的 debug 日志位置：

grep -rn "Entry-HcclCommInit" run/plog | grep "<通信域名称>"

示例展示了通信域大小为ranks[4]以及 rank0~3 的 run 日志位置：

run/plog/plog-2111667_20251024111652406.log:[INFO] HCCL(2111667,all_reduce_test):2025-10-24-11:16:52.725.226 [op_base.cc:1292] [2111668]Entry-HcclCommInitRootInfoInner:ranks[4], rank[3], rootinfo: host ip[127.10.0.1] port[60000] nicDeploy[1] identifier[127.10.0.1%enp_60000_0_1761275812718970], deviceLogicId[3] run/plog/plog-2111665_20251024111652405.log:[INFO] HCCL(2111665,all_reduce_test):2025-10-24-11:16:52.724.374 [op_base.cc:1292] [2111667]Entry-HcclCommInitRootInfoInner:ranks[4], rank[2], rootinfo: host ip[127.10.0.1] port[60000] nicDeploy[1] identifier[127.10.0.1%enp_60000_0_1761275812718970], deviceLogicId[2] run/plog/plog-2111668_20251024111652406.log:[INFO] HCCL(2111668,all_reduce_test):2025-10-24-11:16:52.719.213 [op_base.cc:1292] [2111665]Entry-HcclCommInitRootInfoInner:ranks[4], rank[0], rootinfo: host ip[127.10.0.1] port[60000] nicDeploy[1] identifier[127.10.0.1%enp_60000_0_1761275812718970], deviceLogicId[0] run/plog/plog-2111666_20251024111652405.log:[INFO] HCCL(2111666,all_reduce_test):2025-10-24-11:16:52.719.502 [op_base.cc:1292] [2111666]Entry-HcclCommInitRootInfoInner:ranks[4], rank[1], rootinfo: host ip[127.10.0.1] port[60000] nicDeploy[1] identifier[127.10.0.1%enp_60000_0_1761275812718970], deviceLogicId[1]

第 2 步：判断是否为全量超时

检查通信域内所有 rank 的 debug 日志：所有 rank 都报通信算子执行超时为全量超时，仅部分 rank 报通信算子超时为非全量超时。超时问题定位思路如下图所示。

非全量超时的两种情况：

部分 rank 无异常日志：如果该通信域内的某个 rank 不存在 debug 日志，或者 debug 日志中没有任务 ERROR 信息，说明该 rank未下发通信算子。该场景非 HCCL 问题，需要业务侧排查没有下发通信算子的原因；
部分 rank 存在其他报错：如果该通信域内某个 rank 的 debug 日志有 ERROR 报错，但不是通信算子执行超时的报错，优先分析该 rank 的首报错。通常首报错为根因，其余 rank 的超时属于连带现象，该场景非 HCCL 问题。

全量超时时需进一步分析：

检查通信参数是否一致：检查所有 rank 报错日志中的算子参数是否一致，包括通信算子、count、dataType、reduceType、通信域名称。如果不一致，该场景非 HCCL 问题，需要业务侧进一步分析算子下发不一致的原因。如下案例中，同一个通信域下 rank0 报错在 AllReduce 算子，而 rank1 报错在 Allgather 算子，则需要从业务上进一步排查根因：

# rank0报错日志: tag[AllReduce_127.10.0.1%enp_60000_0_1761275812718970], AlgType(level 0-1-2):[fullmesh-ring-NHR]. [ERROR] HCCL(2111665,all_reduce_test):2025-10-24-11:18:29.499.247 [task_exception_handler.cc:771] [2111665][TaskExecStage][Timeout][Host]Task run failed, groupRank information is group:[127.10.0.1%enp_60000_0_1761275812718970], user define information[], rankSize[4], rankId[0]. [ERROR] HCCL(2111665,all_reduce_test):2025-10-24-11:18:29.499.283 [task_exception_handler.cc:704] [2111665][TaskExecStage][Timeout][Host]Task run failed, opData information is timeStamp:[2025-10-24-11:16:55.493.816], deviceId[0], index[21], count[256], reduceType[sum], src[0x12c0c0013000], dst[0x12c0c0014000], dataType[float32]. # rank1报错日志: tag[AllGather_127.10.0.1%enp_60000_0_1761275812718970], AlgType(level 0-1-2):[fullmesh-ring-NHR]. [ERROR] HCCL(2111666,all_reduce_test):2025-10-24-11:18:29.513.764 [task_exception_handler.cc:771] [2111666][TaskExecStage][Timeout][Host]Task run failed, groupRank information is group:[127.10.0.1%enp_60000_0_1761275812718970], user define information[], rankSize[4], rankId[1]. [ERROR] HCCL(2111666,all_reduce_test):2025-10-24-11:18:29.513.787 [task_exception_handler.cc:704] [2111666][TaskExecStage][Timeout][Host]Task run failed, opData information is timeStamp:[2025-10-24-11:16:55.489.331], deviceId[1], index[21], count[256], src[0x12c0c0013000], dst[0x12c0c0014000], dataType[float32].

检查算子下发时间：如果所有 rank 的算子参数一致，可排查通信域内 rank 之间算子的下发时间差，即比较各 rank 报错日志中的timeStamp。若不同 rank 的算子下发时间间隔超过HCCL_EXEC_TIMEOUT（默认 1836 秒），所有 rank 都会等待超时，需从业务上排查 rank 之间的算子下发时间间隔超过超时时间是否符合预期；若符合预期，则可通过 HCCL_EXEC_TIMEOUT 环境变量指定合适的超时时间。可在 log 日志中检索当前配置的超时时间：
```
grep -r "HCCL_EXEC_TIMEOUT" run/plog
```

4.3 疑难场景：开启算子级行为跟踪

若遇到较难排查的算子执行报错问题，上述排查都满足符合预期时，可开启HCCL_ENTRY_LOG_ENABLE环境变量，再复现一次用例。该环境变量使用后会在每次通信算子下发后，在 log/run/plog 目录下的日志文件中打印一次日志，记录通信算子下发的入参信息。用例执行失败后便可排查每个 rank 上下发的通信算子是否存在异常：

export HCCL_ENTRY_LOG_ENABLE=1

开启后，每次通信算子下发都会打印详细入参：

[INFO] HCCL(3015875,python):2025-03-07-11:43:32.305.623 [hccl_opbase_atrace_info.cc:56][3017221]Entry-HcclAllReduce: tag[AllReduce_127.10.0.1%eth_60000_0_1741318944927847], sendBuf[0x1241d3dcdc00], recvBuf[0x124702f40200], count[10746295], dataType[float32], op[sum], localRank[0], streamId[7],comm[0xfffe380078d0], deviceLogicId[0] [INFO] HCCL(3015875,python):2025-03-07-11:43:32.306.413 [hccl_opbase_atrace_info.cc:56][3017183]Entry-HcclAllReduce: tag[AllReduce_127.10.0.1%eth_60000_0_1741318944927847], sendBuf[0x1244bfffe000], recvBuf[0x1244bfffb400], count[1024], dataType[float32], op[sum], localRank[0], streamId[2],comm[0xfffe380078d0], deviceLogicId[0]

可据此检查：

所有 Rank 是否均已下发通信算子；
算子顺序是否一致；
count、dataType、reduceType 是否一致；
是否存在异常 Stream。

一个典型的由流同步缺失导致的案例：业务在127.10.0.1%eth_60000_0_1741318944927847通信域中下发了两个 AllReduce 算子，但下发在了两条不同的 stream 上（streamId[7]和streamId[2]）。NPU 上多流并发执行，若业务上没有正确实现流执行的同步机制，这两个处于同一通信域下的 AllReduce 算子会并发执行；由于 HCCL 在同一个通信域下的通信算子资源复用，两个 AllReduce 算子并发执行会导致 notify 等资源被错误消耗，从而产生无法预期的报错，如执行超时报错或者精度异常。

五、典型场景二：SDMA ERROR（EI0012）

5.1 问题现象

SDMA 内存拷贝任务异常时，打屏日志中会出现EI0012错误码，关键字为Execution_Error_SDMA，如下所示：

[PID: 3480365] 2025-12-24-14:10:31.094.189 Execution_Error_SDMA(EI0012): SDMA memory copy task exception occurred. Remote rank: [4800]. Base information: [streamID:[351], taskID[5], taskType[Memcpy], tag[], AlgType(level 0-1-2):[null-null-null].]. Task information: [src:[0x12c180000000], dst:[0x12c041800000], size:[0x80], notify id:[0xffffffffffffffff], link type:[HCCS], remote rank:[0]]. Communicator information: [group:[], user define information[], rankSize[0], rankId[0]].

同时，CANN 日志中存在关键字"fftsplus sdma error"，HCCL 侧会同步打印Task run failed的 task exception 信息：

[ERROR] RUNTIME(57096,python3.10):2025-05-12-20:55:44.705.025 [task_info.cc:1170]57288 PrintSdmaErrorInfoForFftsPlusTask:fftsplus task execute failed, dev_id=0, stream_id=50, task_id=21, context_id=18, thread_id=0, err_type=4[fftsplus sdma error] [ERROR] RUNTIME(57096,python3.10):2025-05-12-20:55:44.705.031 [task_info.cc:1270]57288 TaskFailCallBackForFftsPlusTask:fftsplus streamId=50, taskId=21, context_id=18, expandtype=1, rtCode=0x715006c,[fftsplus task exception], psStart=0x0, kernel_name=not found kernel name, binHandle=(nil), binSize=0. [ERROR] HCCL(57096,python3.10):2025-05-12-20:55:44.706.132 [task_exception_handler.cc:947] [57288][TaskExecStage][Timeout][Host]Task run failed, base information is streamID:[32], taskID[21], tag[AllGather_group_name_0], AlgType(level 0-1-2):[fullmesh-ring-H-D]. [ERROR] HCCL(57096,python3.10):2025-05-12-20:55:44.706.140 [task_exception_handler.cc:810] [57288][TaskExecStage][Timeout][Host]Task run failed, groupRank information is group:[group_name_0], user define information[Unspecified], rankSize[8], rankId[0]. [ERROR] HCCL(57096,python3.10):2025-05-12-20:55:44.706.163 [task_exception_handler.cc:737] [57288][TaskExecStage][Timeout][Host]Task run failed, opData information is timeStamp:[2025-05-12-20:54:51.268.778], deviceId[0], index[4], count[3397632], src[0x12c25487ac00], dst[0x12c255000000], dataType[uint8].

5.2 可能原因与核查方法

SDMA ERROR 的本质是在执行 SDMA 内存拷贝任务时发生了页表转换失败，即内存拷贝的输入或输出地址未分配内存、分配的内存小于内存拷贝大小，或分配的内存已被释放。常见的问题根因有以下场景：

通信域提前析构：下发通信算子后，未执行流同步确认通信算子执行完成就析构通信域。由于通信域析构时会释放集合通信的 HCCL Buffer 地址，因此会导致 SDMA 内存拷贝时页表转换失败。可在 CANN 日志的 run 目录下检索通信域销毁的时间：
```
grep -r "Entry-HcclCommDestroy" log/run/plog
```
网络链路故障：Atlas A3 训练系列产品 / Atlas A3 推理系列产品下，网络链路故障也会导致 SDMA ERROR，此时需要检查两端之间的链路状态；
Buffer 与数据量不匹配：调用 HCCL 通信算子时，传入的输入或输出地址实际分配的内存大小小于传入的数据量 Count。

六、两个关键环境变量

6.1 HCCL_EXEC_TIMEOUT：设备间同步等待时间

功能：不同设备进程在分布式训练或推理过程中存在卡间执行任务不一致的场景（如仅特定进程会保存 checkpoint 数据），通过该环境变量可控制设备间执行时同步等待的时间，在该配置时间内各设备进程等待其他设备执行通信同步。

配置示例：

export HCCL_EXEC_TIMEOUT=1800

各产品取值规则（单位均为 s）：

Ascend 950PR/Ascend 950DT：CCU_MS 与 CCU_SCHED 模式下取值范围 [0, 65535]，默认 1836，配置为 0 代表永不超时；AI_CPU 模式下取值范围 [0, 2147483647]，默认 1836；AIV 模式下取值范围 [0, 1091]，默认 1091，支持十毫秒级精度（如 50 毫秒配置为 0.05），超出最大值按 1091 处理；
Atlas A3 训练/推理系列产品：AI_CPU 与 AICPU_CacheDisable 模式下取值范围 [0, 2147483647]，默认 1836；AIV 模式同上，取值范围 [0, 1091]，默认 1091；
Atlas A2 训练/推理系列产品：HOST 与 HOST_TS 模式下取值范围 [0, 2147483647]，默认 1836；AIV 模式同上，默认 1091；
Atlas 训练系列产品：取值范围 (0, 17340]，默认 1836。实际生效的超时时间 = 环境变量取值先整除 68 再乘以 68（小于 68 则按 68s 处理），例如HCCL_EXEC_TIMEOUT=600时实际生效为600÷68×68 = 8×68 = 544s；
Atlas 推理系列产品：同上，取值范围 (0, 17340]，默认 1836，同样按整除 68 的规则对齐。

说明与约束：

在 AIV 模式下，实际生效的超时时间为interval × N × 10⁻³毫秒，其中 interval 为硬件支持的算子超时最短时间间隔（可通过aclrtGetOpTimeoutInterval接口获取，单位 us），N 为 [1, 254] 范围内整数；如果配置的超时时间不等于该值，则向上对齐；
一般情况下用户保持默认值即可；当默认值无法满足设备间执行通信同步的需求时，可通过此环境变量适当增大同步等待时间；
若调用 HCCL C 接口初始化具有特定配置的通信域时，通过HcclCommConfig的hcclExecTimeOut参数配置了设备间执行时的同步等待时间，则以通信域粒度的配置为准。

6.2 HCCL_ENTRY_LOG_ENABLE：算子级行为跟踪

功能：控制是否实时打印通信算子的调用行为日志。

1：实时打印通信算子的调用行为日志，即调用一次通信算子，打印一条运行日志；
0：不打印通信算子的调用行为日志；

默认值为0。该环境变量仅用于集合通信算子的单算子调用场景。开启方式：

export HCCL_ENTRY_LOG_ENABLE=1

开启后即可在日志中看到形如Entry-HcclAllReduce: tag[...], sendBuf[...], recvBuf[...], count[...], dataType[...], op[...], localRank[...], streamId[...]的入参记录，用于核查各 rank 的算子下发情况（详见 4.3 节）。

七、定位流程速查与文档索引

推荐定位路径：

在集群任意节点的 CANN 日志中检索HeartbeatAbnormal：
- 命中 → 结合Cluster Exception Location定位根节点与异常类型，按 2.4 节方法排查；
- 未命中 → 进入第 2 步；
检索Task run failed/TaskExecStage：
- 命中 → 按 EI0002（Notify 超时）或 EI0012（SDMA ERROR）流程排查；
- 未命中 → 怀疑集群行为不一致，检查脚本、版本、数据集，必要时开启HCCL_ENTRY_LOG_ENABLE复现跟踪。

仓库文档速查：

定位思路（EI0002）：本文主体文档，任务下发执行阶段报错定位总览；
集群心跳机制：心跳机制的故障探测能力与日志格式说明；
进程卡死或对端心跳丢失：Heartbeat Lost / Stuck 场景示例；
task exception 机制：task exception 机制总览；
task exception 机制定位思路：Task run failed日志解析；
算子执行超时（EI0002）：全量/非全量超时分级排查；
SDMA ERROR（EI0012）：SDMA 页表转换失败场景排查；
HCCL_EXEC_TIMEOUT 与 HCCL_ENTRY_LOG_ENABLE：两个关键环境变量的完整取值说明；
HCCL_DIAGNOSE_ENABLE：task 级信息跟踪的开关配置。

源码佐证：任务执行超时相关配置的解析与默认值定义位于 alg_env_config.cc 与 alg_env_config.h；算法模板中对超时与同步的运用可进一步查阅 alg_template_base.cc 等模板实现。本文涉及的日志行号（如task_exception_handler.cc:610/704/737/771/810/908/947、heartbeat.cc:951）均对应 HCCL 运行时日志打印代码，可在实际报错中作为检索关键字使用。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考