工具使用

基础使用方式

可以通过执行以下命令，启动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（表示关闭），1（表示开启，会解析更详细的数据，比如算子名称）。如果单独开启--level，则会解析所有Step的详情，耗时较长，所以建议配合--steps参数一起使用。示例：--level=1，默认值为0。	否
	--output	输出件所在目录。如果不输入取值，输出件默认保存在leaksDumpResults目录。示例：--output=/home/projects/output。	否
	--log-level	指定输出日志的级别，可选值有info、warn、error。默认值为warn。	否
内存对比参数	--compare	开启Step间内存数据对比功能。	否
内存对比参数	--input	对比文件所在的绝对目录，需输入基线文件和对比文件的目录，以逗号（中英文均可）分割，仅在compare功能开启时有效。示例：--input=/home/projects/input1,/home/projects/input2。	否

配合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文件字段及含义
字段	说明
Record Index	msLeaks工具记录事件的index顺序。
Timestamp(us)	事件发生的时间。
Event	msLeaks记录的事件，包括acl的init、finalize，kernelLaunch、malloc、free、PyTorch内存池信息和mstx信息。
Event Type	事件类型。
Process Id	进程号。
Thread Id	线程号。
Device Id	设备类型、卡号。
Kernel Index	当前记录所属kernelLaunch的Index。
Flag	内存的属性标识。
Addr	内存地址。
Size(byte)	内存大小。
Total Allocated(byte)	预留内存中已分配的内存大小。
Total Reserved(byte)	预留的内存大小。

{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 xxx	kernelLaunch打点信息。名称中的xxx代表的是进程号。
	memory size	cpu上内存信息。当开启Host侧内存采集功能后，会采集到该参数。
	pin memory size	hal侧申请的host锁页内存。
Device侧	Process xxx	kernelLaunch打点信息。名称中的xxx代表的是进程号。
	torch allocated memory size	PyTorch内存池allocated信息。
	torch reserved memory size	PyTorch内存池reserved信息。
	Thread xxx	各Step的持续时间。名称中的xxx代表的是线程号。
	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调用所引起的内存变化存在差异。