本文介绍 HyperTrace 训练效能保障套件各子命令的详细参数、输出文件以及环境变量的配置。
命令树总览
hyper-trace├── run 全栈 eBPF 追踪采集├── preflight 训练前环境预检，通过后自动拉起训练├── setup GPU Tracer 安装（CUPTI / ROCtracer）├── collect 节点配置诊断（GPU/RDMA/System）├── gpu NVIDIA GPU 工具集│ └── health GPU 健康检查├── dcu DCU 工具集│ └── health DCU 健康检查├── report 从 trace JSON 生成分析报告├── pytrace Python 函数栈轻量采样└── init 生成配置文件（交互式 / 默认）
输出文件参考
路径 | 说明 |
/tmp/ebpf-trace/<timestamp>/ | 采集输出根目录 |
trace_output.json | Chrome Trace 格式（Perfetto UI 可直接加载） |
trace_report.html | 13 维度交互式 HTML 报告 |
/opt/ebpf_tracer/ | GPU Tracer 默认安装目录 |
/opt/ebpf_tracer/activate.sh | 环境变量激活脚本 |
/tmp/hyper-trace-preflight/ | preflight 日志默认目录 |
hyper-trace run 全栈追踪采集
sudo hyper-trace run [flags]
常用示例：
# 默认全探针，采集时间 10 秒sudo hyper-trace run -t 10# 仅 Python 栈 + GPUsudo hyper-trace run --pystack --gpu -t 10# 指定 PIDsudo hyper-trace run -p 12345,12346 -t 10# 采集后自动生成报告sudo hyper-trace run -t 10 --report
全栈采集的详细参数如下：
参数 | 说明 | 默认行为 |
-t, --duration | 采集时长（秒） | 10 (s) |
-c, --config | 配置文件路径（JSON） | - |
-p, --pid | 指定 PID（逗号分隔，覆盖自动检测） | 采集 GPU 上所有进程 |
-o, --output | 输出文件名 | 输出到： /tmp/hyper-trace/<timestamp>/ |
--output-mode | full（完整 Chrome Trace，~GB） detect（聚合统计，~KB） hybrid（统计+采样事件） | full 模式 |
--cpu | CPU on/off 调度追踪 | 关闭 |
--gpu | GPU Kernel profiling（CUPTI/ROCtracer） | 关闭 |
--cuda-api | CUDA/HIP API uprobe 追踪 | 关闭 |
--pystack | Python 函数栈（USDT 优先，自动回退 uprobe） | 开启 |
--pystack-hz | Python 栈采样频率 | 200 Hz |
--gc | Python GC 追踪 | 关闭 |
hyper-trace preflight 训练前环境预检
hyper-trace preflight [flags] -- <command> [args...]
常用示例：
# 显示调用 preflighthyper-trace preflight -- torchrun --nproc_per_node=8 train.py# 隐式调用 preflight，与显式调用无差别hyper-trace python train.py
参数 | 说明 | 默认行为 |
--log-dir | 本地日志目录 | 输出到： /tmp/hyper-trace-preflight |
--timeout | 多机节点发现汇聚超时秒数 | 超时时间为：120s |
--skip-health | 跳过健康检测 | 不跳过 |
--skip-collect | 跳过标准化/基线检测 | 不跳过 |
--skip-consistency | 跳过集群一致性检测 | 不跳过 |
--batch_detect | 仅运行检测，不拉起训练命令；失败退出码 1 | 以拉起训练命令的形式执行 |
hyper-trace collect 节点配置诊断及一致性检测
# 本地表格输出sudo hyper-trace collect# JSON 输出sudo hyper-trace collect -o json# 打印 baseline 标准sudo hyper-trace collect --baseline# 多节点集群采集sudo hyper-trace collect -f hosts.txt
hyper-trace gpu health NVIDIA GPU 健康检查
# 本地节点检查hyper-trace gpu health# JSON 输出hyper-trace gpu health --json# 集群批量检查hyper-trace gpu health -f hosts.txt
数据来源：
nvidia-smi -q（温度、功耗、ECC、PCIe、时钟）、dmesg（NVRM/Xid 错误）、/dev/nvidia*（驱动就绪）。hyper-trace dcu health DCU 健康检查
# 本地节点检查hyper-trace dcu health# JSON 输出hyper-trace dcu health -o json# 集群批量检查hyper-trace dcu health -f hosts.txt
数据来源：
hy-smi（温度、功耗、显存、时钟、PCIe 链路）、dmesg（Hygon/XCD 错误码）、/dev/kfd + /dev/dri/renderD*（驱动就绪）、DTK-ROCm 版本信息。关键环境变量参考
环境变量名称 | 功能 |
CUPTI_TRACER_AUTOSTART | CUPTI tracer 自动启动开关 |
HYPER_TRACE_PREFLIGHT_MODE | preflight 模式：strict（默认）/ warn |
HYPER_TRACE_PREFLIGHT_HEALTH | preflight 健康检测开关：on / off（默认 off） |
HYPER_TRACE_PREFLIGHT_COLLECT | preflight 基线检测开关：on / off（默认 off） |
HYPER_TRACE_PREFLIGHT_OCCUPANCY | preflight 占用检测开关：on / off（默认 on） |
HYPER_TRACE_PREFLIGHT_CONSISTENCY | preflight 集群一致性检测开关（默认 on） |
