Hang 检测是面向大规模分布式训练场景的任务健康诊断能力，可在任务运行期间自动巡检、实时感知异常挂起，并通过函数调用栈分析快速定位性能瓶颈与故障根因。面向算法工程师与任务运维人员，该功能可大幅降低分布式训练 Hang 问题排查成本，提升任务运行效率与稳定性。

功能介绍

• 支持多维度hang 检测：在基于日志迭代间隔判断是否hang 的基础上，支持结合训练进程调用栈、进程 IO 等多维度的指标，综合判断，提升hang 检测的准确性

• hang 分析能力：

  • 无侵入采集：无需修改业务代码，无需修改用户代码，自动采集训练进程、Dataloader 子进程调用栈，支持手动/自动触发指标的采集
  • 可视化分析定位：自动生成函数聚合火焰图，支持按进程类型筛选。通过多 Rank 聚合函数火焰图对比分析，快速锁定异常节点、异常函数

使用限制

1. 当前仅支持 Pytorch 框架的训练任务

使用步骤

开启 hang 检测

1. 登录百舸AI计算平台AIHC控制台。
2. 进入分布式训练列表页面，点击创建任务。
3. 资源配置模块，训练框架选择 Pytorch
4. 容错与诊断模块，开启自动容错，在高级设置中，开启 hang检测：

• 基于日志的检测，可以自定义日志间隔的阈值
• 高级诊断，在日志检测达到阈值后，平台会额外通过函数调用栈与进程IO监控指标，多维度判断任务状态，提高 hang 检测的准确度

任务启动运行后，会实时检测 hang。

hang 分析

在任务详情页面，点击进入 Hang 解析 标签页，即可查看训练任务hang 的分析报告

1. 若您在创建任务时已开启 Hang 检测，系统检测到任务挂起后，将自动触发指标采集，并生成聚合函数栈火焰图。
2. 同时本功能支持手动触发采集，无需提前开启 Hang 检测，当你发现任务 Hang 时可手动发起诊断分析

数据采集完成后，会自动生成聚合函数栈火焰图，支持下载。

视图使用说明

1. 火焰图文件都合并了所有rank的数据。

2. 栈帧格式：

   Plain Text 复制

   1栈帧格式：
   2<ThreadName>@<FuncName>@<CodePath>@<Ranks In There>|<Ranks Not In There>

   • ThreadName：线程名，采集不到会显示unknown
   • FuncName：函数名，如果获取不到会显示unknown
   • CodePath：函数执行路径
   • Ranks In There：哪些rank的调用栈执行到了这个位置
   • Ranks Not In There：哪些rank的调用栈没有执行到这个位置

3. 为了提升视图效果，Ranks In There 和 Ranks Not In There 的rank列表呈现逻辑为：

   • 压缩连续的rank号，格式为：开始rank号-结束rank号。例如0-5代表 [rank-0,rank-1,rank-2,rank-3,rank-4]
   • 隔离非连续的rank号，格式为：第1组rank/第2组rank。例如60-62/65代表[rank-60,rank-61,rank-62,rank-65]

4. 火焰图示例图如下：

   • rank-60的主线程（MainThread)执行到了/opt/conda/.../linear.py:116处的forward函数
   • 0-59号rank和61-143号rank的主线程（Main Thread）没有执行到/opt/conda/.../linear.py:116处的forward函数

分析逻辑

先看整体：所有 Rank 的调用栈是否一致

• 一致 → 全局 Hang（代码 / 通信问题）
• 不一致 → 局部节点异常（单 Rank / 单节点先 Hang）

再看栈顶函数

• 卡在 业务 / 数据加载 / IO / 计算函数 → 应用层代码问题
• 卡在 通信函数（all_reduce 等） → 通信等待或全局阻塞

最后定位异常 Rank

• 栈与其他 Rank 明显不同的 → 故障节点
• 其他 Rank 都在等它通信 → 根因就是这个异常 Rank

排查实践

Case1 局部hang

1. 场景描述

节点（某个rank或pod内的一组rank）由于发生了非通信问题先hang，进而扩散，导致全局hang。

2. 分析目标

分析出异常节点，具体是哪一个rank或哪一组rank。

3. 分析逻辑

基本原理：异常rank的调用栈与其它rank的调用栈理论存在明显差异。因为异常rank是hang在了非通信问题，所以异常rank的调用栈理论停滞在非通信函数。而其它rank的hang是由于等待同异常rank通信，所以其它rank调用栈理论停滞在通信函数。

4. 经典案例

规模为8机64卡的训练任务，判断处于 hang状态

• 查看python栈聚合函数火焰图，观察到栈顶函数，机器A的所Rank（rank40-47）调用栈停滞函数位置明显与其它rank存在差异
• 进入该训练实例，采集训练进程，发现Process 23x is disk-sleep，磁盘处于休眠状态，I/O 阻塞导致了训练进程 hang 住。

可以结合节点的监控，进一步排查磁盘的IO 性能

case2 全局hang

1. 场景描述

用户代码编写问题导致的全局hang

---

2. 分析目标

分析出异常函数

3. 分析逻辑

由于是代码问题导致的全局hang，理论上所有rank调用栈都停滞在相同的函数。如果该函数为非通信函数（例如dataloader相关），可以推断是由用户代码导致

4. 经典案例

10机分布式训练任务，判断处于 hang 状态

• 查看Python火焰图，明显看到所有rank的调用栈顶都停滞在相同的函数。该函数为dataloader相关函数，因此怀疑dataloader代码编写存在问题。需要进一步排查dataloader的函数