这篇面向已安装 HyperTrace 训练效能保障套件工具的用户，介绍常见训练任务的接入和信息采集方式。
一、场景一：训练前环境标准化预检
适用于多机分布式训练启动前，需要确保所有节点 GPU 就绪、配置一致且无僵尸进程的场景。
二、使用方式
在每个训练节点执行同一条命令，preflight 自动完成预检并在通过后拉起训练：
# 隐式形式（推荐）hyper-trace torchrun –nproc_per_node=8 –nnodes=4 –node_rank=0 –master_addr=10.0.0.1 train.py# 显式形式hyper-trace preflight — torchrun –nproc_per_node=8 train.py
三、行为模式
通过设置环境变量 HYPER_TRACE_PREFLIGHT_MODE 可以选择标准化预检模式：
·strict 模式（默认）：任意节点 FAIL 时，rank 0 广播 no-go，所有节点退出非零状态，训练不启动。
·warn 模式（HYPER_TRACE_PREFLIGHT_MODE=warn）：告警但始终拉起训练命令。
四、场景二：GPU 训练全栈性能分析
适用于需要分析单机多卡训练任务中 Python 层、CUDA/HIP API 层和 GPU Kernel 层性能关联的场景。
五、使用方式
训练启动前，通过 hyper-trace setup 命令完成环境注入，或者通过 preflight 模式启动训练任务。
# 场景一：通过 hyper-trace setup 功能完成环境注入，然后启动训练进程hyper-trace setupbash start_train.sh# 场景二：通过环境变量开启训练检测注入，然后通过 preflight 模式启动训练进程export HYPER_TRACE_PREFLIGHT_SETUP=onhyper-trace bash start_train.sh
新开启一个终端窗口，然后调用 hyper-trace 进行性能数据采集：
# 全栈式采集 10 秒，完成后生成报告sudo hyper-trace run -t 10 –report# 只采集 Python 函数栈 + GPU Kernelsudo hyper-trace run –pystack –gpu -t 10
采集完成后，按以下方式分析结果，结果文件输出在/tmp/hyper-trace/<timestamp>/目录下：
·打开 trace_report.html，重点查看：GPU 利用率、通信和计算占比、Python 函数热点、GPU 算子热点。
·将 trace_output.json 导入 Perfetto UI，在时序图中找出高耗时 Kernel，定位 Python 函数与 GPU 执行的完整调用链路。