企业官网建设流程全解析

CANN oam-tools msprof 延迟采集性能数据（--delay / --duration）实战指南

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

导读

本文围绕 CANN oam-tools 中 msprof 工具的延迟采集性能数据能力展开，讲解如何通过--delay与--duration两个参数，按计划延迟启动性能数据采集、并限定采集持续时间，从而精准覆盖 AI 任务运行的关键阶段。读完本文，你将掌握延迟采集的命令格式、参数取值范围与默认值、与动态采集（--dynamic）的互斥约束，以及底层参数解析与采集调度机制的源码级原理，可直接复现于实际故障定位与性能分析场景。

功能说明：为什么需要"延迟采集"

在 AI 训练/推理任务的性能分析中，任务往往存在明显的启动预热阶段与稳定运行阶段。若从任务启动那一刻就开始全量采集性能数据，会产生大量与问题定位无关的早期数据，既浪费存储与磁盘 IO，也增加后续解析开销。

msprof 的延迟采集能力正是为解决这一问题而设计：用户可以通过设置--delay和--duration两个参数，配置数据采集的延迟启动时间与采集持续时间，让 Profiling 在任务运行到目标阶段时才开始，并在设定时长后自动停止。

从 oam-tools 源码看，该能力与动态采集共用同一套参数通道，且两者互斥。延迟采集场景下不支持动态采集性能数据，即不能同时配置--dynamic参数，详见下文"与动态采集的互斥关系"。

命令格式与适用前提

以运行用户登录工具所在环境，执行以下命令采集性能数据：

msprof [options] <app>

延迟采集有两条硬性前提，缺一不可：

1. 仅当采集 AI 任务运行性能数据时支持启用延迟采集能力：即使用场景限定为对用户程序（app）进行 Profiling 采集，必须传入用户程序路径。
2. 必须传入用户程序，且--delay/--duration与--dynamic参数不能同时配置。

• app 参数说明请参见 app 参数说明；
• options 参数说明请参见下表；
• 同时可叠加 采集 AI 任务运行性能数据 中的参数（如--runtime-api=on、--task-time=on等），组成完整的采集方案。

参数说明

表1options 参数说明

两个参数的关键语义要点：

• --delay决定"何时开始"：从采集进程启动（即 msprof 拉起 AI 任务）开始计时，达到设定的秒数后才真正启动数据采集。若 delay 值大于 AI 任务总执行时间，则整个任务执行期间都不会启动采集（任务结束后采集自然终止，不会产生数据）。
• --duration决定"持续多久"：从采集启动时刻（即 delay 结束的时刻）开始计时，达到设定秒数后自动停止采集。默认未配置时，采集将一直持续到 AI 任务结束。
• 两者的时间基准不同：delay 以"msprof 启动时刻"为基准，duration 以"采集实际启动时刻（delay 结束时刻）"为基准，两者共同构成[delay, delay+duration]的完整采集窗口。

参数范围的源码依据

从 oam-tools 源码可以印证上述取值范围与默认行为：

• 参数注册于参数解析器 input_parser.cpp，其帮助信息明确为"Collect start delay time in seconds, range 1 ~ 4294967295s."与"Collection duration in seconds, range 1 ~ 4294967295s."；
• 取值范围校验通过CheckArgRange(cmdInfo, opt, 1, PROF_MAX_DYNAMIC_TIME)完成（input_parser.cpp），最小值 1、最大值与动态采集共用的上限PROF_MAX_DYNAMIC_TIME（4294967295）保持一致；
• 解析后的值分别写入参数结构体的delayTime与durationTime字段（input_parser.cpp），该字段定义于 prof_params.h，并支持序列化/反序列化（SET_VALUE/FROM_STRING_VALUE，见 prof_params.h 与 prof_params.h）。

使用示例

以下命令演示一个最典型的延迟采集场景：AI 任务启动 3 秒后开始采集，持续采集 3 秒后自动停止：

msprof --delay=3 --duration=3 /home/projects/MyApp/out/main

执行时序可拆解为：

1. t=0s：msprof 启动，拉起用户程序/home/projects/MyApp/out/main；
2. t=0~3s：处于延迟等待阶段，不采集任何性能数据；
3. t=3s：--delay计时结束，采集启动，--duration开始计时；
4. t=3~6s：持续采集性能数据；
5. t=6s：--duration计时结束，采集自动停止。

若 AI 任务在 3 秒内就结束了（执行时间 ≤ delay），则整个任务执行期间不会启动采集——这一行为在源码中有对应处理：应用模式下，若任务在 delay 时间内提前退出，会记录日志"[App Mode] Before delay time, the app process has exited."并直接结束（running_mode.cpp）。

底层原理：采集模式的环境变量注入

延迟采集在源码层面的实现并非新增一套独立采集链路，而是通过环境变量标记采集模式的方式，将--delay/--duration的存在信息传递给运行时 Profiling 组件，由底层按延迟窗口控制采集启停。

关键证据位于 application.cpp：

if (DynProfCliMgr::instance()->IsAppMode()) { envsV.push_back(DynProfCliMgr::instance()->GetKeyPidEnv()); } if (!params->delayTime.empty() || !params->durationTime.empty()) { envsV.push_back(PROFILING_MODE_ENV + "=" + DELAY_DURARION_PROFILING_VALUE); }

即当且仅当delayTime或durationTime任一非空时，msprof 会向用户程序注入环境变量PROFILING_MODE=delay_or_duration（常量定义见 config.h）。这与动态采集共用PROFILING_MODE环境变量通道：

• 动态采集（attach 方式）要求用户预先设置export PROFILING_MODE=dynamic（见 PROFILING_MODE 环境变量说明）；
• 延迟采集则由 msprof 进程侧自动注入delay_or_duration标记，无需用户手工配置。

因此，--delay/--duration与--dynamic在语义上都属于"对采集时机的控制"，通过同一PROFILING_MODE通道生效，二者天然互斥——这正是文档中"延迟采集场景下不支持动态采集性能数据"约束的底层原因。

与动态采集的互斥关系

延迟采集与 动态采集性能数据（--dynamic=on）属于两种并列的采集时机控制方式，具有以下差异与约束：

两条硬性约束请务必遵守：

1. --delay/--duration与--dynamic不能同时配置，否则属于非法参数组合；
2. 动态采集场景下，用户程序中不能设置环境变量PROFILING_MODE和PROFILING_OPTIONS（详见 动态采集文档 的注意事项）；而延迟采集的环境变量由 msprof 自动注入，用户无需也无法手工干预。

常见问题与注意事项

• 采集窗口内无数据：若--delay配置的时间超过了 AI 任务的执行时间，AI 任务执行期间不会启动采集，也就不会产生性能数据。可通过查看 msprof 日志中的"[App Mode] Before delay time, the app process has exited."告警（running_mode.cpp）快速确认是否属于任务提前退出场景。
• duration 未配置时的行为：默认情况下采集随启动持续到 AI 任务结束自动停止，适合不关心采集开销、需要完整覆盖任务全程的场景。
• 参数叠加：延迟采集参数可与 采集 AI 任务运行性能数据 中的其他采集项参数自由叠加，例如同时开启 runtime API、任务耗时等采集维度，建议将--delay精确对齐到任务的热点阶段，以最小化数据冗余。
• 数据产出与解析：采集结束后在输出路径下生成 PROF_XXX 目录，性能数据的解析与导出方法可参见 msprof 命令总览 及 AI 任务运行性能数据采集 中的输出说明。

小结

延迟采集是 msprof 在"何时采集"维度上的关键能力，通过--delay指定延迟启动秒数、--duration指定采集持续秒数，即可在 AI 任务运行的关键阶段精准采样，显著降低无关数据量。其参数解析、范围校验（input_parser.cpp）、环境变量注入（application.cpp）与任务提前退出判定（running_mode.cpp）在 oam-tools 源码中均有清晰实现，读者可结合上述文件路径进一步深入阅读。使用时要牢记：仅支持 AI 任务运行性能数据采集场景、必须传入用户程序、且不可与--dynamic同时配置。

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