工具使用

基础使用方式

可以通过执行以下命令，启动msLeaks工具。

• 用户不需要使用命令行指定参数

  msleaks [options] <prog_name> 

• 用户需要使用命令行指定参数
  • 方式一（推荐使用此方式）：user.sh为用户脚本

    msleaks [options] bash user.sh

  • 方式二

    msleaks [options] -- <prog_name> [prog_options]

  

  • 环境变量TASK_QUEUE_ENABLE可自行配置，具体配置可参见《Ascend Extension for PyTorch 环境变量参考》的“TASK_QUEUE_ENABLE”章节。

    当TASK_QUEUE_ENABLE配置为2时，开启task_queue算子下发队列Level 2优化，此时会采集workspace内存。

  • msLeaks工具支持在开放态部署场景下采集内存数据，主要采集HAL类型的内存申请和释放事件，安装开放态部署场景，请参见。

• 当--events=launch，需要采集Aten算子下发与访问事件时，此时需要满足Ascend Extension for PyTorch框架中的PyTorch版本大于或等于2.3.1，才可使用该功能。
• 当--analysis参数取值包含decompose时，leaks_dump_{timestamp}.csv结果件中Attr参数中会包含显存类别和组件名称。
• 当--analysis参数取值包含decompose时，会开启内存分解功能，当前支持对Ascend Extension for PyTorch框架、MindSpore框架和ATB算子框架的内存池进行分类，但是暂不支持对MindSpore框架和ATB算子框架的内存池进行细分类。在Ascend Extension for PyTorch框架下，可支持对aten、weight、gradient、optimizer_state进行细分类，其中weight、gradient、optimizer_state仅限于PyTorch的训练场景（即调用optimizer.step()接口的场景），aten是aten算子中申请的内存，需要同时满足PyTorch版本大于或等于2.3.1，--level参数取值中包含0，--events参数取值中包含alloc，free，access。
• 当参数--level=1，且使用Hugging Face的tokenizers库时，可能会遇到“当前发生进程fork，并行被禁用”的告警提示。这个告警信息本身不会影响功能，可以选择忽略。如果希望避免这类告警，可执行export TOKENIZERS_PARALLELISM=false来关闭并行的行为。
• 当--collect-mode=custom，且使用Python自定义采集接口进行采集数据时，Step内内存分析功能不可用，内存块监测、拆解和低效内存识别功能只对采集范围内的数据可用。

配合mstx打点使用

mstx提供了基础打点能力，结合此能力，msLeaks工具可以进行Step内内存分析和Host侧内存采集，同时msLeaks工具能够在可视化trace中标记打点位置，便于用户定位问题代码行。对于C脚本和Python脚本，mstx打点方式略有不同，可参考《性能调优工具用户指南》中的“mstx API参考”章节内容。

开启msLeaks工具的Host侧内存采集功能后，输出的leaks_dump_{timestamp}.csv结果件中会存在大量Host侧malloc free记录，cpu_trace_{timestamp}.json结果件中也会存在Host侧内存相关信息。

下方以Python脚本示例，展示mstx结合msLeaks工具的使用方式。

• Step内内存分析
  请在训练推理脚本内的Step开始和结束处进行标记，并使用固化信息“step start”标识Step开始，示例如下：

  1 2 3 4 5 6

  import mstx for epoch in range(15): id = mstx.range_start("step start", None) # 标识Step开始并开启Step内内存分析功能 .... .... mstx.range_end(id) # 标识Step结束

• Host侧内存采集

  由于采集整个进程的Host侧内存，会出现落盘文件数据量大、难以解析的情况，因此我们选择通过标识来开启和关闭采集，在所需的Host侧内存操作的代码段前后添加mstx打点，并使用固化信息“report host memory info start”，示例如下：

  1 2 3 4 5

  import mstx id = mstx.range_start("report host memory info start", None) ... ... mstx.range_end(id) # 标识停止采集Host侧内存操作

  

  • 需控制Host侧内存采集的代码长度，避免采集过多数据，以减少内存数据采集的时间并简化后续分析。
  • 在需要的用户程序前可添加PYTHONMALLOC=malloc。

    PYTHONMALLOC=malloc是Python的环境变量，表示不采用Python的默认内存分配器，所有的内存分配均使用malloc，该配置对小内存申请有一定影响。

结果件说明

msLeaks工具进行内存分析后，输出的结果件如表3。

• leaks_dump_{timestamp}.csv文件
  Step内内存分析的结果文件字段解释如表4所示。

  表4 leaks_dump_{timestamp}.csv文件字段及含义

  字段	说明
  ID	事件ID。
  Event	msLeaks记录的事件类型，包括以下几种类型： SYSTEM：系统级事件 MALLOC：内存申请 FREE：内存释放 ACCESS：内存访问 OP_LAUNCH：算子执行 KERNEL_LAUNCH：kernel执行 MSTX：打点
  Event Type	事件子类型。 当Event为SYSTEM时，Event Type包含ACL_INIT和ACL_FINI。 当Event为MALLOC或FREE时，Event Type包含HAL、PTA、MindSpore、ATB、HOST和PTA_WORKSPACE。 当Event为ACCESS时，Event Type包含READ、WRITE和UNKNOWN。 当Event为OP_LAUNCH时，Event Type包含ATEN_START、ATEN_END、ATB_START和ATB_END。 当Event为KERNEL_LAUNCH时，Event Type包含KERNEL_LAUNCH、KERNEL_START和KERNEL_END。 当Event为MSTX时，Event Type包含Mark、Range_start和Range_end。
  Name	与Event值有关，当Event值为以下值时，Name代表不同的含义。当Event值为其余值时，Name的值为N/A。 ACCESS：Name为引发访问的算子名/ID。 OP_LAUNCH：Name为算子名称。 KERNEL_LAUNCH：Name为kernel名称。 MSTX：Name为自定义打点名称。
  Timestamp(ns)	事件发生的时间。
  Process Id	进程号。
  Thread Id	线程号。
  Device Id	设备信息。
  Ptr	内存地址，可以作为标识内存块的id值，一个内存块的生命周期是同一个ptr的malloc到下一次free。
  Attr	事件特有属性，每个事件类型有各自的属性项。具体展示信息如下所示： 当Event为MALLOC或FREE时，会展示以下参数信息： allocation_id：相同的allocation_id属于对同一块内存的操作。 addr：地址。 size：本次申请或者释放的内存大小。 owner：内存块所有者，多级分类时格式为{A}@{B}@{C}.....，仅当Event为MALLOC时，存在此参数。 total：内存池总大小，仅当Event Type为PTA、MindSpore或ATB时，存在此参数。 used：内存池总计二次分配大小，仅当Event Type为PTA、MindSpore或ATB时，存在此参数。 inefficient：表示是否为低效内存，值表示低效类别，其中early_allocation表示过早申请，late_deallocation表示过迟释放，temporary_idleness表示临时闲置。仅当Event为MALLOC，Event Type为PTA或ATB时，存在此参数。 当Event为ACCESS时，会展示以下参数信息： dtype：Tensor的dtype。 shape：Tensor的shape。 size：Tensor的size。 format：Tensor的format。 type：访问内存池类型，例如ATB。 allocation_id：相同的allocation_id属于对同一块内存的操作，仅当Event Type为PTA时，存在此参数。 当Event为OP_LAUNCH，Event Type为ATB_START或ATB_END时，会展示以下参数信息： path：算子在模型中的位置，例如“0_1967120/0/0_GraphOperation/0_ElewiseOperation”，其中包含pid、所属模块名和算子名。 workspace ptr：workspace内存起始地址。 workspace size：workspace内存大小。 当Event为KERNEL_LAUNCH时，会展示以下参数信息： path：kernel在模型中的位置，例如“0_1967120/1/0_GraphOperation/1_ElewiseOperation/0_AddF16Kernel/before”，其中包含pid、所属算子和kernel名，仅当Event Type为KERNEL_START或KERNEL_END时，存在此参数。 streamId：stream编号。 taskId：任务编号。
  Call Stack(Python)	Python调用栈信息（可选）。
  Call Stack(C)	C调用栈信息（可选）。

• {device}_trace_{timestamp}.json文件

  可视化内存信息结果件包含两种json文件，分别为cpu_trace_{timestamp}.json（Host侧可视化结果件）和npux_trace_{timestamp}.json（device侧可视化结果件），其中x代表的是device id，例如npu0_trace_{timestamp}.json。

  

  当--device=cpu时，开启采集cpu内存信息功能，才会生成cpu_trace_{timestamp}.json文件。

  文件可通过Chrome trace（chrome://tracing/）或Perfetto（Perfetto UI）等可视化工具展示，如图1所示。

  图1 Host侧可视化信息
  
  图2 Device侧可视化信息
  
  Host侧和Device侧可视化信息详情如表5，可视化文件和mstx打点信息可以辅助进行内存问题定位和问题代码行确定。

  表5 可视化信息详解

  文件	名称	说明
  Host侧	Process PID	kernelLaunch打点信息。名称中的PID代表的是进程号。
  	memory size	cpu上内存信息。当开启Host侧内存采集功能后，会采集到该参数。
  	pin memory size	hal侧申请的host锁页内存。
  Device侧	Process PID	kernelLaunch打点信息。名称中的PID代表的是进程号。
  	{Framework Name} allocated memory size	对应框架的内存池allocated信息。
  	{Framework Name} reserved memory size	对应框架的内存池reserved信息。
  	Thread TID	各Step的持续时间。名称中的TID代表的是线程号。
  	mstx 0	mstx打点信息。
  	Thread 0	长时间未释放Step间的内存信息。

• memory_compare_{timestamp}.csv文件

  Step间内存对比的结果文件字段解释如表6所示。

  表6 memory_compare_{timestamp}.csv文件字段说明

  字段	说明
  Event	msLeaks记录的对比事件类型，包括OP_LAUNCH和KERNEL_LAUNCH两种类型。
  Name	kernel的名称。
  Device Id	设备类型、卡号。
  Base	input输入的第一个文件路径中的数据。
  Compare	input输入的第二个文件路径中的数据。
  Allocated Memory(byte)	kernel调用前后的内存变化。 如果为N/A，表示不存在该kernel的调用。
  Diff Memory(byte)	Base和Compare的内存相对变化。 当数值为0时，表示该kernel调用所引起的内存变化没有差异。 当数值不为0时，表示该kernel调用所引起的内存变化存在差异。