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_PATHascend_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.shexamples/目录下为各场景预置了可直接执行的脚本加载环境变量后即可运行脚本说明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一条命令体检 deviceasys/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-usagecpu,mem --sys-period5即调用安装目录下的msprof命令采集 5 秒--sys-period5的 Host 侧 CPU 与内存系统数据--host-sys-usagecpu,mem输出到当前目录的./msprof_output。脚本自带set -e若 msprof 不可用或采集失败会立即报错退出。三、asys故障信息收集与诊断两种调用方式与子命令src/asys/目录下同时存在 asys.py 和指向它的软链接asyssrc/asys/asys - ./asys.pyCMake 通过install(DIRECTORY ${ASYS_DIR} ...)将整个目录原样拷贝软链接也会保留。因此安装后两种调用都能直接用# 形式一显式 python3 调用 .py python3 ${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys.py -h # 形式二直接调用软链接 asysasys.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支持的参数infoCollects the software and hardware information of the host and device-rinfo 运行模式、-ddevice 编号healthDiagnoses the health status of the device-ddevice 编号collect采集环境中已有运维调试信息或实时导出堆栈task_dir、--output、--tar、-r、--remote、--all、--quiet、--timeoutlaunch执行任务脚本并在运行期间采集运维信息位置参数task、--output、--tardiagnose诊断 device 硬件状态component、stress_detect、hbm_detect、cpu_detect、aicore_stl_detect仅支持 910B / 910_93 / 950 / 960-r、-d、--timeout、--outputanalyze解析 trace、coredump、coretrace、stackcore、aicore_error 与 ub 信息-r、-d、-f、-p、--exe_file、--core_file、-s等config获取或恢复配置信息--get、-d、--restore、--stress_detectprofiling采集 device 的性能数据-d、-r、--output、--period、--aic_metrics在环境变量加载生效后可以直接以 asys 调用以下最常用命令# 采集主机与 device 的软硬件信息不依赖待诊断任务通常作为环境自检 asys info -rstatus -d0 # 体检 device 健康状态 asys health # 采集环境中已存在的运维信息并打包到指定输出目录 asys collect --output output_dir其中collect的-r参数取值stacktrace时必须与--remote、--all配合使用向指定进程发送信号生成 stackcore 文件--timeout取值范围为 [1, 60] 秒、默认 10 秒——这些约束均定义在 cmd_parser.py 的Arg枚举中可直接据此核对参数合法性。更多用法详见 asys 工具用户指南。四、msaicerrAI 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_exceptionmsaicerr.py任何未捕获异常都会打印错误日志并以GLOBAL_RESULT False标记失败便于示例脚本用set -e判定成败对 collect tar 包的解压则通过safe_tar_members做了防 tar-slip 校验msaicerr.py过滤符号链接、设备节点等不安全成员。更多用法详见 msaicerr 工具用户指南。五、msprof性能调优collector 与 Python wheel 的分工msprof 由 C 侧 collectorbasic、dvvp和msprofPython wheel分析脚本组成。bash build.sh完成后wheelmsprof-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 -rstatus -d0与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），仅供参考