一、命令树总览
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） |