CANN Runtime 中 mstx 打点与 domain 过滤实践：基于 3_mstx_with_domain 样例的默认/自定义 domain 与 msprof 采集控制

• CANN
• Ascend
• 人工智能
• 任务调度

本篇文章围绕 CANN runtime 开源仓库中的example/5_performance/profiling/3_mstx_with_domain样例展开，系统讲解如何在算子执行流程中使用 MindStudio Tools Extension Library（msTX）接口，在默认 domain 与自定义 domain 中分别完成瞬时事件（Mark）与范围事件（Range）打点，并通过 msprof 的--mstx-domain-include/--mstx-domain-exclude参数按 domain 精确控制采集范围。读完本文后，你将掌握 mstx domain 的创建、打点、销毁的完整生命周期管理方法，以及 domain 级采集过滤的实战命令，从而在性能分析中把自定义业务阶段精确映射到 Profiling 时间线。

样例概述：mstx 在默认 domain 与自定义 domain 中的打点

3_mstx_with_domain是 Profiling 性能分析方向的进阶样例，其核心目的是演示 msTX 接口在默认 domain与自定义 domain两种场景下的打点方式。样例以aclnnAdd向量加法算子为计算载体，在执行流程的各个关键节点插入 mstx 打点，运行完成后可用 msprof 按 domain 有选择地采集这些打点数据。样例整体结构如下：

example/5_performance/profiling/3_mstx_with_domain/ ├── common/ │ ├── util_acl.h # aclInit/Context/Stream 初始化与释放的通用封装 │ └── util_mstx.h # ACL_CALL / CHECK_RET / LOG_PRINT 辅助宏 ├── CMakeLists.txt # 工程构建脚本，链接 ascendcl、nnopbase、msprofiler、opapi 等库 ├── README.md # 样例使用说明（本文讲解对象） ├── README_en.md # 英文版使用说明 ├── mstx_with_domain.cpp # 样例主程序源码 └── run.sh # 一键编译并运行脚本

从源码结构看，样例的运行链路为：main→Init（初始化 acl 资源）→MstxDomainInit（创建自定义 domain）→TestMstxWithDomain（默认 domain 打点 + 执行算子）→DoAclAdd（自定义 domain 打点 + 算子执行）→MstxDomainDeInit（销毁自定义 domain）→DeInit（释放 acl 资源）。

产品支持情况

本样例支持以下产品（README 声明）：

需要说明的是，样例 README 中的产品支持表仅列出当前样例已完成验证或已明确声明支持的产品（参见 example/README.md 中的"产品支持表说明"），未在表格中列出的产品不代表不支持；若某产品明确不支持，会以×标识。因此在实际使用前，建议结合自身硬件型号与 CANN 版本确认 mstx 组件的可用性。

环境准备与 msTX 依赖检查

设置 CANN 环境变量

编译运行样例前，需要将样例代码放到已安装 CANN 软件的环境中，并加载环境变量：

# ${install_root} 替换为 CANN 安装根目录，默认安装在 /usr/local/Ascend 目录 source ${install_root}/cann/set_env.sh

在example/README.md的环境准备章节中，还额外要求设置ASCEND_INSTALL_PATH：

export ASCEND_INSTALL_PATH=${install_root}/cann

此外，本样例的run.sh脚本会直接读取ASCEND_HOME_PATH环境变量来定位 CANN 安装路径与 msTX 头文件，因此建议一并设置：

export ASCEND_HOME_PATH=${install_root}/cann

这一点在 Profiling 系列的 1_msproftx 样例中也有明确说明：run.sh还会读取ASCEND_HOME_PATH，请一并设置为同一路径。

检查 msTX 组件

本样例依赖 CANN Toolkit 中的 MindStudio Tools Extension Library（msTX）组件。执行以下命令检查当前环境是否存在样例所需的 msTX 头文件：

ls -l "${ASCEND_HOME_PATH}/include/mstx/ms_tools_ext.h"

• 若命令正常显示该文件信息，表示当前环境已包含样例所需的 msTX 头文件，可以继续编译运行。
• 若命令提示文件不存在，请按以下方式处理：
  • 确认ASCEND_HOME_PATH指向 CANN Toolkit 的实际安装目录；
  • 若当前环境未安装 msTX，请选择与当前 CANN 软件版本配套的 msTX 版本，并参见《msTX 安装指南》中的"在线安装"或"离线安装"章节完成安装；
  • 若需要升级 msTX，请参见《msTX 安装指南》中的"升级"章节。

安装或升级完成后，重新执行source ${install_root}/cann/set_env.sh加载 CANN 环境变量，并再次执行上述检查，确认头文件可通过${ASCEND_HOME_PATH}/include/mstx/ms_tools_ext.h访问。

切换到样例目录并运行

cd ${git_clone_path}/example/5_performance/profiling/3_mstx_with_domain bash run.sh

run.sh内部完成的工作包括：校验ASCEND_HOME_PATH是否设置、加载${ASCEND_HOME_PATH}/bin/setenv.bash、创建build目录并用 CMake 编译、最终运行可执行文件并将输出通过tee同时打印到终端和output_msg.txt文件（源码见 run.sh）。

从 CMakeLists.txt 可以看到编译期的关键配置：

• 最低 CMake 版本要求为3.16.0；
• 通过ASCEND_HOME_PATH定位 CANN 头文件目录与lib64链接目录；
• 可执行文件mstx_with_domain链接了libascendcl.so、libnnopbase.so、libmsprofiler.so、libopapi.so、libc_sec.so以及dl，其中libmsprofiler.so承载 msprof 采集能力。

源码解析：domain 生命周期与两类打点方式

自定义 domain 的创建与销毁

样例在程序启动后、执行主流程前创建自定义 domain，程序结束时销毁。相关代码位于 mstx_with_domain.cpp：

namespace { aclrtContext context; aclrtStream stream; mstxDomainHandle_t domainRange; std::string g_domainRangeName = "DoAclAdd_Inner"; ... void MstxDomainInit() { domainRange = mstxDomainCreateA(g_domainRangeName.c_str()); } void MstxDomainDeInit() { mstxDomainDestroy(domainRange); } } // namespace int main(int argc, const char** argv) { int32_t deviceId = 0; int ret = Init(deviceId, &context, &stream); if (ret != ACL_SUCCESS) { return ret; } MstxDomainInit(); ret = TestMstxWithDomain(); MstxDomainDeInit(); auto deinitRet = DeInit(deviceId, &context, &stream); return ret != ACL_SUCCESS ? ret : deinitRet; }

这里自定义 domain 的名称被定义为"DoAclAdd_Inner"，mstxDomainCreateA返回mstxDomainHandle_t类型句柄，之后所有"自定义 domain 打点"接口都要以该句柄作为第一个入参。main中的执行顺序为：先Init初始化 acl 资源，再MstxDomainInit创建 domain，执行TestMstxWithDomain，最后MstxDomainDeInit销毁 domain 并DeInit释放资源，体现了"domain 句柄先创建、后使用、最后销毁"的标准生命周期管理。

Init/DeInit的 acl 资源初始化流程封装在 common/util_acl.h 中：aclInit初始化系统资源、aclrtSetDevice设置 Device、aclrtCreateContext创建 Context、aclrtSetCurrentContext设为当前 Context、aclrtCreateStream创建 Stream；释放时按相反顺序调用aclrtDestroyStream、aclrtDestroyContext、aclrtResetDevice、aclFinalize。

默认 domain 打点（mstxMarkA / mstxRangeStartA / mstxRangeEnd）

TestMstxWithDomain演示了默认 domain 下的打点方式——不需要 domain 句柄，直接调用以mstx为前缀的接口：

static int TestMstxWithDomain() { // range with "default" domain start uint64_t id = mstxRangeStartA("TestMstxWithDomain", stream); ACL_CALL(aclrtSetCurrentContext(context)); // mark with "default" domain end mstxMarkA("DoAclAdd Start", stream); ACL_CALL(DoAclAdd(context, stream)); // range with "default" domain end mstxRangeEnd(id); return ACL_SUCCESS; }

其中：

• mstxRangeStartA("TestMstxWithDomain", stream)开启一个默认 domain 下的范围事件（Range），入参为描述字符串和关联 Stream，返回uint64_t类型的范围 id；
• mstxMarkA("DoAclAdd Start", stream)记录默认 domain 下的瞬时事件（Mark），用于标记某个时刻发生的业务动作；
• mstxRangeEnd(id)用起始接口返回的 id 关闭对应的范围事件。

整个TestMstxWithDomain函数体被一对 Range 包裹，恰好覆盖"切换 Context + 触发算子执行"这段业务逻辑，可在时间线上直观看到该阶段的整体耗时。

自定义 domain 打点（mstxDomainMarkA / mstxDomainRangeStartA / mstxDomainRangeEnd）

DoAclAdd内部演示了自定义 domain（即"DoAclAdd_Inner"）下的打点，所有接口均以mstxDomain为前缀，且第一个入参是mstxDomainCreateA返回的句柄：

int DoAclAdd(aclrtContext context, aclrtStream stream) { ... ACL_CALL(CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self)); ACL_CALL(CreateAclTensor(otherHostData, otherShape, &otherDeviceAddr, aclDataType::ACL_FLOAT, &other)); // mark with "DoAclAdd_Inner" domain mstxDomainMarkA(domainRange, "Create alpha aclScalar", stream); alpha = aclCreateScalar(&alphaValue, aclDataType::ACL_FLOAT); ... ACL_CALL(aclnnAddGetWorkspaceSize(self, other, alpha, out, &workspaceSize, &executor)); ... ACL_CALL(aclnnAdd(workspaceAddr, workspaceSize, executor, stream)); // range with "DoAclAdd_Inner" domain start uint64_t id = mstxDomainRangeStartA(domainRange, "After aclnnAdd", stream); ACL_CALL(aclrtSynchronizeStream(stream)); ... // 拷贝结果并打印 // range with "DoAclAdd_Inner" domain end mstxDomainRangeEnd(domainRange, id); return ret; }

自定义 domain 打点与默认 domain 的关键区别在于多一个 domain 句柄参数：mstxDomainMarkA(domainRange, message, stream)记录瞬时事件，mstxDomainRangeStartA(domainRange, message, stream)返回范围 id，mstxDomainRangeEnd(domainRange, id)结束范围。由于这些打点归属于名为"DoAclAdd_Inner"的独立 domain，后续采集时就可以通过 domain 过滤机制把它们与其他打点区分开。

msprof 采集：按 domain 精确控制采集范围

样例运行本身不依赖 msprof，但若要采集 mstx 打点数据，需在运行命令前叠加 msprof 采集前缀。README 提供了三种典型场景：

# 采集所有打点数据，包括默认 domain 和自定义 domain msprof --msproftx=on bash run.sh # 只采集 default domain 的打点数据 msprof --msproftx=on --mstx-domain-include="default" bash run.sh # 采集 default domain 之外的打点数据 msprof --msproftx=on --mstx-domain-exclude="default" bash run.sh

参数使用要点：

• --msproftx=on：开启 msproftx/mstx 打点数据的采集，是采集 mstx 数据的前置开关；
• --mstx-domain-include：只采集指定 domain 的打点数据，未被列出的 domain 不采集；
• --mstx-domain-exclude：采集除指定 domain 之外的打点数据；
• --mstx-domain-include与--mstx-domain-exclude互斥，不可同时配置；
• 如需指定多个 domain，使用逗号隔开，例如--mstx-domain-include="default,DoAclAdd_Inner"。

对照本样例的打点分布可以直观理解过滤效果：

这种按 domain 过滤的能力非常适合将"框架侧打点"与"业务侧打点"分离采集：业务代码可以把自身逻辑放在独立 domain 中，分析时通过 include/exclude 只关注自己关心的那部分时间线，避免被其他 domain 的标记干扰。

采集产物的解析与字段解读

msprof 采集完成后会生成 Profiling 原始数据目录。根据 profiling_artifact_analysis.md 的说明，结果目录由采集方式和路径配置优先级决定：使用msprof命令时--output指定存放目录；未指定--output且设置了ASCEND_WORK_PATH时，结果目录为ASCEND_WORK_PATH/profiling_data；通过msprof [msprof arguments] <app> [app arguments]启动应用且均未配置时，结果保存在当前目录。

解析与导出命令如下：

# 解析原始采集数据 msprof --parse=on --output=<profiling_result_dir> # 导出文本（csv/json summary） msprof --export=on --output=<profiling_result_dir> --summary-format=csv --type=text msprof --export=on --output=<profiling_result_dir> --summary-format=json --type=text # 导出数据库文件 msprof --export=on --output=<profiling_result_dir> --type=db

与本样例强相关的导出字段有两个：

• msproftx message：aclprofMark、aclprofPush、aclprofRangeStart或mstx 标记携带的描述，用于把应用自定义阶段映射到性能时间线；
• Domain：mstx domain 名称，用于按 domain 过滤或归类应用自定义打点。

也就是说，样例中传入 mstx 接口的字符串描述（如"DoAclAdd Start"、"After aclnnAdd"）最终会以msproftx message形式出现在导出结果中，而"default"与"DoAclAdd_Inner"会作为Domain字段值出现。分析时建议先确认打点消息是否出现在导出结果中，再按消息对应的业务阶段分析耗时（参见 profiling_artifact_analysis.md 的"分析建议"章节）。

示例输出与结果验证

编译运行成功后，终端（以及output_msg.txt文件）会输出类似如下的内容：

[INFO]: AscendHome is set to ... ... result[0] is: 1.200000 result[1] is: 2.200000 result[2] is: 3.200000 result[3] is: 5.400000 result[4] is: 6.400000 result[5] is: 7.400000 result[6] is: 9.600000 result[7] is: 10.600000

这些result[i]对应selfHostData = {0,1,2,3,4,5,6,7}与otherHostData = {1,1,1,2,2,2,3,3}按alpha = 1.2f执行alpha * self + other的计算结果（例如1.2 * 1 + 1 = 2.2、1.2 * 5 + 3 = 9.0附近的数值符合预期，实际输出以运行环境为准），说明算子执行与打点流程均正常结束。随后即可按上文 msprof 命令叠加采集，并在导出产物中检索Domain与msproftx message字段，验证默认 domain 与自定义 domain 的打点是否按预期分别采集。

小结

3_mstx_with_domain样例完整覆盖了 msTX 组件在 CANN Runtime 场景中的核心用法：

1. domain 生命周期：mstxDomainCreateA创建自定义 domain 句柄，mstxDomainDestroy销毁，两者严格包住打点区间；
2. 两种打点范式：默认 domain 使用mstxMarkA/mstxRangeStartA/mstxRangeEnd，自定义 domain 使用mstxDomainMarkA/mstxDomainRangeStartA/mstxDomainRangeEnd（需携带 domain 句柄），分别记录瞬时事件与范围事件；
3. domain 级采集过滤：通过msprof --msproftx=on叠加--mstx-domain-include/--mstx-domain-exclude（互斥、逗号分隔多值）实现按 domain 精确采集。

掌握这些能力后，你可以在自己的算子或训练推理程序中以最小侵入方式埋入业务阶段标记，再结合 domain 过滤与 Profiling 产物解读 中的解析导出流程，将性能瓶颈定位到具体的业务阶段，为性能调优提供精确的时间线依据。

• CANN
• Ascend
• 人工智能
• 任务调度