CANN oam-tools 中 mstx API 使用示例为应用添加自定义耗时打点并借助 msprof 采集【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools导读mstx API 是 CANN 提供给开发者的一套轻量级打点接口用于在用户程序或上层框架代码中记录特定事件发生的时间跨度帮助定位应用瓶颈。本文以 oam-tools 仓库中 mstx API使用示例 为骨架完整给出基于 AscendCL 的 mstx 打点示例代码并深入讲解 Range 与 Domain 两大核心概念、msprof 采集命令及 domain 过滤参数的源码级实现。读完本文你将掌握如何在自己的推理/训练程序中插入 mstx 打点、如何用msprof --msproftxon采集并裁剪输出数据以及这些接口在 msprof 侧的数据流转机制。一、mstx API 在 Profiling 体系中的定位在 CANN 的 Profiling 数据体系中msprof 工具支持采集多种数据。其中用户自定义事件的时间跨度数据属于msproftx 数据类别。在 采集msproftx数据 中明确给出了三种打点方式的使用建议通用场景推荐使用mstx API也可选 msproftx APIPyTorch 场景使用 TorchNPU Profiler API。即当需要定位应用程序或上层框架程序的性能瓶颈时通过特定接口记录应用程序执行期间特定事件发生的时间跨度写入性能数据文件。mstx API 是其中的首选方案其核心价值在于——用户不需要关心 msprof 的底层采集细节只需在业务代码的关键路径如模型执行前后、通信任务前后插入极简的起止打点即可获得 host 侧与 device 侧的耗时数据。二、环境准备与样例代码获取mstx API 样例代码随 Ascend-cann-toolkit 工具包一起发布使用前需要满足如下前提安装 Ascend-cann-toolkit 包确保已正确安装 CANN 软件工具包参见 《CANN 软件安装》 与 快速安装指南。定位样例代码mstx API 样例代码集成在 Ascend-cann-toolkit 包中路径为${INSTALL_DIR}/tools/mstx/samples其中${INSTALL_DIR}为 CANN 软件安装后的文件存储路径。以 root 用户安装为例默认存储路径为/usr/local/Ascend/cann按 README 使用样例进入上述samples目录后依据其中的 README 文档编译与运行样例。说明本节提供的打点代码为示例性质非完整可独立编译的工程完整样例请以上述 CANN 安装路径下的tools/mstx/samples为准。三、mstx API 核心概念Range 与 Domain在进入代码之前先理解 mstx 的两个核心抽象。仓库源码 mstx_def.h 中定义了相关数据类型using mstxRangeId uint64_t; // Range 的句柄类型为 64 位无符号整数 struct MstxDomainRegistrationSt {}; typedef struct MstxDomainRegistrationSt MstxDomainHandle; typedef MstxDomainHandle* mstxDomainHandle_t; // Domain 的句柄类型Range时间区间一次打点记录的起止区间。调用mstxRangeStartA开启一段区间并返回mstxRangeId其值为 0 表示无效 Range源码中定义为MSTX_INVALID_RANGE_ID 0随后调用mstxRangeEnd(rangeId)关闭该区间。Range 数据包含 start/end 两个时间戳msprof 据此计算该段代码的真实耗时。Domain域对打点事件进行逻辑分组的容器。默认情况下打点属于默认 domain源码中以default标识用户可调用mstxDomainCreateA创建自定义 domain并针对性地在指定 domain 内打点。Domain 的用途在于数据裁剪——msprof 采集时可以通过--mstx-domain-include/--mstx-domain-exclude只保留或过滤特定 domain 的数据从而减小输出体积、聚焦分析目标。从 mstx_def.h 的函数表枚举可以看出 mstx 接口的完整功能面核心模块MSTX_API_MODULE_CORE包含MSTX_FUNC_START、MSTX_FUNC_MARKA、MSTX_FUNC_RANGE_STARTA、MSTX_FUNC_RANGE_END等核心域模块MSTX_API_MODULE_CORE_DOMAIN包含MSTX_FUNC_DOMAIN_CREATEA、MSTX_FUNC_DOMAIN_DESTROY、MSTX_FUNC_DOMAIN_MARKA、MSTX_FUNC_DOMAIN_RANGE_STARTA、MSTX_FUNC_DOMAIN_RANGE_END等。即 mstx API 家族除本文示例用到的 Range/Domain 打点接口外还提供 Mark 标记类接口mstxMarkA、mstxDomainMarkA与 domain 销毁接口mstxDomainDestroy对应声明可见 mstx_inject.h。四、mstx API 使用示例完整代码以下是使用 mstx API 执行采集操作的示例代码完整覆盖了AscendCL 初始化 → 资源申请 → 默认 domain 打点 → 自定义 domain 打点 → 资源释放 → 去初始化的完整流程aclrtContext context_; aclrtStream stream_; // 1. AscendCL初始化 aclError ret ACL_ERROR_NONE; ret aclInit(nullptr); if (ret ! ACL_SUCCESS) { ERROR_LOG(aclInit failed); return FAILED; } // 2. 申请运行管理资源包括设置用于计算的Device、创建Context、创建Stream ret aclrtSetDevice(0); if (ret ! ACL_ERROR_NONE) { ERROR_LOG(aclrtSetDevice failed); return FAILED; } ret aclrtCreateContext(context_, 0); if (ret ! ACL_ERROR_NONE) { ERROR_LOG(acl create context failed); return FAILED; } ret aclrtCreateStream(stream_); if (ret ! ACL_ERROR_NONE) { ERROR_LOG(acl create stream failed); return FAILED; } .... // 3. 在想采集耗时的代码位置添加打点代码比如在执行模型前后打点获取模型执行耗时 mstxRangeId rangeId mstxRangeStartA(model execute, nullptr); // 第二个入参设置nullptr只记录host侧range耗时(适用于纯host侧代码段)设置有效的stream同时记录host侧和对应device侧耗时(适用于下发计算任务或通信任务) ret aclmdlExecute(modelId, input, output); // 执行模型样例代码 mstxRangeEnd(rangeId); // 4. 步骤3里的打点数据属于默认domain可调用mstx domain相关接口创建自定义domain并指定domain进行打点 mstxDomainHandle_t selfDomain mstxDomainCreateA(self_domain); mstxRangeId domainRangeId mstxDomainRangeStartA(selfDomain, model execute, nullptr); ret aclmdlExecute(modelId, input, output); // 执行模型样例代码 mstxDomainRangeEnd(selfDomain, domainRangeId); // 5. 释放运行管理资源 // 6. AscendCL去初始化4.1 逐步拆解步骤 1AscendCL 初始化。aclInit(nullptr)完成 AscendCL 运行环境的初始化是所有 AscendCL 程序的第一步需先于后续所有资源申请与 mstx 打点执行。步骤 2申请运行管理资源。依次调用aclrtSetDevice(0)设置用于计算的 Device、aclrtCreateContext(context_, 0)创建 Context、aclrtCreateStream(stream_)创建 Stream。这是执行模型推理/训练任务的前置条件mstx 打点必须运行在已初始化好的 AscendCL 环境中。步骤 3默认 domain 打点——获取模型执行耗时。这是 mstx 最基本的用法mstxRangeId rangeId mstxRangeStartA(model execute, nullptr); ret aclmdlExecute(modelId, input, output); // 执行模型 mstxRangeEnd(rangeId);mstxRangeStartA的第二个入参stream是决定采集范围的关键传入nullptr只记录 host 侧 range 耗时适用于纯 host 侧代码段传入有效的 stream同时记录 host 侧和对应 device 侧耗时适用于下发计算任务或通信任务的场景如上面的aclmdlExecute。此处的打点数据属于默认 domainmsprof 侧以default标识。步骤 4自定义 domain 打点。当业务中存在多个逻辑阶段如数据预处理、前向计算、梯度更新时可将它们归入不同 domain 以便在采集端按需裁剪mstxDomainHandle_t selfDomain mstxDomainCreateA(self_domain); mstxRangeId domainRangeId mstxDomainRangeStartA(selfDomain, model execute, nullptr); ret aclmdlExecute(modelId, input, output); mstxDomainRangeEnd(selfDomain, domainRangeId);mstxDomainCreateA(self_domain)创建名为self_domain的自定义 domain 并返回其句柄mstxDomainHandle_t后续打点均需携带该句柄以便 msprof 将事件归入对应 domain。mstxDomainRangeEnd(selfDomain, domainRangeId)在结束时同时传入 domain 句柄与 range id完成区间闭合。步骤 5/6释放资源与去初始化。打点完成后需释放步骤 2 申请的运行管理资源并调用 AscendCL 去初始化接口保证程序正常退出且数据完整落盘。4.2 打点位置的选择建议从工程实践角度看mstx 打点的信息密度取决于埋点位置的选择常见做法包括在模型执行aclmdlExecute前后打点直接得到模型推理耗时在通信任务如集合通信前后打点评估多卡并行下的通信开销在数据预处理、后处理等 host 侧代码段打点定位 host 瓶颈将不同阶段的打点归入不同 domain配合采集参数按需输出。五、采集与结果解析msprof 命令打点代码就绪后需使用 msprof 工具采集 mstx 数据。相关命令格式与参数详见 采集msproftx数据。5.1 命令格式登录运行环境执行如下命令msprof [options] app 或 msprof [options] --applicationapp采集 mstx 数据必须传入用户程序app因为打点事件产生于被采集程序的运行过程。5.2 关键参数参数必选/可选说明--msproftx必选控制 msproftx/mstx 用户程序和上层框架输出性能数据的开关可选on或off默认值为off。采集 mstx 数据时必须配置为on。--mstx-domain-include可选只输出指定 domain 的数据。填写mstxDomainCreateA接口的 name多个 domain 用逗号隔开default表示默认 domain。需搭配--msproftxon。与--mstx-domain-exclude互斥。--mstx-domain-exclude可选过滤掉指定 domain 的数据。填写规则与 include 相同需搭配--msproftxon。与--mstx-domain-include互斥。domain 参数的完整规则依据 采集msproftx数据 与 PROFILING_OPTIONS 环境变量说明若 include 与 exclude 均不配置采集所有 domain 数据若配置了程序中不存在的 domain采集结果中无该 domain 的数据include 与 exclude 不可同时配置。5.3 使用示例msprof --msproftxon /home/projects/MyApp/out/main采集完成后在--output指定的目录下生成PROF_XXX目录存放自动解析后的性能数据其中即包含 mstx Range 事件的时间跨度数据。5.4 参数约束的源码验证上述参数约束并非仅存在于文档而是有明确的源码实现。在 msprof 的命令行参数解析与校验代码 input_parser.cpp 中--msproftx、--mstx-domain-include、--mstx-domain-exclude三个参数被分别解析并写入采集参数结构体校验逻辑要求当--msproftx不为on时若配置了 include/exclude 参数则报错Argument --mstx-domain-include/--mstx-domain-exclude must be used with --msproftxon.同时校验 include 与 exclude 不能同时配置否则报错Argument --mstx-domain-include and --mstx-domain-exclude ...。此外参数注册表中对该两个 domain 参数的描述也明确了default用于过滤默认 domain、仅当--msproftxon时生效、二者不可同时设置。这与文档描述完全一致开发者在使用时可放心依赖此约束。六、源码级原理mstx 数据在 msprof 侧如何流转为了让读者对 mstx API 有更深入的理解下面结合仓库源码说明打点数据从用户程序到性能文件的流转路径。从代码结构看mstx 在 msprof 侧由三部分协作完成6.1 注入机制与函数表mstx 采用函数表注入的方式与 msprof 交互。mstx_inject.h 声明了InitInjectionMstx(MstxGetModuleFuncTableFunc)与GetModuleTableFunc(...)等注入入口mstx_def.h 中定义了模块枚举PROF_MODULE_MSPROF、PROF_MODULE_MSPTI与函数表类型MstxFuncTable。可以推断用户程序中的mstxRangeStartA等调用实际通过注入的函数表路由到 msprof 侧对应的处理函数从而将打点事件送入采集链路。6.2 Domain 管理mstx_domain_mgr.h 中的MstxDomainMgr负责 domain 的注册与管理每个 domain 以nameHash名称哈希作为内部标识CreateDomainHandle/DestroyDomainHandle管理句柄生命周期mstxDomainAttr结构体中的enabled标志默认置为true当该 domain 出现在--mstx-domain-exclude列表、或不在--mstx-domain-include列表中时会被置为false源码注释明确说明此逻辑SetMstxDomainsEnabled接收 include/exclude 配置并据此批量设置各 domain 的启用状态IsDomainEnabled在事件写入前做过滤判断。这正是--mstx-domain-include/--mstx-domain-exclude能够精确裁剪输出数据的底层实现。6.3 数据处理器与环形缓冲mstx_data_handler.h 中的MstxDataHandler是 mstx 事件的实际消费者数据类型枚举MstxDataType区分DATA_MARK标记、DATA_RANGE_START区间起点、DATA_RANGE_END区间终点内部使用容量为 512 的环形缓冲RingBufferMsprofTxInfoRING_BUFFER_DEFAULT_CAPACITY 512暂存事件由独立线程消费并上报Flush/ReportDataSaveMstxData在写入前携带domainNameHash与MstxDomainMgr::IsDomainEnabled配合完成 domain 过滤Start接口接收mstxDomainInclude/mstxDomainExclude两个字符串参数正是从 msprof 命令行参数传递而来。由此可以梳理出完整的调用链用户程序 mstx 打点注入→ msprof 采集进程 MstxDataHandler → 环形缓冲暂存 → domain 过滤 → 上报写入性能数据文件 → PROF_XXX 目录。理解这条链路有助于在实际使用中判断数据为什么没采到如未开--msproftxon、domain 被过滤、程序异常退出导致缓冲未落盘等。七、常见问题与使用注意事项采集不到 mstx 数据请确认命令中已配置--msproftxon且采集命令携带了用户程序app。未开启开关时msprof 不会采集任何 mstx/msproftx 事件。domain 数据缺失若配置了--mstx-domain-include但填写的 domain 名与mstxDomainCreateA的 name 不一致或该 domain 在程序中未创建则采集结果中不会有该 domain 的数据default关键字用于指代默认 domain。include/exclude 冲突二者不可同时配置msprof 会直接报错拒绝执行。host/device 耗时差异mstxRangeStartA第二个入参传nullptr时只记录 host 侧耗时要评估下发计算/通信任务在 device 侧的耗时必须传入有效的 stream。Range 必须成对闭合mstxRangeStartA与mstxRangeEnd、mstxDomainRangeStartA与mstxDomainRangeEnd必须配对调用未闭合的 Range 会导致耗时统计不完整。八、参考资料mstx API使用示例本文主题文档采集msproftx数据附录Profiling options参数解释PROFILING_OPTIONS 环境变量说明mstx 相关源码mstx_def.h、mstx_inject.h、mstx_domain_mgr.h、mstx_data_handler.h、input_parser.cpp【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考