安装相关
运行时报 /sys/kernel/btf/vmlinux 不存在？
确认内核是否启用 BTF：
cat /boot/config-$(uname -r) | grep CONFIG_DEBUG_INFO_BTF
若输出
CONFIG_DEBUG_INFO_BTF=y 但文件仍不存在，检查 debugfs 是否挂载：mount -t debugfs none /sys/kernel/debugls /sys/kernel/btf/vmlinux
若输出为 `is not set` 或无此配置项，说明内核编译时未开启 BTF，需升级到支持 BTF 的内核（5.4+）。
采集相关
执行 run 时提示 no GPU processes found？
确认训练进程是否有 GPU 活动，必要时手动指定 PID。
# NVIDIA 环境：确认训练进程是否有 GPU 活动nvidia-smi --query-compute-apps=pid,process_name --format=csv# DCU 环境/opt/hyhal/bin/hy-smi --showpids# 手动指定 PIDsudo hyper-trace run -p <pid> -t 10
训练进程没有 CUPTI tracer 激活日志？
# 检查环境变量echo $CUDA_INJECTION64_PATH# 手动激活hyper-trace setupsource /opt/ebpf_tracer/activate.sh# 确认 .so 文件存在ls -la /opt/ebpf_tracer/libcupti_tracer.so
DCU 训练进程没有 ROCtracer 激活日志？
# 检查 LD_PRELOAD 是否包含 roctracer_wrapper.soecho $LD_PRELOAD# 手动激活hyper-trace setupsource /opt/ebpf_tracer/activate.sh# 确认 .so 文件存在（需 --dcu setup）ls -la /opt/ebpf_tracer/librocm_tracer.so
Python 函数栈采集为空？
# 检查 USDT 探针是否可用readelf -n /proc/<pid>/exe | grep function__entry# 无输出时会回退到 uprobe 模式（自动）# 确认已启用 --pystacksudo hyper-trace run --pystack -t 10
预检相关
preflight 报 cluster consistency FAIL？
rank 0 会汇聚所有节点的 OS/内核/驱动/VBIOS 信息到
<log-dir>/cluster/ 目录，查看各节点 preflight.log 找出不一致字段，对齐配置后重新运行。preflight 在多节点场景下超时（节点发现阶段卡住）？
检查各节点之间
<master_port> + 200 的 TCP 端口是否可达（防火墙/安全组）。也可增大超时：HYPER_TRACE_PREFLIGHT_TIMEOUT=300 hyper-trace ...
HyperTrace 与常见工具的功能对比
对比项 | 采集内容 | Nsight System | Torch-Profiler | HyperTrace |
预检测 | -- | 不支持 | 不支持 | 支持 |
随时诊断 | -- | 不支持 | 不支持 | 支持 |
零代码入侵 | -- | 支持 | 不支持 | 支持 |
Python 应用层 | Python 函数调用、训练 step 耗时 | 不支持 | 支持 | 支持 |
框架层 | PyTorch 算子执行 | 不支持 | 支持 | 支持 |
GPU 计算层 | kernel 执行时间、类型分布 | 支持 | 支持 | 支持 |
