使用asys命令行工具抓取报告

Asight Systems命令行工具asys（以后简称asys），可以在不使用GUI工具的情况下对目标应用进行性能分析数据的采集，并输出报告。此报告可以拷贝到其它系统，后续由GUI工具进行分析。

asys主要功能有：

• 采集跟踪信息

  • 支持采集CUDA/cuDNN/cuBLAS/NVTX/OSRT API执行信息。

  • 支持采集PPU设备上Kernel执行和内存操作信息，支持CPU侧和PPU侧信息关联。

  • 支持采集PCCL通信过程执行信息。

  • 支持采集CUDA/OSRT API 调用栈。

  • 支持采集CPU调度信息，支持采集CPU执行时调用栈信息，支持基于调用栈统计函数耗时占比。

  • 支持采集PPU侧和CPU侧内存使用信息。

  • 支持采集网卡设备吞吐量等指标。

• 采集过程控制

  • 支持控制采集时长，支持延迟启动跟踪采集，支持手动打断采集过程。

  • 支持通过NVTX range指定采集范围。

  • 支持通过CUDA profiler API ( cudaProfilerStart/Stop ) 指定采集范围。

  • 支持循环触发跟踪采集，支持指定循环次数。

  • 支持自动生成报告名称，支持通过宏组装报告名。

  • 支持自定义应用运行环境，可配置应用运行时环境变量，可控制应用打印输出。

  • 支持采集daemon方式应用程序，可指定等待应用结束方式。

  • 支持长时间采集轮转生成报告文件。

• 交互式采集跟踪

  • 支持分别控制应用启动和跟踪采集（start/stop/launch/shutdown子命令）。

  • 支持应用运行过程中多次启动和停止跟踪采集。

  • 支持多个采集过程共存，支持查看采集过程列表。

  • 支持附着到已启动的应用中采集跟踪信息（attach子命令）。

• 支持数据统计分析后处理

  • 支持设备内存使用分组统计。

  • 支持PPU时间利用率统计分析。

asys的环境配置请参见配置asys命令行工具。

可以通过asys -h命令查看帮助。asys支持多个子命令，用于支持多样化的跟踪采集方式：

root@0b0f55fa89fd:~# asys -h

usage: asys [--version] [--help] <command> [<args>] [application] [<application args>]

The most commonly used asys commands are:
profile       Run an application and capture its profile into a asysrep file.
attach        Attach to process and capture its profile into a asysrep file.
launch        Launch an application ready to be profiled.
start         Start a profiling session.
stop          Stop a profiling session and capture its profile into a asysrep file.
cancel        Cancel a profiling session and discard any collected data.
shutdown      Disconnect launched processes from the profiler and shutdown the profiler.
sessions      List active sessions.
status        Provide current status of CLI or the collection environment.
export        Export asysrep file into another format.
stats         Generate statistics from an existing asysrep or SQLite file.
analyze       Identify optimization opportunities in a asysrep file.

Use 'asys --help <command> ' for more information about a specific command.

若希望查看子命令的帮助信息，可通过asys <sub_command> -h的方式进行查询，例如查询profile子命令的使用帮助，可执行:

asys profile -h

此外，若希望查看当前安装的asys的版本信息，可执行：

asys -v

1. 采集跟踪信息

可以通过执行asys profile命令，指定跟踪项，运行应用程序，并生成跟踪报告。

profile子命令的使用方式为：asys profile [option] <application> [application args]

1.1 指定跟踪项

asys支持通过--trace或者-t选项指定开启的跟踪类型（跟踪项），多个跟踪项之间通过,分隔。 例如：

asys profile -t hggc,hgtx,acblas -o baseline python test_linear.py

• -t hggc,hgtx,acblas指定开启的跟踪项：hggc/hgtx/acblas。

• -o baseline指定输出报告名称（不需要指定后缀名）。

• python test_linear.py运行应用程序。

在应用程序运行结束后，或者输入Ctrl + C打断后，asys会生成对应的跟踪报告（本例中：baseline.asysrep），可以在Asight Systems中查看报告内容。

2. 控制采集过程

2.1 采集时间控制

可以通过--delay或者-y选项指定应用程序启动到开始跟踪采集的时延，可通过--duration或者 -d选项指定跟踪采集的时长，超时后停止应用，并生成报告，例如：

asys profile -t hggc --delay 2 --duration 3 python test_linear.py

• --delay 2启动应用后，延时2秒后开始采集。

• --duration 3采集时长3秒，超时后停止应用并生成报告。

最终采集过程执行流程如下图：

提示：若希望跟踪采集超时结束后不停止应用，可以用--kill none选项。

2.2 事件触发跟踪采集

可以通过在应用程序插入指定事件的方式来指定采集范围，并在asys中指定采集开始和结束的触发事件，以精确控制跟踪抓取范围。

asys支持两种触发方式，通过 --capture-range或者 -c选项指定，对应触发事件介绍如下：

举例：使用hggcProfilerApi作为事件触发，抓取指定代码范围的跟踪，应用代码中插入事件API：cudaProfilerStart/ cudaProfilerStop。

cudaProfilerStart(); // profile start
DoProcess();
cudaProfilerStop(); // profile stop
DoOtherProcess();

asys profile -t hggc -c hggcProfilerApi cuda_test

• -c hggcProfilerApi在cudaProfilerStart开始时启动跟踪抓取，在cudaProfilerStop停止时停止跟踪抓取，应用结束。（本例中仅抓取DoProcess执行过程中的跟踪。）

Tips：当hggcProfilerStart和hggcProfilerStop在采集过程中多次出现时，比如start两次后stop，asys将生效第一次出现的start和第一次出现的stop，以确定采集时间范围。

举例：使用hgtx作为事件触发，抓取指定代码范围的跟踪，应用代码中插入nvtx range，名称为DoProcess。

for (int index = 0; index < 5; ++index) {
    nvtxRangePushA("DoProcess"); // start
    DoProcess();
    nvtxRangePop(); // stop
}

asys profile -t hggc,hgtx -c hgtx -p DoProcess cuda_test

• -c hgtx指定使用HGTX/NVTX作为事件触发源。

• -p DoProcess指定HGTX/NVTX range名称，本例中range名称为DoProcess，domain为默认domain。DoProcessrange开始时启动跟踪抓取，range结束时停止跟踪抓取，应用结束。

当使用HGTX/NVTX作为事件触发源时，--hgtx-capture或者-p选项支持多种方式指定domain和range匹配模板：

无论触发方式为hggcProfilerApi还是hgtx，asys均支持事件多次触发（每次触发生成一份报告），以及指定触发事件结束后的行为，通过--capture-range-end选项进行控制：

循环采集跟踪举例如下，循环采集2次跟踪，生成2个报告，随后应用程序停止：

asys profile -t hggc,hgtx -c hgtx -p DoProcess --capture-range-end repeat-shutdown:2 cuda_test

• -c hgtx指定使用HGTX/NVTX作为事件触发源。

• -p DoProcess指定HGTX/NVTX range名称，本例中range名称为DoProcess。

• --capture-range-end repeat-shutdown:2循环触发2次跟踪采集，随后应用程序停止。

Tips：当--capture-range-end为repeat[:N]或repeat-shutdown:N时，若应用程序中触发停止事件和下个触发开始事件间隔时间较短：

• asys可能无法响应此跟踪开始事件，asys将会在匹配到后续跟踪开始事件后开始跟踪采集。

• 其他进程（可触发事件不同进程）的跟踪数据可能在开始采集初期存在丢失。

2.3 长时间采集报告文件轮转

对于需要长时间跟踪采集的场景，asys支持通过--trace-rotation选项配合--duration选项进行报告文件轮转：

• asys每次采集--duration指定的时间后生成报告文件，并继续启动下一轮跟踪采集。

• 仅保留最近的若干报告文件，保留的文件个数通过--trace-rotation选项指定。

• 可通过--output指定报告名称模板，名称中使用%t参数记录跟踪起始时间，避免报告文件名重复。

例如，指定每30秒生成一份报告文件，保留最近3份报告文件：

asys profile -t hggc --duration 30 --trace-rotation 3 --output test_report_%t cuda_test

• --duration 30指定每次采集时间为30秒。

• --trace-rotation 3指定保留最近3份报告文件。

• --output test_report_%t指定生成报告名称模板，%t被替换为跟踪起始时间，生成文件名举例：test_report_08_09_33.asysrep。

Tips：

1. --trace-rotation选项不支持和--capture-range选项配合使用。

2. 本轮跟踪采集结束，到下一轮跟踪采集开始之间存在短的间隙，这段跟踪数据将不会被采集。

3. asys将持续采集跟踪数据直到应用程序结束，可通过输入Ctrl + C停止应用程序结束跟踪采集。

2.4 指定报告名

asys支持通过--output或者-o选项指定报告名（无需指定后缀，asys会自动添加.asysrep后缀），通过--force-overrite true或者-f true选项允许覆盖同名文件。通过-o选项指定报告名称时，asys支持识别宏变量并替换为对应的值，支持的宏变量格式如下：

举例如下：

asys profile -t hggc -o report_%q{HGGC_DRIVER_CANDIDATE}_%i python test_linear.py

• -o report_%q{HGGC_DRIVER_CANDIDATE}_%i，本例最终生成报告文件为：report_UMD_2.asysrep。

  • %q{HGGC_DRIVER_CANDIDATE}替换为环境变量HGGC_DRIVER_CANDIDATE对应值。

  • %i替换为确保本文件夹相同名称前缀文件不重名的索引值。

Tips：默认-o选项值为report%i，因此默认不指定-o选项时，报告文件也不会覆盖。

2.5 自定义应用运行环境

asys支持指定应用程序运行时的环境配置：

可通过选项--env-var或者-e添加应用执行时的环境变量，多个环境变量通过,分隔。

可通过选项--inherit-environment false或者 -n false指定应用程序运行时不继承系统环境变量。

可通过--show-output false或者-w false禁止应用程序打印输出。

举例如下：

asys profile -e ENABLE_DEBUG=1,LOG_LEVEL=DEBUG -n false -w false python test_linear.py

• -e ENABLE_DEBUG=1,LOG_LEVEL=DEBUG运行应用程序时，配置环境变量ENABLE_DEBUG和LOG_LEVEL。

• -n false运行应用程序时，不继承系统环境变量。

• -w false禁止应用程序打印输出。

2.6 等待应用程序结束

asys支持指定应用程序结束的判断方式，默认是等待应用程序fork出的所有进程结束后，认为应用程序结束。比如daemon方式运行的应用，asys默认等待后台的daemon进程均已结束后，停止跟踪采集。具体等待应用程序结束的方式，通过--wait选项指定：

2.7 系统级跟踪采集

asys采集跟踪数据时，默认采集本应用程序进程树（根进程和子孙进程）的跟踪信息。若当前系统内存在其他背景应用程序抢占CPU侧资源，导致应用程序执行受影响，此类问题仅通过进程树的跟踪信息难以定位。可使用asys采集本操作系统内所有进程的跟踪数据（系统级跟踪），以分析背景应用的影响。

可通过选项--sample或者-s使能系统级跟踪采集，例如：

asys profile -s system-wide -t hggc python test_linear.py

• -s system-wide：采集系统内所有进程的CPU调度跟踪数据。

系统级跟踪采集支持不指定应用程序，不指定应用程序时无法采集应用级跟踪采集项，例如：

asys profile -s system-wide --ppu-metrics-device all --nic-metrics true

• -s system-wide：采集系统内所有进程的CPU调度跟踪数据。

• --ppu-metrics-device all：使能所有PPU设备的metrics采样。

• --nic-metrics true：采集网卡运行指标。

asys支持多种系统级跟踪采集项，例如--ppu-metrics-device等功能，在帮助信息中均标记为System scope。与之对应的，asys支持多种应用级跟踪采集项，例如--trace等功能，在帮助信息中均标记为Application scope。-s选项可通过设置为system-wide或者process-tree可切换CPU调度采集为系统级或者应用级。具体跟踪项类型说明请参见asys profile -h帮助信息。

3. 交互式采集跟踪

在使用asys profile采集跟踪的方式之外，asys支持通过命令单独控制启动应用、开始采集、停止采集和停止应用等行为，允许灵活地控制跟踪抓取行为。

3.1 交互式命令说明

asys支持通过以下子命令控制跟踪采集过程，各个子命令支持的选项和asys profile支持的选项类似，可以通过asys <subcommand> -h查看帮助信息：

通过子命令的配合执行，可以灵活地决定应用运行和跟踪采集的时机。

举例：先启动应用程序，抓取两次跟踪，随后停止应用：

asys launch -t hggc cuda_test
asys start -o test_report1
asys stop
asys start -o test_report2
asys stop
asys shutdown

• asys launch ...启动应用程序。

• asys start ...开始跟踪采集，指定报告文件。

• asys stop停止跟踪采集，执行后应用程序仍在运行，后续可继续执行asys start ...开启新一轮的跟踪采集。

• asys shutdown停止应用程序。

举例：先启动跟踪采集，指定事件触发条件，然后启动应用程序：

asys start -o test_report -c hgtx -p DoProcess
asys launch -t hggc,hgtx cuda_test

• asys start ...启动跟踪采集，通过-c和-p选项指定事件触发条件，跟踪会在应用程序启动后，开始跟踪抓取。

• asys launch ...启动应用程序，由于已通过asys start开启跟踪抓取，asys launch ...在应用启动后即可开始跟踪抓取。跟踪会在匹配到事件触发条件后开始记录。

3.2 多个采集过程共存

asys支持多个采集过程共存，例如多个asys profile或者asys launch / start采集过程同时执行。每个采集过程对应一个session，用于区分多个共存的采集过程，可通过选项创建或者关联一个session。每个session有对应的名称和session ID，多个session之间名称不可相同。

举例：执行asys launch创建一个session，执行asys start时关联此session，指定此session开始跟踪采集。

asys launch -t hggc --session-new test cuda_test
asys start --session test

• --session-new test创建一个名称为test的session。

• --session test关联到名称为test的session。

查看当前存在的采集过程session列表：

asys sessions list

其中ID列为session对应的session ID，用于在--session选项中使用此ID指定session。

若不指定session选项，则默认session名称如下：

• asys profile子命令：session名称profile-<pid>-<application>。

• asys launch / start / stop / cancel / shutdown子命令：session名称[default]。

Tips：多个asys profile子命令，因session名称不同默认可共存。交互式子命令，只允许一个默认名称的session存在。

4. 附着式(attach)跟踪采集 (Beta)

asys支持通过attach附着到应用程序采集跟踪数据，应用程序不需要事先通过asys启动。asys attach支持同时附着到多个应用进程，并支持反复附着到相同应用程序采集数据。asys attach完成采集后不会影响应用程序继续运行。

4.1 Attach跟踪采集说明

使用asys attach附着到多个应用进程采集跟踪，示例如下：

asys attach -t hggc -f true -o attach_report 94644,94923

• -t hggc采集HGGC相关跟踪。

• -f true允许同名报告文件覆盖。

• -o attach_report指定报告名称为attach_report。

• 94644,94923同时附着到PID为94644和94923的进程，多个PID通过,区分。

asys attach执行后开始采集跟踪数据，可通过输入Ctrl + C停止跟踪采集并生成报告文件，或者通过--duration指定采集时长，例如：

asys attach -t hggc --duration 10 94644,94923 

• --duration 10采集10秒后停止跟踪采集，并生成报告，应用程序运行不受影响。

asys attach支持反复附着到应用程序采集跟踪数据，在采集结束后不会停止应用程序。asys attach在停止采集后对应用性能影响小，不干扰应用程序继续运行。

4.2 跟踪采集支持范围

asys attach支持的跟踪采集功能和asys profile类似，可通过执行asys attach -h查看具体支持的功能项。

选项-t支持的各个跟踪项，对应采集的信息内容，参见如下表格：

其他asys attach支持的跟踪采集功能如下：

• 支持--sampleCPU执行信息和--backtrace调用栈采集。

• 支持--python-samplingPython调用栈采集。

• 支持--host-memory-sampling系统内存使用采集。

• 支持--ppu-metrics-device设备运行指标采集。

• 支持--nic-metrics网卡运行指标采集。

• 支持--hggcbacktraceHGGC调用栈采集。

• 支持--hggc-memory-usage设备内存使用采集和锁页内存使用采集。

4.3 attach注意事项

使用asys attach进行跟踪采集时，需要注意如下事项：

• asys attach只支持在x86_64/arm指令集环境中运行。

• asys attach在附着到应用程序的过程中，可能导致应用程序死锁。

• 相同应用进程不支持不同release版本的asys attach混合使用。

asys attach的使用限制如下：

• 暂不支持采集 HGTX / ACDNN / ACBLAS / OSRT / Video 等跟踪数据。

• 不支持采集在attach之前已经实例化的legacy HGGC graph相关跟踪信息。

• 不支持attach到已使用 HGPTI 库的进程。