跳到主要内容

Moore Perf System 用户指南

Moore Perf System 是 Moore Threads SDK 中的关键性能分析工具，帮助开发者在开发和调试过程中识别系统级性能瓶颈，进行有针对性的分析和优化。Moore Perf System 不需要修改应用程序即可启用性能分析。

命令行界面 (CLI)​

Moore Perf System CLI (msys) 提供了一种从命令行分析应用程序的方法，用于在不依赖图形用户界面 (GUI) 的情况下收集目标系统的数据。收集到的数据可以传输到其他系统上进行后续分析。

在目标系统上安装 CLI​

如果您倾向于以非 root 模式运行 CLI（推荐），建议将其安装在您有完全访问权限的目录中。

注意：在 Windows 上，需要以管理员权限运行 CLI。

基本检查​

安装完成后，建议先执行以下命令确认 CLI 可用：

msys --version
msys --help

示例输出：

Moore Perf System Version: 1.8.0-a2d42b1d5

在 Linux 环境中，未正确加载运行库或驱动依赖时，执行部分采集相关命令可能出现类似如下提示：

==PROF== Failed to load libmtperf_target.so and libdrm_mtgpu.so.

这通常表示目标环境尚未满足完整采集依赖。请优先检查 MT GPU 驱动、相关运行库，以及 LD_LIBRARY_PATH 等动态库搜索路径环境变量是否包含所需库路径并已在当前 shell 中生效。

命令行选项​

Moore Perf System 支持两种形式的命令行：

msys [全局选项]

或者

msys <命令> [<命令参数>] [应用程序] [<应用参数>]

所有命令行选项都是区分大小写的。对于命令开关选项：

  • 使用短选项时，参数应该在空格后跟随开关
  • 使用长选项时，开关应该跟随一个等号，然后是参数

全局选项​

短选项长选项描述
-h--help显示帮助菜单
-v--version显示版本

命令概览​

Moore Perf System 命令行界面可以在两种模式下使用。您可以使用特定命令的选项启动应用程序并开始收集；或者，您可以使用交互式 CLI 命令控制应用程序的启动和数据收集。

命令描述
profile运行应用程序并收集事件
launch在交互模式下启动一个准备进行收集的应用程序
start在交互模式下开始配置会话
stop在交互模式下停止配置会话
cancel在交互模式下取消配置会话
sessions list列出活动会话
export将 msys-rep 文件导出为另一种格式
stats从现有的 msys-rep 生成统计数据
analyze在 msys-rep 中识别优化机会

profile 命令​

运行应用程序并收集事件。

语法

msys profile [选项] <应用程序> [<应用参数>]

选项

短选项长选项可能的参数默认描述
--capture-rangenone、musaProfilerApi、hotkeynone设置采集触发方式。musaProfilerApi 表示仅在应用调用 musaProfilerStart 后开始采集；hotkey 表示按下 --hotkey-capture 指定的热键后开始采集，仅适用于图形应用；none 表示忽略 musaProfilerStart/Stop 与热键控制。
--capture-range-endnone、stop、stop-shutdown、repeat[:N]、repeat-shutdown:Nstop-shutdown设置采集区间结束后的行为。仅与 --capture-range 联合使用。
-d--device<设备索引>捕获所有设备设置要采集的设备 ID。多个 ID 应由逗号分隔，无空格。选项参数必须是 --device=help 开关报告的 GPU ID 之一。
--duration<秒>NA以秒为单位设置采集持续时间，必须大于 0。到达指定时长后，目标进程将被终止。
-e--env-varA=B[,C=D...]NA设置环境变量，变量应由逗号分隔且不带空格，例如：-e a=b,c=d。
--gpu-metrics-set<指标 ID> 或 all默认不采集指定 GPU Metrics 采样的指标集。多个 ID 应由逗号分隔，无空格。选项参数必须是 all 或 --gpu-metrics-set=help 报告的索引之一。
-h--help显示 profile 帮助菜单
--hotkey-captureF1 到 F12F12设置触发采集的热键，仅在 --capture-range=hotkey 时生效。
--musa-graph-tracegraph、nodegraph设置 MUSA Graph Trace 粒度。graph 表示整体追踪 graph；node 表示收集 node 活动，但可能带来明显运行时开销。
-o--output<文件名>report#.msys-rep设置输出报告文件名。
--osrt-threshold<纳秒>1000设置 OS Runtime (osrt) API 被追踪的最小执行时长。值远小于 1000 可能导致较大开销和超大结果文件。默认值为 1000（1 微秒）。
-t--tracemusa、opengl、osrt、vulkan、nonemusa,opengl选择要追踪的 API。多个 API 用逗号分隔，不能包含空格。none 表示不追踪任何 API。
-y--delay<秒>NA设置开始采集前的延迟时间，单位为秒。

示例

msys profile --trace=musa,osrt -o report.msys-rep ./my-application
msys profile --capture-range=musaProfilerApi ./my-application
msys profile --capture-range=hotkey --hotkey-capture=F12 ./my-application

launch 命令​

在交互模式下启动一个准备进行收集的应用程序。

语法

msys launch [选项] <应用程序> [<应用参数>]

选项

短选项长选项可能的参数默认描述
-e--env-varA=B[,C=D...]NA设置环境变量，变量应由逗号分隔，无空格。
-h--help显示 launch 帮助菜单
--session[default] 或已有会话名[default]在指定会话中启动应用程序。
--osrt-threshold<纳秒>1000设置 OS Runtime (osrt) API 被追踪的最小执行时长。
-t--tracemusa、opengl、osrt、vulkan、nonemusa,opengl选择要追踪的 API。多个 API 用逗号分隔，不能包含空格。

start 命令​

在交互模式下开始配置会话。

语法

msys start [选项]

选项

短选项长选项可能的参数默认描述
-d--device<设备索引>捕获所有设备设置要采集的设备 ID。多个 ID 应由逗号分隔，无空格。选项参数必须是 --device=help 开关报告的 GPU ID 之一。
--gpu-metrics-set<指标 ID> 或 all默认不采集指定 GPU Metrics 采样的指标集。多个 ID 应由逗号分隔，无空格。选项参数必须是 all 或 --gpu-metrics-set=help 报告的索引之一。
-h--help显示 start 帮助菜单
-o--output<文件名>report#.msys-rep设置输出报告文件名。
--session[default] 或已有会话名[default]在指定会话中开始采集。

执行 msys start 后，如果命令成功，通常会出现类似输出：

Session '[default]' started, use the 'launch' command to launch and profile a target app.

stop 命令​

在交互模式下停止配置会话。

语法

msys stop [选项]

选项

短选项长选项可能的参数默认描述
-h--help显示 stop 帮助菜单
-q--quit无false停止采集后退出应用程序。
--session[default] 或已有会话名[default]停止指定会话中的采集。

执行 msys stop 后，通常会输出报告文件路径，例如：

Stopping...
Report file: /path/to/report1.msys-rep
Stop executed.

cancel 命令​

在交互模式下取消配置会话。

语法

msys cancel [选项]

选项

短选项长选项可能的参数默认描述
-h--help显示 cancel 帮助菜单
-q--quit无false取消采集后退出应用程序。
--session[default] 或已有会话名[default]取消指定会话中的采集。

如果会话不存在，可能出现如下提示：

'[default]' is not active.

sessions list 命令​

列出活动会话。

语法

msys sessions list [选项]

选项

短选项长选项可能的参数默认描述
-h--help显示 sessions list 帮助菜单

示例输出：

NAME      TIME    STATE                     LAUNCH
[default] 00:29   CollectingGlobalOnly      0

如果当前没有活动会话，可能仅显示表头：

NAME    TIME    STATE                     LAUNCH

请注意，sessions 不是一级命令，必须使用完整形式 msys sessions list。

export 命令​

将 .msys-rep 文件导出为其他格式。

语法

msys export [选项] <report file>

选项

短选项长选项可能的参数默认描述
-h--help显示 export 帮助菜单
-f--force-overwriteon/off、yes/no、1/0、true/falsefalse如为 true，则覆盖同名输出文件。
-o--output<文件名>NA设置输出文件名。
-t--typejson、sqlitejson导出类型。json 可用于 chrome://tracing/，sqlite 导出为 sqlite schema。

stats 命令​

从现有的 .msys-rep 生成统计数据。

语法

msys stats [选项] <input-file>

常用选项

短选项长选项可能的参数默认描述
-f--formattable、csv、json控制台默认 table，文件默认 csv指定输出格式；未指定 -o 时输出到控制台，若指定 -f json，控制台输出格式也为 JSON。
-h--help显示 stats 帮助菜单
-o--output<输出路径或文件基名>打印到控制台指定输出方式；若写入文件，则使用 <basename>_<report>.<ext> 形式命名。
-r--report<name[,name...]>默认报告集指定要生成的报告，可使用逗号分隔多个报告。

默认报告集

  • musa_api_sum
  • musa_api_trace
  • musa_gpu_kern_sum
  • musa_gpu_kern_gb_sum
  • musa_gpu_mem_size_sum
  • musa_gpu_mem_time_sum
  • musa_gpu_sum
  • musa_kern_exec_sum
  • musa_api_gpu_sum
  • opengl_api_sum

示例

msys stats report1.msys-rep
msys stats -r musa_gpu_trace report1.msys-rep
msys stats --report musa_gpu_trace,musa_gpu_kern_sum --format csv --output . report1.msys-rep

analyze 命令​

从现有的 .msys-rep 中识别优化机会。

语法

msys analyze [选项] <input-file>

常用选项

短选项长选项可能的参数默认描述
-f--formattable、csv、json控制台默认 table，文件默认 csv指定输出格式；未指定 -o 时输出到控制台，若指定 -f json，控制台输出格式也为 JSON。
-h--help显示 analyze 帮助菜单
-o--output<输出路径或文件基名>打印到控制台指定输出方式。
-r--rule<name[:args...][,name[:args...]...]>默认规则集指定分析规则，可为规则附加参数。
--help-formats[<format_name>|ALL]NA查看输出格式帮助。
--help-rules[<rule_name>|ALL]NA查看规则帮助。
--filter-time[<start_time>]/[<end_time>]全时间范围按时间范围过滤参与分析的事件和记录，时间单位支持 ns、us、ms、s。

默认规则集

  • musa_memcpy_sync
  • musa_memcpy_async
  • musa_memset_sync
  • musa_api_sync
  • musa_gpu_gaps
  • musa_gpu_time_util

示例

msys analyze report1.msys-rep
msys analyze -r musa_memcpy_async:rows=10:start=10ms,musa_gpu_gaps:rows=20 report1.msys-rep
msys analyze --rule musa_memcpy_sync,musa_gpu_gaps --format csv --output . report1.msys-rep

容器和调度器支持​

Docker 容器支持​

Moore Perf System 支持在 Docker 容器中进行性能分析。要在容器中使用 Moore Perf System，需要确保：

  1. 容器具有访问 GPU 的权限。
  2. Moore Perf System 工具已安装在容器内或主机上。
  3. 适当的权限设置以进行性能数据收集。

Direct3D Trace​

Moore Perf System 能够收集 Windows 目标上的 Direct3D 11 和 Direct3D 12 API。

D3D11 API Trace​

Moore Perf System 可以捕获被分析进程中 Direct3D 11 API 调用的信息，包括 D3D11 API 函数的执行时间、性能标记和帧持续时间。

图 8：Direct3D 11 API Trace

D3D12 API Trace​

Direct3D 12 是一个用于 Microsoft Windows 的低开销 3D 图形和计算 API。

Moore Perf System 可以捕获被分析进程中 Direct3D 12 的使用信息，包括 D3D12 API 函数的执行时间、GPU 上执行的相关工作负载、性能标记和帧持续时间。

图 9：Direct3D 12 API Trace

启用 Direct3D Trace​

在 GUI 中，可以通过项目设置页面启用 Direct3D API Trace 功能。选择要 Trace 的 Direct3D API 类型（D3D11 或 D3D12）后，性能分析将自动收集相关的 API 调用信息。

WDDM 队列​

Windows 显示驱动程序模型（WDDM）架构使用队列从 CPU 向 GPU 发送工作包。每个进程中的每个 D3D 设备都与一个或多个上下文关联。被分析应用程序使用的图形、计算和复制命令与上下文关联，批量到命令缓冲区，并推送到与该上下文关联的相关队列中。

图 10：WDDM 队列架构

有关 WDDM 架构的详细信息，请参见 Microsoft 文档。

Vulkan Trace​

Vulkan 是一个低开销、跨平台的 3D 图形和计算 API，面向从 PC 到手机和嵌入式平台的各种设备。Vulkan API 由 Khronos Group 定义。

Moore Perf System 可以捕获被分析进程中 Vulkan API 调用的信息，包括 API 函数名称、执行时间、返回值、函数参数、进程 ID 和线程 ID。

图 11：Vulkan API Trace

启用 Vulkan Trace​

在项目设置中启用 Vulkan Trace 选项后，Moore Perf System 将捕获应用程序中的 Vulkan API 调用，并在时间线上显示相关信息。

MUSA Trace​

基本 MUSA Trace​

Moore Perf System 能够捕获被分析进程中 MUSA 执行的信息。

以下信息可以收集并在报告的时间线上显示：

  • MUSA API Trace — 跟踪应用程序使用的 MUSA Runtime 和 MUSA Driver 调用。使用 MUSA API 的每个线程将作为线程子节点显示在时间线视图左侧的树结构中。

  • MUSA Runtime 调用通常以前缀 musa 开始（例如，musaLaunch）

  • MUSA Driver 调用通常以前缀 mu 开始（例如，muDeviceGetCount）

  • MUSA HW Trace — 跟踪 GPU 上的活动，包括内存操作（例如，主机到设备的内存复制）和 Kernel 执行。你可以展开包含 MUSA HW 节点的进程节点以找到进程中使用的 MUSA 上下文，每个 MUSA 上下文将与其相应的 MUSA Stream 一起显示。Stream 包含 GPU 上的内存操作和 Kernel 执行情况。

图 12：MUSA Trace 时间线

MUSA Graph Trace​

Moore Perf System 能够以 graph 或 node 粒度捕获应用程序中的 MUSA Graph 信息。可以在 CLI 中使用 --musa-graph-trace 选项设置捕获粒度，或在 GUI 中通过设置相应的下拉菜单来完成。

图 13：MUSA Graph Trace 设置

Graph 粒度

当 MUSA Graph Trace 设置为 graph 时，用户可在时间线上看到每个 graph 作为一个元素呈现：

图 14：Graph 粒度追踪

Node 粒度

当 MUSA Graph Trace 设置为 node 时，用户可在时间线上看到每个 graph 下的所有 node：

图 15：Node 粒度追踪

OS Runtime Libraries Trace​

Moore Perf System 支持追踪操作系统运行时库（OS Runtime Libraries）的 API 调用。这可以帮助开发者了解应用程序与操作系统底层库之间的交互。

Locking a Resource​

对于以下加锁/等待类函数，工具会进行特殊处理：如果检测到目标资源已经被其他线程持有、当前调用可能发生阻塞，则即使调用本身较短也会被优先记录；否则通常不会被记录。

pthread_mutex_lock
pthread_rwlock_rdlock
pthread_rwlock_wrlock
pthread_spin_lock
sem_wait

需要注意的是，即使某次调用在进入时被判定为“可能阻塞”，后续也可能只经过很短几个周期就返回；这种情况下，该调用仍然会出现在 trace 中。

OS Runtime Default Function List​

Libc system call wrappers

accept
bind
brk
close
connect
dup
fcntl
ftruncate
ioctl
listen
mmap
mprotect
munmap
openat
poll
pread64
read
recvfrom
recvmsg
sendmsg
shutdown
socket
write
writev

POSIX Threads

pthread_barrier_wait
pthread_cancel
pthread_cond_broadcast
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait
pthread_create
pthread_join
pthread_kill
pthread_mutex_lock
pthread_mutex_timedlock
pthread_mutex_trylock
pthread_rwlock_rdlock
pthread_rwlock_timedrdlock
pthread_rwlock_timedwrlock
pthread_rwlock_tryrdlock
pthread_rwlock_trywrlock
pthread_rwlock_wrlock
pthread_spin_lock
pthread_spin_trylock
pthread_timedjoin_np
pthread_tryjoin_np
pthread_yield
sem_timedwait
sem_trywait
sem_wait

配置 OSRT Trace​

CLI 配置

使用 --osrt-threshold 选项设置 OSRT API 必须执行的最小持续时间（以纳秒为单位）才会被追踪：

msys profile --trace=osrt --osrt-threshold=1000 <application>
  • 阈值范围：1000 ns - 10000000 ns（1 微秒 - 10000 微秒）
  • 默认值：1000 ns（1 微秒）

注意： 值远小于 1000 可能会导致显著的开销，并导致非常大的结果文件。

GUI 配置

在项目设置页面中：

  1. 勾选 Collect OS runtime libraries trace 复选框启用 OSRT Trace
  2. 可选：勾选 Skip if shorter than 并设置时间阈值（单位：微秒）

OpenGL Trace​

可以收集 OpenGL 和 OpenGL ES API 以协助分析 CPU 和 GPU 之间的交互。

图 16：OpenGL Trace 选择 图 17：OpenGL API Trace

在 GUI 中查看报告​

报告可以复制到任何系统，并使用 GUI 进行分析。

打开现有报告​

你可以通过选择 文件 > 打开 并选择 .msys-rep 文件来打开现有文件。

图 18：打开现有报告

导入 ETL 文件​

在 Windows 上，支持导入 .etl 文件。

图 19：导入 ETL 文件

注意： 当加载大型报告（包含超过 3000000 个事件）时，你需要选择一个时间范围并点击 "加载" 按钮以完成加载过程。

图 20：选择时间范围加载大型报告

共享报告文件​

Moore Perf System 生成的报告文件（.msys-rep）可以在不同系统之间共享，便于团队协作分析性能问题。

报告选项卡​

每个打开的报告都会在一个单独的选项卡中显示，方便同时查看和比较多个报告。

概要视图​

此视图提供了性能分析会话的概要信息。它特别适用于审查用于生成此报告的项目配置。

图 21：概要视图

时间线视图​

时间线是一个多功能控件，左侧包含树状层次结构，右侧显示相应的图表。

图 22：时间线视图

层次结构的内容取决于用于收集报告的项目设置。例如，如果某个特定功能未启用，则相应的行将不会显示在时间线上。

缩放和滚动​

在 Moore Perf System GUI 的右上角，你将看到缩放和滚动控制部分：

图 23：时间线缩放和滚动控制

滑块设置屏幕行的垂直大小，放大镜将其重置为原始设置。

在时间线上水平缩放和滚动有很多方法。点击键盘图标打开对话框，解释这些操作。

图 24：时间线操作说明

鼠标悬停在几个项目上时，会显示额外的信息作为工具提示。

图 25：时间线菜单

在事件列表中显示事件​

右键单击时间线行并选择 在事件列表中显示 或 在事件列表中显示所有事件。

图 26：事件视图菜单

点击事件列表中的特定实例将突出显示时间线上的相应事件。

图 27：选择事件

显示标记事件​

标记事件以便稍后在时间线上快速查看。

图 28��：标记事件

显示统计信息​

选择 显示统计信息 以显示 GPU 使用情况信息。

图 29：显示统计信息

固定行​

右键单击并选择 固定行 以固定选定的行。

图 30：固定行

事件列表​

事件列表以表格形式显示跟踪事件。

在事件列表中单击一个项目会自动将时间线视图聚焦到相应的时间线项目，并显示详细的事件信息。

可以搜索和排序视图内容。

使用 Shift 或 Ctrl 启用多选。

右键菜单提供命令，如在时间线上缩放至已选项、标记事件、清除选定事件 和 清除已筛选的事件。

图 31：事件视图底部菜单

统计视图​

下拉框选择统计系统视图以查看详细的统计结果。

图 32：统计视图

专家系统视图​

下拉框选择专家系统视图以查看详细的分析结果。

图 33：专家系统视图

过滤​

输入过滤条件并突出显示行。

图 34：事件视图过滤 图 35：事件视图高级过滤

排序​

点击标题进行排序。

图 36：事件视图排序

多报告时间线视图​

Moore Perf System 支持同时查看多个报告，便于进行性能对比分析。

打开多个报告文件

  1. 选择 文件 > 打开，选择多个 .msys-rep 文件
  2. 在弹出的对话框中选择打开方式：

图 37：打开多个报告文件

  • 单独打开每个报告：在每个标签页中分别打开报告
  • 创建新的多报告视图：在单个视图中对齐显示多个报告

新建多报告视图

选择 文件 > 新建多报告视图 可以创建一个新的空多报告视图，然后添加报告文件进行对比分析。

图 38：多报告时间线视图

功能特点

  • 多个报告的时间线垂直对齐，便于对比
  • 共享相同的时间刻度，可同步缩放和滚动
  • 支持保存多报告视图配置（.msys-multi 文件）以便后续使用

版权所有 2024 摩尔线程，本文档受国际版权法保护。

摩尔线程和摩尔线程徽标是摩尔线程智能科技 (北京)有限责任公司的注册商标。

免责声明

本文档提供有关摩尔线程产品的信息。本文档并未授权任何知识产权的许可，并未以明示或暗示，或以禁止反言或其他方式授予任何知识产权许可。