OAM-Tools 功能运行示例：asys、msaicerr、msprof 三组件从安装到跑通的验证实践
【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools
完成 OAM-Tools 的编译与安装后，如何快速验证工具真的能在自己的昇腾环境中跑起来？本文基于仓库examples/目录的开箱即用样例，给出三件事：加载环境变量的正确姿势、一键运行脚本（deploy.sh）的用法与内部逻辑、以及 asys / msaicerr / msprof 三个组件各自最核心的验证命令。读完后你可以直接复制命令在真实环境中完成工具功能验证，并理解每条命令背后对应的入口文件与子命令实现。
一、环境准备：加载 CANN 环境变量是运行示例的前提
所有示例脚本都依赖 CANN 的环境变量。完成安装后，工具会被释放到 CANN 安装目录下的tools/子目录（root 用户默认在/usr/local/Ascend/cann/tools/）。运行示例前请先加载环境变量：
# root 用户默认路径；非 root 用户将 /usr/local 替换为 ${HOME} source /usr/local/Ascend/cann/set_env.sh # 指定路径安装时：source ${install_path}/cann/set_env.sh执行上方命令后，${ASCEND_HOME_PATH}即为 CANN 安装目录：
- root 用户默认：
/usr/local/Ascend/cann - 非 root 用户默认：
${HOME}/Ascend/cann - 指定路径安装：
${install_path}/cann
这一前提在源码中也有直接体现。msaicerr 入口 msaicerr.py 的main()在解析参数前会先检查ASCEND_OPP_PATH：
ascend_opp_path = os.environ.get("ASCEND_OPP_PATH") if not ascend_opp_path: utils.print_error_log("Environment variable not set after the CANN software is installed.") return Constant.MS_AICERR_INVALID_PATH_ERROR也就是说，如果跳过source set_env.sh直接运行msaicerr.py，会因找不到 CANN 环境变量而直接报错退出——这正是各示例脚本先加载环境再执行工具的原因。
二、一键运行脚本：deploy.sh 与三个组件的 run.sh
examples/目录下为各场景预置了可直接执行的脚本，加载环境变量后即可运行：
| 脚本 | 说明 |
|---|---|
| asys/run.sh | 使用 asys 基础命令体检 device 健康状态，入门首选 |
| msaicerr/run.sh | 运行内置 sample 算子检测软硬件环境是否具备 msaicerr 运行条件，装完即跑 |
| msprof/run.sh | 采集 5 秒系统级 CPU/内存性能数据，装完即跑 |
| deploy.sh | 依次执行上述三个脚本，一键跑通全部样例 |
# 一键运行全部样例 bash deploy.sh # 或单独运行某个组件的样例 bash asys/run.sh2.1 deploy.sh：依次串联三个组件
从 deploy.sh 的源码看，它的逻辑非常直接：开头set -e保证任一脚本失败即整体退出，随后按顺序执行三个子脚本：
set -e SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cd "$SCRIPT_DIR" bash ./asys/run.sh bash ./msaicerr/run.sh bash ./msprof/run.sh因此deploy.sh的通过与否可以直接作为"整套 OAM-Tools 在当台机器上可用"的快速判据。
2.2 asys/run.sh：一条命令体检 device
asys/run.sh 的全部内容就是一条asys health（配合set -e）。health 子命令对应 cmd_parser.py 中Command.HEALTH的定义："Diagnoses the health status of the device."，仅接受Arg.DEVICE参数。
2.3 msaicerr/run.sh：内置 sample 算子做环境自检
msaicerr/run.sh 展示了示例脚本定位 CANN 根目录并加载环境的完整模式：
CANN_ROOT="${ASCEND_INSTALL_PATH:-${ASCEND_HOME_PATH:-/usr/local/Ascend/cann}}" SETENV="$CANN_ROOT/bin/setenv.bash" # shellcheck source=/dev/null [ -f "$SETENV" ] && source "$SETENV" python3 "$CANN_ROOT/tools/msaicerr/msaicerr.py" -e脚本优先使用ASCEND_INSTALL_PATH，回退到ASCEND_HOME_PATH，再回退到默认路径/usr/local/Ascend/cann；随后调用msaicerr.py -e（不显式指定-dev时默认使用 0 号 device）运行内置 sample 算子，验证软硬件环境是否满足 msaicerr 的运行条件。这与源码中-e, --env参数的 help 一致："Check the environment when running the built-in sample operator."（见 msaicerr.py）。
2.4 msprof/run.sh：采集 5 秒 CPU/内存数据
msprof/run.sh 在环境定位逻辑与 msaicerr 相同的基础上，实际执行：
OUTPUT_DIR="./msprof_output" mkdir -p "$OUTPUT_DIR" "$CANN_ROOT/tools/profiler/bin/msprof" --output="$OUTPUT_DIR" --host-sys-usage=cpu,mem --sys-period=5即调用安装目录下的msprof命令，采集 5 秒（--sys-period=5）的 Host 侧 CPU 与内存系统数据（--host-sys-usage=cpu,mem），输出到当前目录的./msprof_output。脚本自带set -e，若 msprof 不可用或采集失败会立即报错退出。
三、asys（故障信息收集与诊断）：两种调用方式与子命令
src/asys/目录下同时存在 asys.py 和指向它的软链接asys（src/asys/asys -> ./asys.py），CMake 通过install(DIRECTORY ${ASYS_DIR} ...)将整个目录原样拷贝，软链接也会保留。因此安装后两种调用都能直接用：
# 形式一：显式 python3 调用 .py python3 ${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys.py -h # 形式二：直接调用软链接 asys（asys.py 自带 #!/usr/bin/env python3 shebang） ${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys -hasys 的子命令定义在 cmd_parser.py 的Command枚举中，包含info / health / collect / launch / diagnose / analyze / config / profiling八个子命令，各自的能力与参数组合可以对照源码确认：
| 子命令 | 能力（来自源码 KEY_HELP） | 支持的参数 |
|---|---|---|
info | Collects the software and hardware information of the host and device | -r（info 运行模式）、-d（device 编号） |
health | Diagnoses the health status of the device | -d（device 编号） |
collect | 采集环境中已有运维调试信息，或实时导出堆栈 | task_dir、--output、--tar、-r、--remote、--all、--quiet、--timeout |
launch | 执行任务脚本并在运行期间采集运维信息 | 位置参数task、--output、--tar |
diagnose | 诊断 device 硬件状态（component、stress_detect、hbm_detect、cpu_detect、aicore_stl_detect；仅支持 910B / 910_93 / 950 / 960） | -r、-d、--timeout、--output |
analyze | 解析 trace、coredump、coretrace、stackcore、aicore_error 与 ub 信息 | -r、-d、-f、-p、--exe_file、--core_file、-s等 |
config | 获取或恢复配置信息 | --get、-d、--restore、--stress_detect |
profiling | 采集 device 的性能数据 | -d、-r、--output、--period、--aic_metrics |
在环境变量加载生效后，可以直接以 asys 调用以下最常用命令：
# 采集主机与 device 的软硬件信息（不依赖待诊断任务，通常作为环境自检） asys info -r="status" -d=0 # 体检 device 健康状态 asys health # 采集环境中已存在的运维信息并打包到指定输出目录 asys collect --output <output_dir>其中collect的-r参数取值stacktrace时必须与--remote、--all配合使用（向指定进程发送信号生成 stackcore 文件），--timeout取值范围为 [1, 60] 秒、默认 10 秒——这些约束均定义在 cmd_parser.py 的Arg枚举中，可直接据此核对参数合法性。
更多用法详见 asys 工具用户指南。
四、msaicerr（AI Core Error 分析）：三种典型用法
msaicerr 入口为 msaicerr.py，安装后位于${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py。源码中的参数注册（msaicerr.py）给出了完整的参数语义：
-p, --report_path：分析 AI Core error 时，错误信息所在的目录；-d, --data：解析 dump 文件时指定的文件路径；-e, --env：运行内置 sample 算子并检查环境（布尔开关）；-out, --output_path：结果输出目录，仅对-p与-d有效（源码通过RequireOtherArgs动作强制该约束）；-dev, --device_id：运行算子使用的 device 编号，缺省为 0，仅对-p与-e有效；-dtype, --dest_dtype：解析 dump 文件时的数据类型，仅对-d有效。
基于以上定义，三种典型用法为：
# 1) 解析一个已有的 AI Core Error 报告路径，结果输出到 <output_dir> python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -p <report_dir> -out <output_dir> -dev 0 # 2) 解析单个 dump 文件（dtype 取值参见 -h 输出） python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -d <dump_file> -out <output_dir> -dtype float16 # 3) 检测当前环境是否具备运行 msaicerr 所需的条件（仅依赖 device 编号） python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -e -dev 0 # 完整参数说明 python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -h源码还体现了两个工程细节：入口设置了全局异常钩子sys.excepthook = handle_exception（msaicerr.py），任何未捕获异常都会打印错误日志并以GLOBAL_RESULT = False标记失败，便于示例脚本用set -e判定成败；对 collect tar 包的解压则通过safe_tar_members做了防 tar-slip 校验（msaicerr.py），过滤符号链接、设备节点等不安全成员。
更多用法详见 msaicerr 工具用户指南。
五、msprof（性能调优）：collector 与 Python wheel 的分工
msprof 由 C++ 侧 collector（basic、dvvp）和msprofPython wheel（分析脚本）组成。bash build.sh完成后，wheel（msprof-0.0.1-py3-none-any.whl）会被拷贝到src/msprof/collector/dvvp/msprofbin/并打包进.run安装包；安装时自动解包到${ASCEND_HOME_PATH}/tools/profiler/profiler_tool/目录下，无需手动pip install。
分析脚本由 msprof collector 流水线内部调用（入口为profiler_tool/analysis/msprof/msprof.py），不会在PATH中注册独立的命令行命令。如需手动运行分析脚本，可直接以 python3 调用安装目录下的入口：
python3 ${ASCEND_HOME_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py -hC++ 侧 collector 一般作为 CANN profiler 流水线的内置组件被调用，开发者无需直接执行；而examples/msprof/run.sh调用的${CANN_ROOT}/tools/profiler/bin/msprof正是该流水线对外暴露的采集入口（见上文 2.4 节的--host-sys-usage用法）。回归测试通过bash build.sh -u --component msprof运行 gtest 用例（产物build/test/ut/msprof/msprof_bin_utest）。
更多用法详见 性能调优工具用户指南。
六、验证清单与延伸阅读
综合以上示例，装完 OAM-Tools 后的推荐验证顺序为：
source /usr/local/Ascend/cann/set_env.sh（按实际安装路径调整）；bash examples/deploy.sh一键跑通全部样例；若不通过，再按asys/run.sh→msaicerr/run.sh→msprof/run.sh的顺序定位到具体组件；- 针对故障定位场景追加
asys info -r="status" -d=0与asys collect --output <dir>做环境自检与信息采集； - 针对 AI Core Error 场景，用
msaicerr.py -e -dev 0确认环境，再用-p/-d解析实际报告或 dump 文件。
延伸阅读：
- asys 用户指南、msaicerr 用户指南、性能调优用户指南
- 快速安装指南：编译依赖与 CANN 软件包安装
- 各组件入口源码：asys.py、msaicerr.py、collector 构建
- 英文对照版：examples/README_en.md
【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
