oam-tools

🚀 概述

oam-tools（Operations, Administration, and Maintenance）项目为开发者提供故障定位工具和性能测试调优工具，包含故障信息收集，软硬件信息展示，AI core error报错分析，AI任务性能采集和分析等能力，提升故障问题定位和AI任务性能分析效率。

🧩 支持的硬件环境

在搭建环境之前，请先确认本机硬件在本工具的支持范围内。

• CPU 架构：aarch64、x86_64

• 昇腾 AI 处理器：

  npu-smi info Name 列	适用产品	对应 CANN ops 包代号
  910B	Atlas A2 训练系列产品 / Atlas 800I A2 推理产品	910b
  910_93/910C	Atlas A3 训练系列产品 / Atlas A3 推理系列产品（业内"910C"对应此项）	910_93
  950	Atlas 950 系列产品	950

  • npu-smi info实际可能显示带子型号的字符串（如910B1 / 910B2 / 910B3 / 910B4），按"Name 列包含上述关键字"的规则匹配即可。
  • 其它芯片暂不支持，欢迎提交 issue 反馈。CANN ops 包名拼接规则与下载详见快速安装。

🔍 目录结构

关键目录结构如下：

├── cmake                                          # 工程编译目录
├── scripts                                        # 辅助构建相关文件
├── src                                            # 所有模块的源代码
|   ├── asys                                       # asys模块目录
|   ├── hccl_test                                  # hccl_test模块目录
|   ├── msaicerr                                   # msaicerr模块目录 
|   ├── msprof                                     # msprof模块目录
|   ├── third_party                                # 依赖的第三方库头文件
|   ......
├── test                                           # UT/ST用例
├── CMakeLists.txt                                 # 构建编译配置文件
├── build.sh                                       # 项目工程编译脚本
......

⚡️ 环境准备

请先按照快速安装指南完成环境准备。

🌐 源码编译

执行以下命令进行编译：

bash build.sh

如需指定第三方库路径，可通过 --cann_3rd_lib_path 参数传入：

bash build.sh --cann_3rd_lib_path=${third_party_path}

• --cann_3rd_lib_path：第三方库存储目录，默认值为 ./third_party。若本地不存在第三方库，编译脚本将自动从 gitcode 开源仓库下载各第三方库源码。
• 编译过程中会自动下载闭源二进制包，该包含有保证功能正常运行所需的库及头文件，且仅提供 release 版本，即使编译选项指定为 debug，也只会下载 release 版本的 tar 包。
• 若编译环境无法访问网络，请参考离线编译环境准备提前完成依赖包的下载与配置，并通过 --cann_3rd_lib_path 参数指定依赖包所在目录后再执行编译。
• 更多编译参数请通过 bash build.sh -h 查看。

编译完成后，build_out 目录下会生成 cann-oam-tools_<cann_version>_linux-<arch>.run 软件包，其中 <cann_version> 为版本号，<arch> 为操作系统架构（可选值：x86_64 或 aarch64）。

🔨 安装

可执行如下命令安装编译生成的oam-tools软件包：

./cann-oam-tools_<cann_version>_linux-<arch>.run --full --install-path=${install_path}

安装完成之后，用户编译生成的oam-tools软件包会替换已安装CANN开发套件包中的oam-tools相关软件。

如果您的环境上grep版本大于3.8.0，安装时会出现告警，例如grep: waring: stray \ before -，这是由于grep高版本对表达式有更严格的校验，但并不影响安装和使用

🧪 验证

编译完成后，用户可以进行测试验证项目功能是否正常。

Python 依赖安装已在环境准备中处理，无需额外操作。

编译执行测试用例：

bash build.sh -u

如果希望指定单独组件进行测试，可以使用--component参数指定：

可选值：asys（故障信息收集）、msaicerr（AI Core Error 分析）、msprof（性能调优）、all（所有组件，默认）

bash build.sh -u --component msprof

UT测试用例编译输出目录为build，如果想清除历史编译记录，可以执行如下操作：

rm -rf build_out/ build/

功能运行示例

完成安装后，工具会被释放到 CANN 安装目录下的 tools/ 子目录（root 用户默认在 /usr/local/Ascend/cann/tools/）。运行示例前请先加载环境变量：

source ${ASCEND_INSTALL_PATH}/bin/setenv.bash

下文示例中尖括号 <...> 内为用户需要替换的占位（输入路径、输出路径、device id 等），其余部分原样照抄即可。

asys（故障信息收集 / 诊断）

src/asys/ 目录下同时存在 asys.py 和指向它的软链接 asys（src/asys/asys -> ./asys.py），CMake 通过 install(DIRECTORY ${ASYS_DIR} ...) 将整个目录原样拷贝，软链接也会保留。因此安装后两种调用都能直接用：

# 形式一：显式 python3 调用 .py
python3 ${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys.py -h

# 形式二：直接调用软链接 asys（asys.py 自带 #!/usr/bin/env python3 shebang）
${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys -h

asys 的子命令在 src/asys/cmdline/cmd_parser.py 的 Command 枚举中定义，包含 info / health / collect / launch / diagnose / analyze / config / profiling。下面以软链接形式给出常用调用，把命令前缀简记为 <asys_bin>（即 ${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys）：

# 采集主机与 device 的软硬件信息（不依赖待诊断任务，通常作为环境自检）
<asys_bin> info

# 体检 device 健康状态
<asys_bin> health

# 采集环境中已存在的运维信息并打包到指定输出目录
<asys_bin> collect --output <output_dir>

将 <asys_bin> 加入 PATH 后即可直接 asys info / asys health 等。完整参数以 <asys_bin> -h 输出为准。

msaicerr（AI Core Error 分析）

msaicerr 入口为 src/msaicerr/msaicerr.py，安装后位于 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py。

# 1) 解析一个已有的 AI Core Error 报告路径，结果输出到 <output_dir>
python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -p <report_dir> -out <output_dir> -dev 0

# 2) 解析单个 dump 文件（dtype 取值参见 -h 输出）
python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -d <dump_file> -out <output_dir> -dtype float16

# 3) 检测当前环境是否具备运行 msaicerr 所需的条件（仅依赖 device 编号）
python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -e -dev 0

# 完整参数说明
python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -h

msprof（性能调优）

msprof 由 C++ 侧 collector（basic、dvvp）和 msprof Python wheel（分析脚本）组成。bash build.sh 完成后，wheel（msprof-0.0.1-py3-none-any.whl）会被拷贝到 src/msprof/collector/dvvp/msprofbin/ 并打包进 .run 安装包；安装时自动解包到 ${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/ 目录下，无需手动 pip install。

分析脚本由 msprof collector 流水线内部调用（入口为 profiler_tool/analysis/msprof/msprof.py），不会在 PATH 中注册独立的命令行命令。如需手动运行分析脚本，可直接以 python3 调用安装目录下的入口：

python3 ${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py -h

C++ 侧 collector 一般作为 CANN profiler 流水线的内置组件被调用，开发者无需直接执行；回归通过 bash build.sh -u --component msprof 运行 gtest 用例（产物 build/test/ut/msprof/msprofbin/msprof_bin_utest）。

🅿️ Pre-commit

pre-commit 是一个用于管理和维护 Git 预提交钩子（hooks）的框架，通过在代码提交前自动化执行代码检查、格式化和安全扫描，确保代码质量并统一团队规范，显著减少 CI/CD 流水线失败并提升协作效率。 本仓已配置pre-commit，用户可以参考CANN社区的pre-commit配置指导书中第3章节安装pre-commit, 首次由于需要配置java，maven环境以及构建jar包，需要的时间比较长。

📖 相关文档

asys工具用户指南：介绍asys命令行工具的使用方法，支持以下功能：故障信息收集、业务复跑+故障信息收集、软硬件和Device状态信息展示、健康检查、综合检测、组件检测、trace文件解析/coredump文件解析/stackcore文件解析/coretrace文件解析、实时堆栈导出、环境配置、AI Core Error故障信息解析等。

msaicerr工具用户指南：介绍msaicerr命令行工具的使用方法，用于分析AI Core Error问题、解析Dump文件、检查环境等。

性能调优工具用户指南：介绍msprof命令行工具的使用方法，用于指导用户采集和分析运行在昇腾AI处理器上的AI任务各个运行阶段的关键性能指标，以便快速定位软、硬件性能瓶颈，提升AI任务性能分析的效率。

HCCL性能测试工具用户指南：介绍hccl_test工具的使用方法，用于指导分布式训练或推理场景下，测试集合通信的功能与性能。

ℹ️ 相关信息

• 贡献指南
• 安全声明
• 许可证