昇腾社区首页
中文
注册
开发者
下载
支持
积分兑换 NEW

应知应会

在故障定位之前，请确保您已熟悉HCCL相关基本概念及故障定位辅助功能。

对于HCCL来说，故障码会涵盖大部分常见问题，如果报错中未包含故障码信息，或故障码信息为EI9999，可能为较为少见的故障场景或HCCL内部问题，请基于实际的CANN日志和代码进行分析，如果无法解决请联系技术支持。

对于没有清晰首报错的问题，大集群故障定位时，需要梳理每个rank的行为，通过rank之间的依赖关系找到根节点。面对这个难题，HCCL提供了建链根节点定位能力和集群心跳能力，并会在常见问题中给出诊断结果，相关原理请参见建链失败定位思路、集群心跳机制 。

本文档适用场景如下：

  • 本文档对HCCL的实现机制的描述，仅用于解释各类故障模式机理，辅助分析故障现象和定位原因。如果在运行机制方面的内容和该机制相关介绍文档不符，请优先参考运行机制对应文档。
  • 本文档中的部分CANN日志示例随着版本更新，内容会有所调整，用户可重点关注日志中的关键信息，如有较大的差异，请以实际的日志信息为准。
  • 当业务发生HCCL异常时，在CANN日志中会有HCCL组件的报错日志信息，若在CANN日志中没有发现HCCL组件的报错日志，需排查是否有其他组件的报错信息，若无报错，请注意训练脚本本身有无异常、是否存在core dump或进程卡住等异常情况。

故障诊断相关环境变量

  • HCCL_CONNECT_TIMEOUT、HCCL_EXEC_TIMEOUT

    HCCL在建链阶段和执行阶段的超时时间，建议HCCL_CONNECT_TIMEOUT配置的时间小于HCCL_EXEC_TIMEOUT配置的时间，以保证复杂场景下能够正确的上报首报错信息，以区分异常业务进程被阻塞的原因是本端还是远端。

  • HCCL_ENTRY_LOG_ENABLE

    HCCL算子级入参记录开关，如果集群行为一致性问题无法通过其他手段锁定异常原因时，可以使能此环境变量，记录不同rank上的集合通信行为，通过卡间横向比对辅助找到行为差异引入点。

  • HCCL_DEBUG_CONFIG

    HCCL模块级日志开关，进行算子开发调试时可以通过此配置分析算子内部的算法选择、任务编排等日志信息。

  • HCCL_DFS_CONFIG

    HCCL高级故障探测配置能力，详见环境变量说明，建议使用默认值。

HCCL相关日志说明

HCCL的日志信息会记录在CANN日志中，CANN的相关日志说明请参考《日志参考》。

  • 当HCCL报错时会在CANN日志的debug目录下打印关键的故障信息；同时在使用部分训练框架的业务场景下，HCCL也会在业务的日志中打印关键的报错信息；
  • HCCL在CANN日志的run目录下会默认记录一些关键运行日志，如通信域的初始化与析构（默认打印）、通信算子的下发（需开启HCCL_ENTRY_LOG_ENABLE环境变量）等，关键日志示例如下：
    • 通信域初始化：
      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：通信域名。
    • 通信域析构：
      Entry-HcclCommDestroy: op_base comm destroy begin
    • 通信算子下发（需开启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。
    • 为了方便快速检索和识别通信域及本端的相关信息，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”表示否。

      • 例如执行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侧Ip]、devicePhyId[物理Id]、server[节点信息]、deviceIp[device侧Ip]、superPodId[超节点Id]、useSuperPodMode[是否为超节点模式]、isStandardCard[是否为标卡场景]，信息中，“1”表示是，“0”表示否。

    • 如果想要查询已经配置成功的环境变量，其配置及实际生效值会被打印在CANN日志的run/plog目录下。
      针对Atlas 推理系列产品、Atlas 训练系列产品、Atlas A2 训练系列产品/Atlas A2 推理系列产品、Atlas A3 训练系列产品/Atlas A3 推理系列产品，可以通过检索"HCCL_ENV"的关键字查询每个进程的环境变量实际生效值，例如执行：grep -r "HCCL_ENV" run/plog/plog-xxx.log，得到以下信息：
      [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.890 [externalinput.cc:742] [1595259][HCCL_ENV] environmental variable PROFILING_MODE and GE profiling option is not set, default: false
[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.881.988 [externalinput.cc:1170] [1595259][HCCL_ENV] HCCL_RDMA_TC set by default to [132]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.991 [externalinput.cc:1205] [1595259][HCCL_ENV] HCCL_RDMA_SL set by default to [4]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.058 [externalinput.cc:1250] [1595259][HCCL_ENV] HCCL_RDMA_TIMEOUT set by default to [20]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.064 [externalinput.cc:1284] [1595259][HCCL_ENV] HCCL_RDMA_RETRY_CNT set by default to [7]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.069 [externalinput.cc:1370] [1595259][HCCL_ENV] HCCL_BUFFSIZE set by environment to [1]M
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.072 [externalinput.cc:621] [1595259][HCCL_ENV] HCCL_DETERMINISTIC set by default to [false]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.074 [externalinput.cc:1395] [1595259][HCCL_ENV] HCCL_DIAGNOSE_ENABLE set by default to [0]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.077 [externalinput.cc:1484] [1595259][HCCL_ENV] HCCL_ENTRY_LOG_ENABLE set by default to [0]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.081 [externalinput.cc:1505] [1595259][HCCL_ENV] HCCL_INTER_HCCS_DISABLE is not set, default value is FALSE.
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.090 [externalinput.cc:1569] [1595259][HCCL_ENV] environmental variable HCCL_OP_EXPANSION_MODE is [HOST], aicpuUnfold[0], aivMode[0], enableFfts[1]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.096 [externalinput.cc:1420] [1595259][HCCL_ENV] HCCL_RDMA_QPS_PER_CONNECTION is set to default value [1]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.099 [externalinput.cc:1454] [1595259][HCCL_ENV] HCCL_MULTI_QP_THRESHOLD is set to default value [512]KB
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.116 [externalinput.cc:1724] [1595259][HCCL_ENV][ParseRetryEnable] HCCL_OP_RETRY_ENABLE set by environment variable to [L0:0,L1:0,L2:0].
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.120 [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.123 [externalinput.cc:1778] [1595259][HCCL_ENV] HCCL_LOGIC_SUPERPOD_ID set by environment to [0]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.125 [externalinput.cc:525] [1595259][HCCL_ENV] HCCL_RDMA_PCIE_DIRECT_POST_NOSTRICT set by default to [EmptyString], rdmaFastPost is [0]
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.128 [externalinput.cc:791] [1595259][HCCL_ENV][Parse][MultiQpSrcPortConfigPath]environmental variable HCCL_RDMA_QP_PORT_CONFIG_PATH is empty
[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.131 [externalinput.cc:1800] [1595259][HCCL_ENV] HCCL_DEBUG_CONFIG is not set, debugConfig set by default to 0x0
父主题： 定位思路