工具使用

基础使用方式

可以通过执行以下命令，启动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”章节。

表1 命令行参数说明
参数	说明
options	命令行参数，详细参数参见表2。
prog_name	用户脚本名称，需自行保证自定义脚本的安全性。当开启Step间内存对比功能时不需要输入此参数。
prog_options	用户脚本参数，需自行保证自定义脚本参数的安全性。当开启Step间内存对比功能时不需要输入此参数。

表2 参数说明
参数类别	参数	说明	是否必选
通用参数	--help, -h	输出msLeaks帮助信息。	否
	--version, -v	输出msLeaks版本信息。	否
	--steps	选择要采集内存信息的Step ID，须配置为实际Step范围内的整数，可配置1个或多个，当前最多支持配置5个。输入的Step ID以逗号（中英文均可）分割。如果不配置该参数，则默认采集所有Step的内存信息。示例：--steps=1,2,3。	否
	--level	采集信息。可选项有0(op)和1(kernel)，默认值为0(op)，示例：--level=0(op)。 0(op)：采集算子级信息。 1(kernel)：采集kernel级信息。	否
	--events	采集事件。可选项有alloc、free、launch和access，默认值为alloc,free，示例：--events=alloc,free。 alloc：采集内存申请事件。 free：采集内存释放事件。 launch：采集算子/kernel下发事件。 access：采集内存访问事件。	否
	--call-stack	采集调用栈。可选项有python和c，选项后以英文冒号间隔跟随数字，表示采集深度，深度默认值为50，示例：--call-stack=python:50。 python：采集python调用栈。 c：采集c调用栈。	否
	--output	输出件所在目录。如果不输入取值，输出件默认保存在leaksDumpResults目录。示例：--output=/home/projects/output。	否
	--log-level	指定输出日志的级别，可选值有info、warn、error。默认值为warn。	否
内存对比参数	--compare	开启Step间内存数据对比功能。	否
内存对比参数	--input	对比文件所在的绝对目录，需输入基线文件和对比文件的目录，以逗号（中英文均可）分割，仅在compare功能开启时有效。示例：--input=/home/projects/input1,/home/projects/input2。	否

当--events=launch，需要采集Aten算子下发与访问事件时，此时需要满足Ascend Extension for PyTorch框架中的PyTorch版本大于2.3，才可使用该功能。

配合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开始，示例如下：

         
              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”，示例如下：

        
             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。

表3 结果件说明
结果件名称	说明
leaks_dump_{timestamp}.csv	使用Step内内存分析功能时，输出内存信息结果件，并默认保存在leaksDumpResults/dump目录下，具体详情信息可参见•leaks_dump_{timestamp}.csv文件。
{device}_trace_{timestamp}.json	使用Step内内存分析功能时，输出可视化内存信息结果件，并默认保存在leaksDumpResults/trace目录下，具体详情信息可参见•{device}_trace_{timestamp}.json。
stepintercompare_{timestamp}.csv	使用Step间内存对比功能时，输出内存对比信息结果件，记录的是基线内存信息、对比内存信息和对比后的内存差异信息，结果件默认保存在leaksDumpResults/compare目录下，具体详情信息可参见•stepintercompare_{timestamp}.csv文件。

leaks_dump_{timestamp}.csv文件

Step内内存分析的结果文件字段解释如表4所示。

表4 leaks_dump_{timestamp}.csv文件字段及含义
字段	说明
ID	事件ID.
Event	msLeaks记录的事件类型，包括以下几种类型： SYSTEM：系统级事件 MALLOC：内存申请 FREE：内存释放 ACCESS：内存访问 OP_LAUHCH：算子执行 KERNEL_LAUNCH：kernel执行 MARK：打点
Event Type	事件子类型。
Name	与Event值有关，当Event值为以下值时，Name代表不同的含义。当Event值为其余值时，Name的值为N/A。 ACCESS：Name为引发访问的算子名/ID。 OP_LAUHCH：Name为算子名称。 KERNEL_LAUNCH：Name为kernel名称。 MARK：Name为自定义文本。
Timestamp(us)	事件发生的时间。
Process Id	进程号。
Thread Id	线程号。
Device Id	设备信息。
Ptr	内存地址，可以作为标识内存块的id值，一个内存块的生命周期是同一个ptr的malloc到下一次free。
call stack	调用栈。
Attr	事件特有属性，每个事件类型有各自的属性项。

{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代表的是进程号。
	torch allocated memory size	PyTorch内存池allocated信息。
	torch reserved memory size	PyTorch内存池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调用所引起的内存变化存在差异。