工具使用

基础使用方式

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

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

  msleaks [options] <prog_name> 

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

    msleaks [options] bash user.sh

  • 方式二

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

  

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

• 当--events=launch，需要采集Aten算子下发与访问事件时，此时需要满足Ascend Extension for PyTorch框架中的PyTorch版本大于或等于2.3，才可使用该功能。
• 当--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，--level参数取值中包含0，--events参数取值中包含alloc，free，access。
• 当参数--level=1，且使用Hugging Face的tokenizers库时，可能会遇到“当前发生进程fork，并行被禁用”的告警提示。这个告警信息本身不会影响功能，可以选择忽略。如果希望避免这类告警，可执行export TOKENIZERS_PARALLELISM=false来关闭并行行为。

配合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执行 MARK：打点
  Event Type	事件子类型。
  Name	与Event值有关，当Event值为以下值时，Name代表不同的含义。当Event值为其余值时，Name的值为N/A。 ACCESS：Name为引发访问的算子名/ID。 OP_LAUNCH：Name为算子名称。 KERNEL_LAUNCH：Name为kernel名称。 MARK：Name为自定义文本。
  Timestamp(ns)	事件发生的时间。
  Process Id	进程号。
  Thread Id	线程号。
  Device Id	设备信息。
  Ptr	内存地址，可以作为标识内存块的id值，一个内存块的生命周期是同一个ptr的malloc到下一次free。
  Attr	事件特有属性，每个事件类型有各自的属性项。
  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。

  文件可通过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间的内存信息。

• stepintercompare_{timestamp}.csv文件

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

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

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