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核心入口为InputParserinput_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] --applicationapp两种方式的差异并不只是书写习惯从源码看二者走的是不同的参数解析路径。方式一末尾直接跟app由CheckUserCmdValidinput_parser.cpp处理将程序路径切分为app_dir程序所在目录与app程序名后存入采集参数方式二--application则由CheckAppValid/GetAppParaminput_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 侧系统数据时本参数可选。这些约束在源码中同样有对应实现PreCheckAppinput_parser.cpp会对 app 名称合法性、路径存在性、是否为软链接、是否具备可执行权限OSAL_X_OK、是否为目录等逐一校验CheckAppParamValid则限制--application参数总长度不超过MAX_APP_LENinput_parser.cpp。options 参数说明五大通用参数详解--output性能数据存放路径--outputpath为可选参数指定收集到的性能数据的存放路径。该参数优先级高于ASCEND_WORK_PATH环境变量具体请参见《环境变量参考》CANN 社区环境变量参考文档。路径中不能包含特殊字符包括\n, \\n, \f, \\f, \r, \\r, \b, \\b, \t, \\t, \v, \\v, \u007F, \\u007F, \, \\\, , \, \\, \\\\, %, \\%, , \\, , \\, |, \\|, , \\, $, \\$, ;, \\;, , \\在 msprof 命令末尾添加 AI 任务执行命令来传入用户程序或执行脚本时默认落盘在当前目录。配置--application参数添加 AI 任务执行命令来传入用户程序或执行脚本时默认落盘在 AI 任务文件所在目录。源码层面的校验逻辑非常完整。CheckOutputValidinput_parser.cpp依次执行相对路径转绝对路径 → 检查路径最大长度 → 调用Utils::CheckPathWithInvalidChar检查非法字符 →CreateDir创建目录 → 校验目录是否为目录、是否可写OSAL_W_OK→ 最终通过CanonicalizePath得到规范化绝对路径写入result_dir。因此如果--output指定的目录无写权限或路径含特殊字符命令会直接报错拒绝执行而不是静默失败。--type性能数据解析结果文件格式--typetype为可选参数设置性能数据解析结果文件格式即选择 msprof 命令行执行采集后自动解析的结果文件格式取值为text解析为.json、.csv格式的文件和.db格式文件msprof_时间戳.db。默认为 text。db仅解析为一个汇总所有性能数据的.db格式文件msprof_时间戳.db使用 MindStudio Insight 工具展示。该参数在源码中的常量定义为TEXT_EXPORT_TYPE text与DB_EXPORT_TYPE dbinput_parser.cpp。CheckExportTypeinput_parser.cpp对取值做严格校验非text/db时直接报错Argument --type: invalid value。因此当你计划用 MindStudio Insight 做可视化分析时应显式指定--typedb需要.json/.csv便于脚本化处理时使用默认的text即可。--environment采集时的自定义环境变量--environmentenv为可选参数用于在采集时向运行环境注入需要的自定义环境变量。不建议使用其他用户的目录覆盖原有环境变量避免提权风险。配置格式为--environment${envKey}${envValue} --environment${envKey1}${envValue1};${envKey2}${envValue2}即支持单个变量赋值也支持用分号;分隔的多个变量同时注入。源码中CheckEnvironmentValidinput_parser.cpp将参数原样保存到params_-app_env后续由采集框架在拉起用户程序时注入对应环境。--storage-limit落盘目录容量上限与文件老化--storage-limitlimit-value为可选参数指定落盘目录允许存放的最大文件容量。当性能数据文件在磁盘中即将占满本参数设置的最大存储空间或剩余磁盘总空间即将被占满时总空间剩余 20MB则会将磁盘内最早的文件进行老化删除处理。取值范围[200, 4294967295]单位为 MB例如--storage-limit200MB默认未配置本参数。未配置本参数时采集前如果磁盘可用空间小于 20MB则不落盘数据。该参数的实现证据非常充分取值校验CheckStorageLimitValidinput_parser.cpp与ParamValidation::CheckStorageLimitparam_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与.dbmsprof_时间戳.db三种格式的结果。.db格式性能数据的详细字段说明请参见本仓库文档 docs/en/msaicerr/README.md 之外的 msprof 相关章节以及仓库中 msprof 采集器源码 src/msprof/collector/dvvp/msprof 目录下的数据定义如需使用 MindStudio Insight 查看可在命令中加入--typedb。组合实战一个兼顾落盘与容量的采集命令将上述参数组合一个典型的训练脚本 自定义环境变量 容量限制 db 格式输出采集命令如下msprof \ --output/home/projects/output \ --typedb \ --environmentASCEND_GLOBAL_LOG_LEVEL1;ASCEND_SLOG_PRINT_TO_STDOUT0 \ --storage-limit1024MB \ /home/projects/run.sh parameter1 parameter2各参数作用一览参数取值示例说明--output/home/projects/output结果落盘目录优先级高于ASCEND_WORK_PATH路径不得含特殊字符--typetext默认/db自动解析结果格式db供 MindStudio Insight 展示--environmentKEY1v1;KEY2v2采集时注入的自定义环境变量分号分隔多个--storage-limit200MB~4294967295MB落盘目录容量上限超出后老化删除最早文件--help-查看完整参数帮助常见问题与排查建议程序参数含引号/特殊符号无法识别改用方式一或把完整命令写入 Shell 脚本后通过执行脚本方式传入。--output报contains invalid character或permission denied路径含特殊字符或无写权限检查输出目录后重试源码中对应CheckPathWithInvalidChar与OsalAccess2(..., OSAL_W_OK)校验input_parser.cpp。--type传入非 text/db 报 invalid valueCheckExportType仅接受text与db两个取值input_parser.cpp。--storage-limit非法确认单位为MB且取值在[200, 4294967295]区间内非法时提示valid range is 200MB~4294967295MBparam_validation.cpp。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考