oam-tools 项目 msprof 采集通用命令完全指南：从参数解析到实战采集

oam-tools 项目 msprof 采集通用命令完全指南：从参数解析到实战采集

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools

导读

msprof是 CANN oam-tools 开源仓库中面向昇腾 AI 处理器的性能数据采集命令行工具，支持AI 任务运行性能数据（如算子耗时、AI Core 利用率、HBM 带宽）与AI 处理器系统数据（如芯片功耗、温度、频率）的采集与自动解析。本文以 docs/zh/profiling/msprof_cmd/general_collect_commands.md 为骨架，完整讲解 msprof 采集通用命令的两种命令格式、app参数传参方式、options参数（--output、--type、--environment、--storage-limit、--help）的取值与约束，并结合本仓库src/msprof/collector/dvvp/msprofbin/src/input_parser.cpp等源码，说明每个参数在底层的校验逻辑与默认行为。读完本文，你将掌握在任意目录下使用 msprof 采集并解析性能数据、正确控制数据落盘位置与老化策略的完整实战能力。

msprof 采集通用命令概述

在 oam-tools 项目中，msprof 的命令行实现位于 src/msprof/collector/dvvp/msprofbin，核心入口为InputParser（input_parser.cpp）。msprof 提供的性能采集能力包括：

• AI 任务运行性能数据：采集被采集程序（如推理/训练应用）运行期间在 AI 处理器上产生的算子、通信、任务级性能数据；
• AI 处理器系统数据：采集芯片设备级的系统运行状态数据。

msprof采集通用命令是所有这些性能数据采集的公共基础：它解决的是"性能数据采集时的基本信息"问题，包括参数说明、AI 任务文件（app）的指定方式、数据存放路径（--output）、自定义环境变量（--environment）等。换言之，无论你最终要采集哪类性能数据（AI 任务数据、msproftx 数据还是 AI 处理器系统数据），都需要先掌握本节介绍的通用命令格式与通用参数。

适用芯片范围：文档标注支持 ascend950、A3、910b、910、310p、310b 等昇腾芯片形态，具体以你当前安装的 msprof 版本支持的硬件为准。

命令格式：两种传入用户程序的方式

登录运行环境后，可以在任意目录下执行 msprof 命令。msprof 支持两种命令格式：

方式一（推荐）：在 msprof 命令末尾，直接传入用户程序或执行脚本。

msprof [options] <app>

方式二：通过--application参数传入用户程序或执行脚本。

msprof [options] --application=<app>

两种方式的差异并不只是书写习惯：从源码看，二者走的是不同的参数解析路径。方式一（末尾直接跟<app>）由CheckUserCmdValid（input_parser.cpp）处理，将程序路径切分为app_dir（程序所在目录）与app（程序名）后存入采集参数；方式二（--application）则由CheckAppValid/GetAppParam（input_parser.cpp）处理，会把--application="..."中第一个空格前的部分识别为程序路径、空格后的部分识别为程序参数（app_parameters）。

方式二还额外支持解释器形式的命令，例如bash xx.sh args、python xx.py args、python -m xx args、/usr/bin/python xx.py args等——源码中Utils::IsAppName(cmdPath)判断失败后会进入解释器分支（input_parser.cpp），此时要求必须携带脚本或模块参数，否则报错an interpreter (python/bash/sh) requires a script or module argument。

下文举例时，为避免信息冗余，均采用方式一进行示例。

app 参数说明：如何指定被采集程序

app参数用于传入用户执行程序及相关参数，支持二进制可执行程序与执行脚本两种形态。

方式一配置示例（命令末尾直接传程序）

在 msprof 命令末尾传入二进制执行程序和程序参数：

msprof --output=/home/projects/output /home/projects/main parameter1 parameter2

在 msprof 命令末尾传入执行脚本和脚本参数：

msprof --output=/home/projects/output /home/projects/run.sh parameter1 parameter2

方式二配置示例（--application 参数传程序）

使用--application参数传入二进制执行程序和程序参数：

msprof --application="/home/projects/main parameter1 parameter2 ..."

使用--application参数传入执行脚本和脚本参数（训练场景）：

msprof --application="/home/projects/run.sh parameter1 parameter2 ..."

使用注意与安全约束

[!NOTE]说明

• 若 parameter 中存在异常符号时将无法识别参数，因此推荐使用方式一传入用户程序。使用方式一时，若配置的用户程序命令中存在"配置参数值需要加引号"的情况，请将命令写入 Shell 脚本后，通过执行 Shell 脚本的方式在 msprof 命令上添加用户程序命令。
• 不建议配置其他用户目录或其他用户可写目录下的 AI 任务，避免提权风险；不建议配置删除文件或目录、修改密码、提权命令等有安全风险的高危操作；应避免使用pmupload作为程序名称。
• 采集全部性能数据、采集 AI 任务运行时性能数据或采集 msproftx 数据时，本参数必选。采集 AI 处理器系统数据时，本参数可选。采集 Host 侧系统数据时，本参数可选。

这些约束在源码中同样有对应实现：PreCheckApp（input_parser.cpp）会对 app 名称合法性、路径存在性、是否为软链接、是否具备可执行权限（OSAL_X_OK）、是否为目录等逐一校验；CheckAppParamValid则限制--application参数总长度不超过MAX_APP_LEN（input_parser.cpp）。

options 参数说明：五大通用参数详解

--output：性能数据存放路径

--output=<path>为可选参数，指定收集到的性能数据的存放路径。

• 该参数优先级高于ASCEND_WORK_PATH环境变量，具体请参见《环境变量参考》（CANN 社区环境变量参考文档）。
• 路径中不能包含特殊字符，包括：

"\n", "\\n", "\f", "\\f", "\r", "\\r", "\b", "\\b", "\t", "\\t", "\v", "\\v", "\u007F", "\\u007F", "\"", "\\\"", "'", "\'", "\\", "\\\\", "%", "\\%", ">", "\\>", "<", "\\<", "|", "\\|", "&", "\\&", "$", "\\$", ";", "\\;", "`", "\\`"

• 在 msprof 命令末尾添加 AI 任务执行命令来传入用户程序或执行脚本时，默认落盘在当前目录。
• 配置--application参数添加 AI 任务执行命令来传入用户程序或执行脚本时，默认落盘在 AI 任务文件所在目录。

源码层面的校验逻辑非常完整。CheckOutputValid（input_parser.cpp）依次执行：相对路径转绝对路径 → 检查路径最大长度 → 调用Utils::CheckPathWithInvalidChar检查非法字符 →CreateDir创建目录 → 校验目录是否为目录、是否可写（OSAL_W_OK）→ 最终通过CanonicalizePath得到规范化绝对路径写入result_dir。因此如果--output指定的目录无写权限或路径含特殊字符，命令会直接报错拒绝执行，而不是静默失败。

--type：性能数据解析结果文件格式

--type=<type>为可选参数，设置性能数据解析结果文件格式，即选择 msprof 命令行执行采集后自动解析的结果文件格式，取值为：

• text：解析为.json、.csv格式的文件和.db格式文件（msprof_时间戳.db）。默认为 text。
• db：仅解析为一个汇总所有性能数据的.db格式文件（msprof_时间戳.db），使用 MindStudio Insight 工具展示。

该参数在源码中的常量定义为TEXT_EXPORT_TYPE = "text"与DB_EXPORT_TYPE = "db"（input_parser.cpp）。CheckExportType（input_parser.cpp）对取值做严格校验，非text/db时直接报错Argument --type: invalid value。因此当你计划用 MindStudio Insight 做可视化分析时，应显式指定--type=db；需要.json/.csv便于脚本化处理时使用默认的text即可。

--environment：采集时的自定义环境变量

--environment=<env>为可选参数，用于在采集时向运行环境注入需要的自定义环境变量。

• 不建议使用其他用户的目录覆盖原有环境变量，避免提权风险。
• 配置格式为：

--environment="${envKey}=${envValue}" --environment="${envKey1}=${envValue1};${envKey2}=${envValue2}"

即支持单个变量赋值，也支持用分号;分隔的多个变量同时注入。源码中CheckEnvironmentValid（input_parser.cpp）将参数原样保存到params_->app_env，后续由采集框架在拉起用户程序时注入对应环境。

--storage-limit：落盘目录容量上限与文件老化

--storage-limit=<limit-value>为可选参数，指定落盘目录允许存放的最大文件容量。当性能数据文件在磁盘中即将占满本参数设置的最大存储空间，或剩余磁盘总空间即将被占满时（总空间剩余 <= 20MB），则会将磁盘内最早的文件进行老化删除处理。

• 取值范围[200, 4294967295]，单位为 MB，例如--storage-limit=200MB，默认未配置本参数。
• 未配置本参数时，采集前如果磁盘可用空间小于 20MB，则不落盘数据。

该参数的实现证据非常充分：

• 取值校验：CheckStorageLimitValid（input_parser.cpp）与ParamValidation::CheckStorageLimit（param_validation.cpp）校验单位必须为MB，且数值必须在[STORAGE_LIMIT_DOWN_THD, UINT32_MAX]（即 200MB ~ 4294967295MB）区间内，非法时提示valid range is %dMB~%uMB。
• 老化机制：文件老化删除实现在 file_ageing.cpp，其中STORAGE_RESERVED_VOLUME被定义为(STORAGE_LIMIT_DOWN_THD / 10) << 20，即 20MB 的磁盘保留阈值；当--storage-limit未配置（limit 为 0）时，默认以磁盘可用空间为上限，若可用空间不足 20MB 则记录日志"Data will not be collected"，拒绝落盘采集。需要说明的是，FileAgeing::Init中对 MINI 类型平台会打印"The MINI_TYPE platform does not support file ageing"，即该老化能力存在平台形态限制，实际以你所部署的产物平台为准。

--help：帮助提示

--help为可选参数，输出 msprof 命令的帮助信息。源码中帮助项定义为{"storage-limit", "Specify the output directory volume. range 200MB ~ 4294967295MB."}（input_parser.cpp）等一整套参数说明列表，实际执行msprof --help即可查看完整参数清单。

使用示例：一次完整的采集与自动解析

登录运行环境，在任意路径下执行以下命令：

msprof --output=/home/projects/output /home/projects/MyApp/out/main

命令含义拆解：

• --output=/home/projects/output：指定性能数据结果文件落盘目录；
• /home/projects/MyApp/out/main：通过方式一传入的被采集二进制程序（app）。

msprof 命令执行完成后，会自动解析并导出性能数据结果文件，默认导出.json、.csv与.db（msprof_时间戳.db）三种格式的结果。.db格式性能数据的详细字段说明，请参见本仓库文档 docs/en/msaicerr/README.md 之外的 msprof 相关章节，以及仓库中 msprof 采集器源码 src/msprof/collector/dvvp/msprof 目录下的数据定义；如需使用 MindStudio Insight 查看，可在命令中加入--type=db。

组合实战：一个兼顾落盘与容量的采集命令

将上述参数组合，一个典型的"训练脚本 + 自定义环境变量 + 容量限制 + db 格式输出"采集命令如下：

msprof \ --output=/home/projects/output \ --type=db \ --environment="ASCEND_GLOBAL_LOG_LEVEL=1;ASCEND_SLOG_PRINT_TO_STDOUT=0" \ --storage-limit=1024MB \ /home/projects/run.sh parameter1 parameter2

各参数作用一览：

参数	取值示例	说明
--output	/home/projects/output	结果落盘目录，优先级高于ASCEND_WORK_PATH，路径不得含特殊字符
--type	text（默认）/db	自动解析结果格式；db供 MindStudio Insight 展示
--environment	KEY1=v1;KEY2=v2	采集时注入的自定义环境变量，分号分隔多个
--storage-limit	200MB~4294967295MB	落盘目录容量上限，超出后老化删除最早文件
--help	-	查看完整参数帮助

常见问题与排查建议

1. 程序参数含引号/特殊符号无法识别：改用方式一，或把完整命令写入 Shell 脚本后通过执行脚本方式传入。
2. --output报"contains invalid character"或"permission denied"：路径含特殊字符或无写权限，检查输出目录后重试；源码中对应CheckPathWithInvalidChar与OsalAccess2(..., OSAL_W_OK)校验（input_parser.cpp）。
3. --type传入非 text/db 报 invalid value：CheckExportType仅接受text与db两个取值（input_parser.cpp）。
4. --storage-limit非法：确认单位为MB且取值在[200, 4294967295]区间内，非法时提示valid range is 200MB~4294967295MB（param_validation.cpp）。
5. app 是软链接或无可执行权限：PreCheckApp会拒绝软链接（IsSoftLink）与无OSAL_X_OK权限的程序，请使用真实路径并确保程序可执行（input_parser.cpp）。

延伸阅读

• 本文关联文档：docs/zh/profiling/msprof_cmd/general_collect_commands.md
• 命令参数解析核心实现：src/msprof/collector/dvvp/msprofbin/src/input_parser.cpp
• 参数取值与范围校验：src/msprof/collector/dvvp/common/validation/param_validation.cpp
• 文件老化删除机制：src/msprof/collector/dvvp/transport/file_ageing.cpp
• 其他 msprof 采集命令文档：docs/zh/profiling/msprof_cmd/msprof_cmd.md、docs/zh/profiling/msprof_cmd/host_system_data.md、docs/zh/profiling/msprof_cmd/processorai_accelerator_system_data.md

【免费下载链接】oam-tools本项目为开发者提供故障定位工具，包含故障信息收集，软硬件信息展示，AI core error报错分析等能力，提升故障问题定位效率，文档可在昇腾社区搜索“故障处理简介”（选择社区版）。项目地址: https://gitcode.com/cann/oam-tools