CANN Runtime msproftx 扩展接口完全指南Stamp 事件标记、范围打点与 Tensor 信息上报实战【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime导读本文基于 CANN 开源运行时仓库cann/runtime中的 msproftx 扩展接口文档系统讲解 msproftx 扩展接口的完整使用方式。msproftx 是 CANN Profiling 体系中面向用户的自定义打点能力用于在采集任务中标注瞬时事件Stamp、时间范围Push/Pop、Range以及调用栈信息最终在 Profiling 解析导出的msprof_tx summary数据中呈现。读完本文你将掌握 11 个 msproftx 扩展接口的调用约束与配对关系、如何在aclprofStart/aclprofStop之间组织打点流程、如何在多线程场景下用 Range 接口代替线程栈接口以及如何在 Torch 场景下上报 Tensor 信息并深入理解其底层实现原理。一、msproftx 扩展接口概述msproftxMS-Prof TX即 Profiling 自定义打点扩展是 CANN Runtime Profiling 能力中面向用户的扩展打点接口集。与 19-01 数据采集接口中的aclprofStart/aclprofStop等粗粒度采集控制接口不同msproftx 允许用户在自己的业务代码中插入细粒度的性能标记从而把业务语义例如模型加载、前向传播、算子下发、预处理等阶段映射到采集到的性能数据上。从源码声明看这些接口定义在 include/external/acl/acl_prof.h 中MSVP_PROF_API导出底层实现由 src/dfx/msprof/collector/dvvp/profimpl/adapter/src/msproftx_adaptor.cpp 中的ProfAcl*系列函数转发给 msprof_tx_manager.cpp 中的MsprofTxManager单例完成。调用 msproftx 相关接口的前提是在aclprofCreateConfig创建配置时使能采集类型ACL_PROF_MSPROFTX其值为0x0080ULL定义见 acl_prof.h。1.1 接口全景一览按功能可以把 11 个扩展接口划分为五类分类接口功能定位标记对象管理aclprofCreateStamp/aclprofDestroyStamp创建 / 释放 msproftx 事件标记Stamp对象标记描述aclprofSetStampTraceMessage为 Stamp 携带字符串描述展示在msprof_tx summary中瞬时事件标记aclprofMark/aclprofMarkEx记录瞬时事件Mark后者可下打到指定 Stream时间跨度标记aclprofPush/aclprofPop、aclprofRangeStart/aclprofRangeStop记录一段时间的开始与结束前者线程内嵌套后者可跨线程Tensor 信息上报aclprofRangePushEx/aclprofRangePop在 Torch 场景下上报 Tensor 信息工具函数aclprofStr2Id将字符串如算子名转换为哈希 ID1.2 使用前提与整体调用约束调用时机msproftx 相关接口必须在 aclprofStart 与 aclprofStop 之间调用且aclprofStart的 aclprofConfig 数据需与aclprofStop保持一致采集类型需包含ACL_PROF_MSPROFTX。配对使用aclprofCreateStamp/aclprofDestroyStamp、aclprofPush/aclprofPop、aclprofRangeStart/aclprofRangeStop、aclprofRangePushEx/aclprofRangePop均为成对接口。推荐调用顺序aclprofStart→aclprofCreateStamp→aclprofSetStampTraceMessage→aclprofMark→aclprofPush/aclprofPop或aclprofRangeStart/aclprofRangeStop→aclprofDestroyStamp→aclprofStop。二、标记对象生命周期管理aclprofCreateStamp 与 aclprofDestroyStamp2.1 aclprofCreateStamp创建事件标记void *aclprofCreateStamp()功能说明创建 msproftx 事件标记对象。后续调用aclprofMark、aclprofSetStampTraceMessage、aclprofPush、aclprofRangeStart时都需要把该指针作为入参传入用于标识记录的是同一个事件的时间跨度。返回值返回void*指针成功返回nullptr失败例如未先调用aclprofStart。约束必须与aclprofDestroyStamp配对使用且需在aclprofStart之后调用。源码佐证在 msprof_tx_manager.cpp 的CreateStamp()实现中会先检查MsprofTxManager是否已初始化即是否已通过aclprofStart触发MsprofTxInit未初始化时记录EK0002错误并返回nullptr初始化后从内存池stampPool_-CreateStamp()取出 Stamp。也就是说Stamp 并非普通堆对象而是从预分配的内存池CURRENT_STAMP_SIZE指定池容量中分配这有利于高频打点场景下的内存稳定性。2.2 aclprofSetStampTraceMessage为标记携带描述信息aclError aclprofSetStampTraceMessage(void *stamp, const char *msg, uint32_t msgLen)功能说明为 msproftx 事件标记携带字符串描述。该描述会出现在 Profiling 解析并导出的结果中的msprof_tx summary数据里便于在分析工具中快速识别打点含义例如 model_load_mark、forward_pass_push。参数说明参数名输入/输出说明stamp输入Stamp 指针指代 msproftx 事件标记即aclprofCreateStamp的返回值msg输入Stamp 信息字符串指针msgLen输入字符串长度返回值返回0表示成功返回其他值表示失败参见 aclError。约束需在aclprofCreateStamp与aclprofDestroyStamp之间调用。源码佐证底层 SetStampTraceMessage 实现中定义了MAX_MSG_LEN 128若msgLen 128会报错并返回失败合法的消息通过strncpy_s拷入 Stamp 内部的message字段并补\0。因此建议描述字符串长度控制在 127 字节以内。2.3 aclprofDestroyStamp释放事件标记void aclprofDestroyStamp(void *stamp)功能说明释放 msproftx 事件标记对象将 Stamp 归还内存池而非直接free。实现见 DestroyStamp对nullptr入参会记录EK0006参数错误。参数说明参数名输入/输出说明stamp输入Stamp 指针即aclprofCreateStamp的返回值返回值无。约束与aclprofCreateStamp配对使用且应在aclprofStop之前调用。三、瞬时事件标记aclprofMark 与 aclprofMarkEx3.1 aclprofMark标记瞬时事件aclError aclprofMark(void *stamp)功能说明标记一个瞬时事件如模型加载完成、执行结束。调用后Profiling 自动在 Stamp 中写入当前时间戳并将Event type设置为Mark表示完成一次 msproftx 采集打点。参数说明参数名输入/输出说明stamp输入Stamp 指针即aclprofCreateStamp的返回值返回值返回0表示成功其他值表示失败参见 aclError。约束在aclprofCreateStamp与aclprofDestroyStamp之间调用。源码佐证Mark() 实现中startTime与endTime均取当前系统周期计数值PlatformSysCycleTime()eventType置为EventType::MARK随后通过ReportStampData上报。3.2 aclprofMarkEx带 Stream 的瞬时打点aclError aclprofMarkEx(const char *msg, size_t msgLen, aclrtStream stream)功能说明向指定的 Stream 流上下发打点任务用于标识 Host 侧打点与 Device 侧打点任务之间的对应关系。与aclprofMark相比aclprofMarkEx不依赖 Stamp 对象而是直接把消息字符串与 Stream 关联起来。参数说明参数名输入/输出说明msg输入打点信息字符串指针msgLen输入字符串长度最大支持 127 字符stream输入指定 Stream类型定义参见 aclrtStream返回值返回0表示成功其他值表示失败参见 aclError。约束无。源码佐证实现分两步完成见 MarkEx / MarkExPoint先校验msg、stream非空且strlen(msg) msgLen、消息长度在1 ~ MAX_MESSAGE_LEN-1范围内调用注册的 Runtime 回调rtProfilerTraceExFunc_即rtProfilerTraceEx携带markId、MARKEX_MODEL_ID 0xFFFFFFFF、MARKEX_TAG_ID 11以及 Stream 指针把打点任务下发到 Device 侧将消息拷贝进MsprofTxInfo后通过 reporter 上报。此外源码中定义了MARKEX_MAX_CYCLE 1000与MARKEX_RANGE_TAG_ID 12Range 型打点使用的 tag从源码结构可以推断其用于控制 MarkEx 相关任务索引的循环复用以及区分瞬时/范围两类 Device 打点任务。四、时间跨度标记Push/Pop 与 RangeStart/RangeStop时间跨度标记用于度量一段代码的执行耗时msproftx 提供了两套语义等价、但使用场景不同的接口。4.1 aclprofPush 与 aclprofPop线程内嵌套范围aclError aclprofPush(void *stamp) aclError aclprofPop()功能说明aclprofPush记录时间跨度开始时间aclprofPop记录结束时间。调用aclprofPush后Profiling 自动在 Stamp 中记录开始时间戳并将Event type设置为Push/PopaclprofPop记录结束时间戳。参数说明aclprofPush参数名输入/输出说明stamp输入Stamp 指针即aclprofCreateStamp的返回值返回值均为返回0成功其他值失败参见 aclError。约束与aclprofPop成对使用表示时间跨度的开始与结束在aclprofCreateStamp与aclprofDestroyStamp之间调用不能跨线程调用。若需要跨线程请使用aclprofRangeStart/aclprofRangeStop。源码佐证Push记录startTime后把 Stamp 压入 Stamp 池的线程栈stampPool_-MsprofStampPush(stamp)Pop从栈中弹出 Stamp弹栈失败会报EK0002提示检查aclprofPush/aclprofPop配对写入endTime并将eventType置为PUSH_OR_POP后上报。由于是栈语义Push/Pop 天然支持嵌套即先 Push A 再 Push B、然后依次 Pop B、Pop A可形成嵌套范围。4.2 aclprofRangeStart 与 aclprofRangeStop可跨线程的范围标记aclError aclprofRangeStart(void *stamp, uint32_t *rangeId) aclError aclprofRangeStop(uint32_t rangeId)功能说明aclprofRangeStart记录时间跨度开始aclprofRangeStop记录结束。调用aclprofRangeStart后Profiling 自动在 Stamp 中记录开始时间戳将Event type设置为Start/Stop生成一个进程唯一的 id并把 Stamp 保存在以进程粒度维护的一个 map中。aclprofRangeStop通过该唯一 id 找到对应的 Stamp 并记录结束时间戳。参数说明接口参数名输入/输出说明aclprofRangeStartstamp输入Stamp 指针即aclprofCreateStamp的返回值aclprofRangeStartrangeId输出msproftx 事件标记的唯一标识用于跨线程时区分aclprofRangeStoprangeId输入msproftx 事件标记的唯一标识返回值均为返回0成功其他值失败参见 aclError。约束与aclprofRangeStop成对使用在aclprofCreateStamp与aclprofDestroyStamp之间调用可以跨线程调用这是与 Push/Pop 最核心的区别。源码佐证RangeStart见 RangeStart通过stampPool_-GetIdByStamp(stamp)生成唯一rangeId并置stamp-isEnable 1RangeStop通过stampPool_-GetStampById(rangeId)反查 Stamp若查不到例如传入了未由aclprofRangeStart返回的 id会报EK0001参数错误。rangeId之所以能跨线程正是因为它的保存粒度是进程级 map而非线程栈。4.3 Push/Pop 与 Range 的选择建议维度aclprofPush / aclprofPopaclprofRangeStart / aclprofRangeStop嵌套支持支持栈语义不支持嵌套仅区间对跨线程不支持支持结束定位无参数自动弹栈通过 rangeId 精确定位典型场景单线程内嵌套调用链异步任务、多线程流水线选型原则如果打点发生在同一线程且存在嵌套调用结构如外层前向传播包内层算子分发优先用 Push/Pop如果开始与结束发生在不同线程如生产者-消费者、异步回调必须改用 RangeStart/RangeStop。五、Torch 场景 Tensor 信息上报aclprofRangePushEx / aclprofRangePop 与 aclprofStr2Id5.1 功能定位在aclrt和kernel 启动场景下用户可在算子加载接口前先调用aclprofRangePushEx上报 Tensor 信息之后再调用aclprofRangePop完成 Profiling 数据的上报。调用aclprofRangePushEx后Profiling 判断messageType为MESSAGE_TYPE_TENSOR_INFO时会缓存 Tensor 信息调用aclprofRangePop时再将缓存的 Tensor 信息上报。5.2 aclprofRangePushExaclError aclprofRangePushEx(aclprofEventAttributes *attr)参数说明参数名输入/输出说明attr输入需要上报的 Tensor 信息结构体详见 aclprofEventAttributes返回值返回0成功其他值失败参见 aclError。约束与aclprofRangePop配对使用先aclprofRangePushEx后aclprofRangePop。5.3 aclprofRangePopaclError aclprofRangePop()功能说明上报缓存的 Tensor 信息即aclprofRangePushEx缓存的那份数据。返回值返回0成功其他值失败参见 aclError。约束与aclprofRangePushEx配对使用。5.4 aclprofStr2Id字符串转哈希 IDuint64_t aclprofStr2Id(const char *message)功能说明msproftx 用于将字符串例如算子名转化为哈希 ID。在构造 Tensor 信息上报时用哈希 ID 代替冗长的字符串可以显著降低打点数据的体积。参数说明参数名输入/输出说明message输入字符信息例如算子名返回值返回哈希 ID如果返回uint64_t类型的最大值则说明失败其他值表示成功。约束与aclprofRangePushEx和aclprofRangePop配合使用在aclprofRangePushEx之前调用。5.5 数据结构aclprofEventAttributes 与相关结构体在 acl_prof.h 中定义了与 Tensor 信息上报配套的公共结构体其布局已冻结以保持二进制兼容新字段只能追加在尾部并提升ACL_PROF_EVENT_ATTR_VERSION#define ACL_PROF_EVENT_ATTR_VERSION 1 #define ACL_PROF_TENSOR_DATA_SHAPE_LEN 8 // shape 维度上限 typedef struct aclprofTensor { uint32_t type; // tensor类型, 0: input, 1: output uint32_t format; // format类型: aclFormat uint32_t dataType; // dataType类型 aclDataType uint32_t shapeDim; // shape dim 8 uint32_t shape[ACL_PROF_TENSOR_DATA_SHAPE_LEN]; // tensor内存大小 } aclprofTensor; typedef struct aclprofTensorInfo { uint64_t opNameId; // 通过 uint64_t aclprofStr2Id(const char *message) 得到 uint64_t opTypeId; uint32_t resv; uint32_t tensorNum; uint32_t kernelType; uint32_t blockNums; void* stream; // stream信息 aclprofTensor* tensors; } aclprofTensorInfo; typedef struct aclprofEventAttributes { uint16_t version; uint16_t size; uint32_t messageType; // MESSAGE_TYPE_TENSOR_INFO union Message { aclprofTensorInfo* tensorInfo; } message; } aclprofEventAttributes;关键说明aclprofEventAttributes.messageType只有枚举ACL_PROF_MESSAGE_TYPE_TENSOR_INFO值0一个取值aclprofTensor.shape的维度上限为 8ACL_PROF_TENSOR_DATA_SHAPE_LENshapeDim不得大于 8头文件允许通过定义ACL_PROF_TENSOR_INFO_DEFINED来屏蔽官方结构定义、使用用户自定义结构但前提是保持与上述冻结布局的二进制兼容从源码结构可以推断aclprofStr2Id得到的opNameId/opTypeId与字符串的对应关系会在 Profiling 解析阶段还原从而在msprof_tx summary中展示可读的算子名。六、源码级实现链路与关键细节6.1 调用链总览从仓库源码可以梳理出 msproftx 的完整调用链应用代码 → aclprofCreateStamp / aclprofMark / aclprofPush ... include/external/acl/acl_prof.h 声明 → ProfAclCreateStamp / ProfAclMark / ProfAclPush ... src/dfx/msprof/collector/dvvp/profimpl/adapter/src/msproftx_adaptor.cpp → MsprofTxManager::CreateStamp / Mark / Push ... src/dfx/msprof/collector/dvvp/msprof/msproftx/src/msprof_tx_manager.cpp → stampPool_Stamp 内存池 reporter_数据上报6.2 关键实现要点初始化与生命周期MsprofTxManager::Init()会创建ProfStampPool并初始化容量为CURRENT_STAMP_SIZE字节初始化失败会上报EK0201环境错误UnInit()会依次反初始化 stampPool 与 reporter。manager 的初始化由aclprofStart流程触发MsprofTxInit回调因此文档要求必须在aclprofStart/aclprofStop之间调用是有实现依据的。错误处理所有入参校验失败都会通过MSPROF_INPUT_ERROR上报EK0006参数为空、EK0001参数非法或EK0002接口顺序错误等错误码返回对应的ACL_ERROR_INVALID_PARAM等 aclError。这些错误码在 docs/zh/error_code_ref 中有对应说明。线程信息采集每次上报ReportStampData都会用OsalGetTid()记录当前线程 IDMarkEx还会用OsalGetPid()记录进程 ID——这是跨线程 Range 语义能够在解析端正确归位的关键。Device 侧打点aclprofMarkEx与 Range 型 Device 打点通过rtProfilerTraceEx运行时接口把任务下发到 StreamtagId区分瞬时11与范围12两种打点任务modelId固定为0xFFFFFFFF。6.3 产品支持情况根据接口文档msproftx 扩展接口在以下产品上支持在IPV350 上不支持Ascend 950PR / Ascend 950DT支持Atlas A3 训练系列产品 / Atlas A3 推理系列产品支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品支持Atlas 200I/500 A2 推理产品支持Atlas 推理系列产品支持Atlas 训练系列产品支持IPV350不支持另外从 msproftx_adaptor.cpp 可以看到所有接口在helper host 侧会直接拒绝执行并记录EK0004接口不支持错误即 msproftx 打点只能运行在业务侧进程。七、完整实战示例仓库在 example/5_performance/profiling/1_msproftx 提供了可直接编译运行的 msproftx 样例main.cpprun.sh。该样例除演示瞬时事件aclprofMark外还演示了aclprofPush/aclprofPop的嵌套范围标记与aclprofRangeStart/aclprofRangeStop的非嵌套范围标记便于对照 NVTX 的常见使用模式。7.1 样例核心流程#include acl/acl.h #include acl/acl_prof.h // 创建带描述信息的 Stamp void* stamp aclprofCreateStamp(); aclprofSetStampTraceMessage(stamp, forward_pass_push, strlen(forward_pass_push)); // ... 初始化 Runtime 与 Profiling ... aclprofConfig* config aclprofCreateConfig( deviceIdList, 1, ACL_AICORE_ARITHMETIC_UTILIZATION, nullptr, ACL_PROF_ACL_API | ACL_PROF_TASK_TIME | ACL_PROF_MSPROFTX); // 注意 ACL_PROF_MSPROFTX aclprofStart(config); // 瞬时事件 aclprofMark(loadMark); // 非嵌套范围可跨线程 uint32_t rangeId 0; aclprofRangeStart(preprocessRange, rangeId); // ... 预处理逻辑 ... aclprofRangeStop(rangeId); // 嵌套范围线程内 aclprofPush(outerRangePush); aclprofPush(innerRangePush); // ... 内层逻辑 ... aclprofPop(); // ... 外层逻辑 ... aclprofPop(); aclprofStop(config); aclprofDestroyStamp(stamp);7.2 编译与运行环境安装详情以及运行详情见 example 目录下的 README。运行步骤如下# ${install_root} 替换为 CANN 安装根目录默认安装在 /usr/local/Ascend 目录 source ${install_root}/cann/set_env.sh export ASCEND_INSTALL_PATH${install_root}/cann # Profiling 样例的 run.sh 还会读取 ASCEND_HOME_PATH请一并设置为同一路径 export ASCEND_HOME_PATH${install_root}/cann # 编译运行 bash run.sh7.3 样例输出[INFO] -------- Start -------- [INFO] Preprocess range start [INFO] Preprocess range stop [INFO] Nested operator dispatch range start [INFO] Nested operator dispatch range stop [INFO] Model execute start [INFO] Model execute end [INFO] -------- End --------运行完成后采集数据落盘到样例指定的./output目录aclprofInit的第一个参数指定结果路径。在 Profiling 解析并导出结果中可通过msprof_tx summary数据查看本次打点的完整时间线各 Stamp 的描述字符串、事件类型Mark / Push/Pop / Start/Stop、开始与结束时间戳等。7.4 样例中的关键实践点样例的 main.cpp 将创建 Stamp 设置描述封装为CreateStampWithMessage并集中用StampSet管理多个 Stamp结束时统一aclprofDestroyStamp——这是推荐的对象管理方式避免漏释放每个 Stamp 在创建后、使用前均校验非空失败时立即aclprofDestroyStamp清理并返回体现了正确的错误处理范式在打点外围用aclprofGetStepTimestamp(stepInfo, ACL_STEP_START/END, stream)记录 step 边界将业务打点与训练 step 对齐相关接口见 19-01 数据采集接口。八、注意事项与常见问题忘记使能采集类型aclprofCreateConfig的dataTypeConfig必须包含ACL_PROF_MSPROFTX否则打点数据不会被采集样例中为ACL_PROF_ACL_API | ACL_PROF_TASK_TIME | ACL_PROF_MSPROFTX。接口顺序aclprofCreateStamp必须在aclprofStart之后、aclprofDestroyStamp必须在aclprofStop之前违反顺序会得到EK0002类错误。配对与生命周期Push 之后必须 Pop、RangeStart 之后必须 RangeStop、PushEx 之后必须 Pop否则会造成 Stamp 泄漏在栈/map 中或导致后续 Pop 弹栈失败。消息长度aclprofSetStampTraceMessage的消息长度须小于 128 字节源码中MAX_MSG_LEN 128aclprofMarkEx的消息长度最大支持 127 字符超限会返回失败。跨线程限制Push/Pop 不能跨线程跨线程场景请改用 RangeStart/RangeStop其rangeId是进程唯一的并以进程级 map 保存 Stamp。不支持的场景IPV350 产品不支持全部 msproftx 扩展接口helper host 侧调用同样会被拒绝。性能开销Stamp 对象从预分配内存池中分配打点数据通过 reporter 异步上报但仍建议控制打点频率与消息长度避免对热路径产生不必要的开销。九、参考资料msproftx 扩展接口官方文档本文主体来源数据采集接口aclprofStart / aclprofStop 等接口声明与公共结构体定义底层实现MsprofTxManager接口适配层msproftx_adaptor.cppmsproftx 实战样例aclError 错误码说明数据结构说明aclprofEventAttributesProfiling 数据采集指南开发指南【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN Runtime msproftx 扩展接口完全指南：Stamp 事件标记、范围打点与 Tensor 信息上报实战
CANN Runtime msproftx 扩展接口完全指南Stamp 事件标记、范围打点与 Tensor 信息上报实战【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime导读本文基于 CANN 开源运行时仓库cann/runtime中的 msproftx 扩展接口文档系统讲解 msproftx 扩展接口的完整使用方式。msproftx 是 CANN Profiling 体系中面向用户的自定义打点能力用于在采集任务中标注瞬时事件Stamp、时间范围Push/Pop、Range以及调用栈信息最终在 Profiling 解析导出的msprof_tx summary数据中呈现。读完本文你将掌握 11 个 msproftx 扩展接口的调用约束与配对关系、如何在aclprofStart/aclprofStop之间组织打点流程、如何在多线程场景下用 Range 接口代替线程栈接口以及如何在 Torch 场景下上报 Tensor 信息并深入理解其底层实现原理。一、msproftx 扩展接口概述msproftxMS-Prof TX即 Profiling 自定义打点扩展是 CANN Runtime Profiling 能力中面向用户的扩展打点接口集。与 19-01 数据采集接口中的aclprofStart/aclprofStop等粗粒度采集控制接口不同msproftx 允许用户在自己的业务代码中插入细粒度的性能标记从而把业务语义例如模型加载、前向传播、算子下发、预处理等阶段映射到采集到的性能数据上。从源码声明看这些接口定义在 include/external/acl/acl_prof.h 中MSVP_PROF_API导出底层实现由 src/dfx/msprof/collector/dvvp/profimpl/adapter/src/msproftx_adaptor.cpp 中的ProfAcl*系列函数转发给 msprof_tx_manager.cpp 中的MsprofTxManager单例完成。调用 msproftx 相关接口的前提是在aclprofCreateConfig创建配置时使能采集类型ACL_PROF_MSPROFTX其值为0x0080ULL定义见 acl_prof.h。1.1 接口全景一览按功能可以把 11 个扩展接口划分为五类分类接口功能定位标记对象管理aclprofCreateStamp/aclprofDestroyStamp创建 / 释放 msproftx 事件标记Stamp对象标记描述aclprofSetStampTraceMessage为 Stamp 携带字符串描述展示在msprof_tx summary中瞬时事件标记aclprofMark/aclprofMarkEx记录瞬时事件Mark后者可下打到指定 Stream时间跨度标记aclprofPush/aclprofPop、aclprofRangeStart/aclprofRangeStop记录一段时间的开始与结束前者线程内嵌套后者可跨线程Tensor 信息上报aclprofRangePushEx/aclprofRangePop在 Torch 场景下上报 Tensor 信息工具函数aclprofStr2Id将字符串如算子名转换为哈希 ID1.2 使用前提与整体调用约束调用时机msproftx 相关接口必须在 aclprofStart 与 aclprofStop 之间调用且aclprofStart的 aclprofConfig 数据需与aclprofStop保持一致采集类型需包含ACL_PROF_MSPROFTX。配对使用aclprofCreateStamp/aclprofDestroyStamp、aclprofPush/aclprofPop、aclprofRangeStart/aclprofRangeStop、aclprofRangePushEx/aclprofRangePop均为成对接口。推荐调用顺序aclprofStart→aclprofCreateStamp→aclprofSetStampTraceMessage→aclprofMark→aclprofPush/aclprofPop或aclprofRangeStart/aclprofRangeStop→aclprofDestroyStamp→aclprofStop。二、标记对象生命周期管理aclprofCreateStamp 与 aclprofDestroyStamp2.1 aclprofCreateStamp创建事件标记void *aclprofCreateStamp()功能说明创建 msproftx 事件标记对象。后续调用aclprofMark、aclprofSetStampTraceMessage、aclprofPush、aclprofRangeStart时都需要把该指针作为入参传入用于标识记录的是同一个事件的时间跨度。返回值返回void*指针成功返回nullptr失败例如未先调用aclprofStart。约束必须与aclprofDestroyStamp配对使用且需在aclprofStart之后调用。源码佐证在 msprof_tx_manager.cpp 的CreateStamp()实现中会先检查MsprofTxManager是否已初始化即是否已通过aclprofStart触发MsprofTxInit未初始化时记录EK0002错误并返回nullptr初始化后从内存池stampPool_-CreateStamp()取出 Stamp。也就是说Stamp 并非普通堆对象而是从预分配的内存池CURRENT_STAMP_SIZE指定池容量中分配这有利于高频打点场景下的内存稳定性。2.2 aclprofSetStampTraceMessage为标记携带描述信息aclError aclprofSetStampTraceMessage(void *stamp, const char *msg, uint32_t msgLen)功能说明为 msproftx 事件标记携带字符串描述。该描述会出现在 Profiling 解析并导出的结果中的msprof_tx summary数据里便于在分析工具中快速识别打点含义例如 model_load_mark、forward_pass_push。参数说明参数名输入/输出说明stamp输入Stamp 指针指代 msproftx 事件标记即aclprofCreateStamp的返回值msg输入Stamp 信息字符串指针msgLen输入字符串长度返回值返回0表示成功返回其他值表示失败参见 aclError。约束需在aclprofCreateStamp与aclprofDestroyStamp之间调用。源码佐证底层 SetStampTraceMessage 实现中定义了MAX_MSG_LEN 128若msgLen 128会报错并返回失败合法的消息通过strncpy_s拷入 Stamp 内部的message字段并补\0。因此建议描述字符串长度控制在 127 字节以内。2.3 aclprofDestroyStamp释放事件标记void aclprofDestroyStamp(void *stamp)功能说明释放 msproftx 事件标记对象将 Stamp 归还内存池而非直接free。实现见 DestroyStamp对nullptr入参会记录EK0006参数错误。参数说明参数名输入/输出说明stamp输入Stamp 指针即aclprofCreateStamp的返回值返回值无。约束与aclprofCreateStamp配对使用且应在aclprofStop之前调用。三、瞬时事件标记aclprofMark 与 aclprofMarkEx3.1 aclprofMark标记瞬时事件aclError aclprofMark(void *stamp)功能说明标记一个瞬时事件如模型加载完成、执行结束。调用后Profiling 自动在 Stamp 中写入当前时间戳并将Event type设置为Mark表示完成一次 msproftx 采集打点。参数说明参数名输入/输出说明stamp输入Stamp 指针即aclprofCreateStamp的返回值返回值返回0表示成功其他值表示失败参见 aclError。约束在aclprofCreateStamp与aclprofDestroyStamp之间调用。源码佐证Mark() 实现中startTime与endTime均取当前系统周期计数值PlatformSysCycleTime()eventType置为EventType::MARK随后通过ReportStampData上报。3.2 aclprofMarkEx带 Stream 的瞬时打点aclError aclprofMarkEx(const char *msg, size_t msgLen, aclrtStream stream)功能说明向指定的 Stream 流上下发打点任务用于标识 Host 侧打点与 Device 侧打点任务之间的对应关系。与aclprofMark相比aclprofMarkEx不依赖 Stamp 对象而是直接把消息字符串与 Stream 关联起来。参数说明参数名输入/输出说明msg输入打点信息字符串指针msgLen输入字符串长度最大支持 127 字符stream输入指定 Stream类型定义参见 aclrtStream返回值返回0表示成功其他值表示失败参见 aclError。约束无。源码佐证实现分两步完成见 MarkEx / MarkExPoint先校验msg、stream非空且strlen(msg) msgLen、消息长度在1 ~ MAX_MESSAGE_LEN-1范围内调用注册的 Runtime 回调rtProfilerTraceExFunc_即rtProfilerTraceEx携带markId、MARKEX_MODEL_ID 0xFFFFFFFF、MARKEX_TAG_ID 11以及 Stream 指针把打点任务下发到 Device 侧将消息拷贝进MsprofTxInfo后通过 reporter 上报。此外源码中定义了MARKEX_MAX_CYCLE 1000与MARKEX_RANGE_TAG_ID 12Range 型打点使用的 tag从源码结构可以推断其用于控制 MarkEx 相关任务索引的循环复用以及区分瞬时/范围两类 Device 打点任务。四、时间跨度标记Push/Pop 与 RangeStart/RangeStop时间跨度标记用于度量一段代码的执行耗时msproftx 提供了两套语义等价、但使用场景不同的接口。4.1 aclprofPush 与 aclprofPop线程内嵌套范围aclError aclprofPush(void *stamp) aclError aclprofPop()功能说明aclprofPush记录时间跨度开始时间aclprofPop记录结束时间。调用aclprofPush后Profiling 自动在 Stamp 中记录开始时间戳并将Event type设置为Push/PopaclprofPop记录结束时间戳。参数说明aclprofPush参数名输入/输出说明stamp输入Stamp 指针即aclprofCreateStamp的返回值返回值均为返回0成功其他值失败参见 aclError。约束与aclprofPop成对使用表示时间跨度的开始与结束在aclprofCreateStamp与aclprofDestroyStamp之间调用不能跨线程调用。若需要跨线程请使用aclprofRangeStart/aclprofRangeStop。源码佐证Push记录startTime后把 Stamp 压入 Stamp 池的线程栈stampPool_-MsprofStampPush(stamp)Pop从栈中弹出 Stamp弹栈失败会报EK0002提示检查aclprofPush/aclprofPop配对写入endTime并将eventType置为PUSH_OR_POP后上报。由于是栈语义Push/Pop 天然支持嵌套即先 Push A 再 Push B、然后依次 Pop B、Pop A可形成嵌套范围。4.2 aclprofRangeStart 与 aclprofRangeStop可跨线程的范围标记aclError aclprofRangeStart(void *stamp, uint32_t *rangeId) aclError aclprofRangeStop(uint32_t rangeId)功能说明aclprofRangeStart记录时间跨度开始aclprofRangeStop记录结束。调用aclprofRangeStart后Profiling 自动在 Stamp 中记录开始时间戳将Event type设置为Start/Stop生成一个进程唯一的 id并把 Stamp 保存在以进程粒度维护的一个 map中。aclprofRangeStop通过该唯一 id 找到对应的 Stamp 并记录结束时间戳。参数说明接口参数名输入/输出说明aclprofRangeStartstamp输入Stamp 指针即aclprofCreateStamp的返回值aclprofRangeStartrangeId输出msproftx 事件标记的唯一标识用于跨线程时区分aclprofRangeStoprangeId输入msproftx 事件标记的唯一标识返回值均为返回0成功其他值失败参见 aclError。约束与aclprofRangeStop成对使用在aclprofCreateStamp与aclprofDestroyStamp之间调用可以跨线程调用这是与 Push/Pop 最核心的区别。源码佐证RangeStart见 RangeStart通过stampPool_-GetIdByStamp(stamp)生成唯一rangeId并置stamp-isEnable 1RangeStop通过stampPool_-GetStampById(rangeId)反查 Stamp若查不到例如传入了未由aclprofRangeStart返回的 id会报EK0001参数错误。rangeId之所以能跨线程正是因为它的保存粒度是进程级 map而非线程栈。4.3 Push/Pop 与 Range 的选择建议维度aclprofPush / aclprofPopaclprofRangeStart / aclprofRangeStop嵌套支持支持栈语义不支持嵌套仅区间对跨线程不支持支持结束定位无参数自动弹栈通过 rangeId 精确定位典型场景单线程内嵌套调用链异步任务、多线程流水线选型原则如果打点发生在同一线程且存在嵌套调用结构如外层前向传播包内层算子分发优先用 Push/Pop如果开始与结束发生在不同线程如生产者-消费者、异步回调必须改用 RangeStart/RangeStop。五、Torch 场景 Tensor 信息上报aclprofRangePushEx / aclprofRangePop 与 aclprofStr2Id5.1 功能定位在aclrt和kernel 启动场景下用户可在算子加载接口前先调用aclprofRangePushEx上报 Tensor 信息之后再调用aclprofRangePop完成 Profiling 数据的上报。调用aclprofRangePushEx后Profiling 判断messageType为MESSAGE_TYPE_TENSOR_INFO时会缓存 Tensor 信息调用aclprofRangePop时再将缓存的 Tensor 信息上报。5.2 aclprofRangePushExaclError aclprofRangePushEx(aclprofEventAttributes *attr)参数说明参数名输入/输出说明attr输入需要上报的 Tensor 信息结构体详见 aclprofEventAttributes返回值返回0成功其他值失败参见 aclError。约束与aclprofRangePop配对使用先aclprofRangePushEx后aclprofRangePop。5.3 aclprofRangePopaclError aclprofRangePop()功能说明上报缓存的 Tensor 信息即aclprofRangePushEx缓存的那份数据。返回值返回0成功其他值失败参见 aclError。约束与aclprofRangePushEx配对使用。5.4 aclprofStr2Id字符串转哈希 IDuint64_t aclprofStr2Id(const char *message)功能说明msproftx 用于将字符串例如算子名转化为哈希 ID。在构造 Tensor 信息上报时用哈希 ID 代替冗长的字符串可以显著降低打点数据的体积。参数说明参数名输入/输出说明message输入字符信息例如算子名返回值返回哈希 ID如果返回uint64_t类型的最大值则说明失败其他值表示成功。约束与aclprofRangePushEx和aclprofRangePop配合使用在aclprofRangePushEx之前调用。5.5 数据结构aclprofEventAttributes 与相关结构体在 acl_prof.h 中定义了与 Tensor 信息上报配套的公共结构体其布局已冻结以保持二进制兼容新字段只能追加在尾部并提升ACL_PROF_EVENT_ATTR_VERSION#define ACL_PROF_EVENT_ATTR_VERSION 1 #define ACL_PROF_TENSOR_DATA_SHAPE_LEN 8 // shape 维度上限 typedef struct aclprofTensor { uint32_t type; // tensor类型, 0: input, 1: output uint32_t format; // format类型: aclFormat uint32_t dataType; // dataType类型 aclDataType uint32_t shapeDim; // shape dim 8 uint32_t shape[ACL_PROF_TENSOR_DATA_SHAPE_LEN]; // tensor内存大小 } aclprofTensor; typedef struct aclprofTensorInfo { uint64_t opNameId; // 通过 uint64_t aclprofStr2Id(const char *message) 得到 uint64_t opTypeId; uint32_t resv; uint32_t tensorNum; uint32_t kernelType; uint32_t blockNums; void* stream; // stream信息 aclprofTensor* tensors; } aclprofTensorInfo; typedef struct aclprofEventAttributes { uint16_t version; uint16_t size; uint32_t messageType; // MESSAGE_TYPE_TENSOR_INFO union Message { aclprofTensorInfo* tensorInfo; } message; } aclprofEventAttributes;关键说明aclprofEventAttributes.messageType只有枚举ACL_PROF_MESSAGE_TYPE_TENSOR_INFO值0一个取值aclprofTensor.shape的维度上限为 8ACL_PROF_TENSOR_DATA_SHAPE_LENshapeDim不得大于 8头文件允许通过定义ACL_PROF_TENSOR_INFO_DEFINED来屏蔽官方结构定义、使用用户自定义结构但前提是保持与上述冻结布局的二进制兼容从源码结构可以推断aclprofStr2Id得到的opNameId/opTypeId与字符串的对应关系会在 Profiling 解析阶段还原从而在msprof_tx summary中展示可读的算子名。六、源码级实现链路与关键细节6.1 调用链总览从仓库源码可以梳理出 msproftx 的完整调用链应用代码 → aclprofCreateStamp / aclprofMark / aclprofPush ... include/external/acl/acl_prof.h 声明 → ProfAclCreateStamp / ProfAclMark / ProfAclPush ... src/dfx/msprof/collector/dvvp/profimpl/adapter/src/msproftx_adaptor.cpp → MsprofTxManager::CreateStamp / Mark / Push ... src/dfx/msprof/collector/dvvp/msprof/msproftx/src/msprof_tx_manager.cpp → stampPool_Stamp 内存池 reporter_数据上报6.2 关键实现要点初始化与生命周期MsprofTxManager::Init()会创建ProfStampPool并初始化容量为CURRENT_STAMP_SIZE字节初始化失败会上报EK0201环境错误UnInit()会依次反初始化 stampPool 与 reporter。manager 的初始化由aclprofStart流程触发MsprofTxInit回调因此文档要求必须在aclprofStart/aclprofStop之间调用是有实现依据的。错误处理所有入参校验失败都会通过MSPROF_INPUT_ERROR上报EK0006参数为空、EK0001参数非法或EK0002接口顺序错误等错误码返回对应的ACL_ERROR_INVALID_PARAM等 aclError。这些错误码在 docs/zh/error_code_ref 中有对应说明。线程信息采集每次上报ReportStampData都会用OsalGetTid()记录当前线程 IDMarkEx还会用OsalGetPid()记录进程 ID——这是跨线程 Range 语义能够在解析端正确归位的关键。Device 侧打点aclprofMarkEx与 Range 型 Device 打点通过rtProfilerTraceEx运行时接口把任务下发到 StreamtagId区分瞬时11与范围12两种打点任务modelId固定为0xFFFFFFFF。6.3 产品支持情况根据接口文档msproftx 扩展接口在以下产品上支持在IPV350 上不支持Ascend 950PR / Ascend 950DT支持Atlas A3 训练系列产品 / Atlas A3 推理系列产品支持Atlas A2 训练系列产品 / Atlas A2 推理系列产品支持Atlas 200I/500 A2 推理产品支持Atlas 推理系列产品支持Atlas 训练系列产品支持IPV350不支持另外从 msproftx_adaptor.cpp 可以看到所有接口在helper host 侧会直接拒绝执行并记录EK0004接口不支持错误即 msproftx 打点只能运行在业务侧进程。七、完整实战示例仓库在 example/5_performance/profiling/1_msproftx 提供了可直接编译运行的 msproftx 样例main.cpprun.sh。该样例除演示瞬时事件aclprofMark外还演示了aclprofPush/aclprofPop的嵌套范围标记与aclprofRangeStart/aclprofRangeStop的非嵌套范围标记便于对照 NVTX 的常见使用模式。7.1 样例核心流程#include acl/acl.h #include acl/acl_prof.h // 创建带描述信息的 Stamp void* stamp aclprofCreateStamp(); aclprofSetStampTraceMessage(stamp, forward_pass_push, strlen(forward_pass_push)); // ... 初始化 Runtime 与 Profiling ... aclprofConfig* config aclprofCreateConfig( deviceIdList, 1, ACL_AICORE_ARITHMETIC_UTILIZATION, nullptr, ACL_PROF_ACL_API | ACL_PROF_TASK_TIME | ACL_PROF_MSPROFTX); // 注意 ACL_PROF_MSPROFTX aclprofStart(config); // 瞬时事件 aclprofMark(loadMark); // 非嵌套范围可跨线程 uint32_t rangeId 0; aclprofRangeStart(preprocessRange, rangeId); // ... 预处理逻辑 ... aclprofRangeStop(rangeId); // 嵌套范围线程内 aclprofPush(outerRangePush); aclprofPush(innerRangePush); // ... 内层逻辑 ... aclprofPop(); // ... 外层逻辑 ... aclprofPop(); aclprofStop(config); aclprofDestroyStamp(stamp);7.2 编译与运行环境安装详情以及运行详情见 example 目录下的 README。运行步骤如下# ${install_root} 替换为 CANN 安装根目录默认安装在 /usr/local/Ascend 目录 source ${install_root}/cann/set_env.sh export ASCEND_INSTALL_PATH${install_root}/cann # Profiling 样例的 run.sh 还会读取 ASCEND_HOME_PATH请一并设置为同一路径 export ASCEND_HOME_PATH${install_root}/cann # 编译运行 bash run.sh7.3 样例输出[INFO] -------- Start -------- [INFO] Preprocess range start [INFO] Preprocess range stop [INFO] Nested operator dispatch range start [INFO] Nested operator dispatch range stop [INFO] Model execute start [INFO] Model execute end [INFO] -------- End --------运行完成后采集数据落盘到样例指定的./output目录aclprofInit的第一个参数指定结果路径。在 Profiling 解析并导出结果中可通过msprof_tx summary数据查看本次打点的完整时间线各 Stamp 的描述字符串、事件类型Mark / Push/Pop / Start/Stop、开始与结束时间戳等。7.4 样例中的关键实践点样例的 main.cpp 将创建 Stamp 设置描述封装为CreateStampWithMessage并集中用StampSet管理多个 Stamp结束时统一aclprofDestroyStamp——这是推荐的对象管理方式避免漏释放每个 Stamp 在创建后、使用前均校验非空失败时立即aclprofDestroyStamp清理并返回体现了正确的错误处理范式在打点外围用aclprofGetStepTimestamp(stepInfo, ACL_STEP_START/END, stream)记录 step 边界将业务打点与训练 step 对齐相关接口见 19-01 数据采集接口。八、注意事项与常见问题忘记使能采集类型aclprofCreateConfig的dataTypeConfig必须包含ACL_PROF_MSPROFTX否则打点数据不会被采集样例中为ACL_PROF_ACL_API | ACL_PROF_TASK_TIME | ACL_PROF_MSPROFTX。接口顺序aclprofCreateStamp必须在aclprofStart之后、aclprofDestroyStamp必须在aclprofStop之前违反顺序会得到EK0002类错误。配对与生命周期Push 之后必须 Pop、RangeStart 之后必须 RangeStop、PushEx 之后必须 Pop否则会造成 Stamp 泄漏在栈/map 中或导致后续 Pop 弹栈失败。消息长度aclprofSetStampTraceMessage的消息长度须小于 128 字节源码中MAX_MSG_LEN 128aclprofMarkEx的消息长度最大支持 127 字符超限会返回失败。跨线程限制Push/Pop 不能跨线程跨线程场景请改用 RangeStart/RangeStop其rangeId是进程唯一的并以进程级 map 保存 Stamp。不支持的场景IPV350 产品不支持全部 msproftx 扩展接口helper host 侧调用同样会被拒绝。性能开销Stamp 对象从预分配内存池中分配打点数据通过 reporter 异步上报但仍建议控制打点频率与消息长度避免对热路径产生不必要的开销。九、参考资料msproftx 扩展接口官方文档本文主体来源数据采集接口aclprofStart / aclprofStop 等接口声明与公共结构体定义底层实现MsprofTxManager接口适配层msproftx_adaptor.cppmsproftx 实战样例aclError 错误码说明数据结构说明aclprofEventAttributesProfiling 数据采集指南开发指南【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考