Moore Perf System 用户指南
Moore Perf System 是 Moore Threads SDK 中的关键性能分析工具，帮助开发者在开发和调试过程中识别系统级性能瓶颈，进行有针对性的分析和优化。Moore Perf System 不需要修改应用程序即可启用性能分析。
- 命令行界面 (CLI)
- 图形界面 (GUI)
命令行界面 (CLI)
Moore Perf System CLI (msys) 提供了一种从命令行分析应用程序的方法，用于在不依赖图形用户界面 (GUI) 的情况下收集目标系统的数据。收集到的数据可以传输到其他系统上进行后续分析。
在目标系统上安装 CLI
如果您倾向于以非 root 模式运行 CLI（推荐），建议将其安装在您有完全访问权限的目录中。
注意：在 Windows 上，需要以管理员权限运行 CLI。
命令行选项
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 [选项] <应用程序> [<应用参数>]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -d | --device | <设备索引> | all device | 设置要配置的设备 ID。多个 ID 应由逗号分隔，无空格。选项参数必须是 --device=help 开关报告的 GPU ID 之一。默认捕获所有设备。 |
| --duration | <秒> | NA | 以秒为单位捕获操作持续时间，持续时间必须大于零。当指定的配置持续时间到期时，目标进程将被终止。 | |
| -e | --env-var | A=B | NA | 设置环境变量，变量应由逗号分隔，无空格，例如：-e a=b,c=d |
| --gpu-metrics-set | <指标 ID> | NA | 指定 GPU 指标采样的指标集。多个 ID 应由逗号分隔，无空格。选项参数必须是 all 或 --gpu-metrics-set=help 开关报告的索引之一。默认不捕获 GPU 指标。 | |
| -h | --help | 显示 profile 帮助菜单 | ||
| --hotkey-capture | F1 到 F12 | NA | 触发配置会话的热键 | |
| --musa-graph-trace | graph, node | graph | 如果选择 graph，将整体追踪 MUSA Graph，不收集节点活动。如果选择 node，将收集节点活动，但不整体追踪 MUSA Graph。默认为 graph（如果可用）。 | |
| -o | --out | <文件名> | report#.msys-rep | 设置输出报告文件名。在默认位置生成 report#.msys-rep 文件，如果需要，增加报告编号以避免覆盖任何现有输出文件。 |
| --osrt-threshold | <纳秒> | 1000 | 设置 OS Runtime (osrt) API 必须执行的持续时间（以纳秒为单位）然后才被追踪。值远小于 1000 可能会导致显著的开销。默认为 1000（1 微秒）。 | |
| -t | --trace | none, musa, opengl, osrt, vulkan | musa,opengl | 选择要追踪的 API。可以选择多个 API，用逗号分隔（无空格）。如果选择 none，则不追踪任何 API。 |
| -y | --delay | <秒> | NA | 捕获操作开始延迟，以秒为单位 |
launch 命令
在交互模式下启动一个准备进行收集的应用程序。
语法
msys launch [选项] <应用程序> [<应用参数>]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -e | --env-var | A=B | NA | 设置环境变量，变量应由逗号分隔，无空格 |
| -h | --help | 显示启动帮助菜单 | ||
| --musa-graph-trace | graph, node | graph | 如果选择 graph，将整体追踪 MUSA Graph，不收集节点活动。如果选择 node，将收集节点活动，但不整体追踪 MUSA Graph。默认为 graph（如果可用）。 | |
| --osrt-threshold | <纳秒> | 1000 | 设置 OS Runtime (osrt) API 必须执行的持续时间（以纳秒为单位）然后才被追踪。默认为 1000（1 微秒）。 | |
| --session | [a-Z][0-9a-Z] | [default] | 在给定会话中启动应用程序。选项参数必须是 msys sessions list 报告的有效会话名称。 | |
| -t | --trace | none, musa, opengl, osrt, vulkan | musa,opengl | 选择要追踪的 API。可以选择多个 API，用逗号分隔（无空格）。如果选择 none，则不追踪任何 API。 |
start 命令
在交互模式下开始配置会话。
语法
msys start [选项]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -d | --device | <设备索引> | all device | 设置要配置的设备 ID。多个 ID 应由逗号分隔，无空格。选项参数必须是 --device=help 开关报告的 GPU ID 之一。默认捕获所有设备。 |
| --gpu-metrics-set | <指标 ID> | NA | 指定 GPU 指标采样的指标集。多个 ID 应由逗号分隔，无空格。默认不捕获 GPU 指标。 | |
| -h | --help | 显示开始帮助菜单 | ||
| -o | --out | <文件名> | report#.msys-rep | 设置输出报告文件名。在默认位置生成 report#.msys-rep 文件，如果需要，增加报告编号以避免覆盖任何现有输出文件。 |
| --session | [a-Z][0-9a-Z] | [default] | 在给定会话中启动应用程序。选项参数必须是 msys sessions list 报告的有效会话名称。 |
stop 命令
在交互模式下停止配置会话。
语法
msys stop [选项]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -h | --help | 显示停止帮助菜单 | ||
| -q | --quit | 停止收集并退出应用程序 | ||
| --session | [a-Z][0-9a-Z] | [default] | 在给定会话中停止收集。选项参数必须是 msys sessions list 报告的有效会话名称。 |
cancel 命令
在交互模式下取消配置会话。
语法
msys cancel [选项]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -h | --help | 显示取消帮助菜单 | ||
| -q | --quit | 取消收集并退出应用程序 | ||
| --session | [a-Z][0-9a-Z] | [default] | 在给定会话中取消收集。选项参数必须是 msys sessions list 报告的有效会话名称。 |
sessions list 命令
列出活动会话。
语法
msys sessions list [选项]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -h | --help | 显示会话列表帮助菜单 |
export 命令
将 msys-rep 文件导出为另一种格式。
语法
msys export [选项]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -h | --help | 显示导出帮助菜单 | ||
| -o | --output | <文件名> | 设置输出文件名 | |
| -t | --type | json (Open in chrome://tracing/) | json | 导出类型 |
stats 命令
从现有的 msys-rep 生成统计数据。
语法
msys stats [选项]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -h | --help | 显示统计帮助菜单 |
analyze 命令
在 msys-rep 中识别优化机会。
语法
msys analyze [选项]
选项
| 短选项 | 长选项 | 可能的参数 | 默认 | 描述 |
|---|---|---|---|---|
| -h | --help | 显示分析帮助菜单 |
图形界面 (GUI)
Moore Perf System GUI 提供了一个直观的界面，用于在本地主机或远程设备上进行性能分析。
从 GUI 分析远程 Linux 目标
Moore Perf System 提供了一个简单的界面，可以用于在本地主机上进行性能分析，也可以通过 SSH 访问远程 Linux 设备。通过下拉框中的 配置目标 可以管理所有的远程连接。
远程连接
在 目标管理 窗口中可以添加、删除和修改远程连接：
安全说明：连接到目标设备时，系统会提示输入用户密码。如果选择记住密码，密码将以明文形式存储在主机上的配置文件中。
开放端口：Moore Perf System 守护进 程需要端口 22 和端口 45557 处于监听状态。可以使用以下命令确认这些端口已开放：
sudo firewall-cmd --list-ports --permanent
sudo firewall-cmd --reload
使用以下命令开放端口，省略 --permanent 选项仅对当前会话生效：
sudo firewall-cmd --permanent --add-port=45557/tcp
sudo firewall-cmd --reload
收集选项
Windows 和 Linux 有不同的收集选项。
Linux
Windows
启动进程
Moore Perf System 可以为目标设备上的性能分析启动新的进程。分析器确保所有环境变量都正确设置，以成功收集跟踪信息。
在 Linux 上，Moore Perf System 可以为目标进程附加额外的环境变量。
开始/停止性能分析
Moore Perf System 提供了一些控制选项方便用户便捷地控制性能分析会话：
点击开始按钮后，根据下方复选框的设置决定会话行为：
- 默认行为：启动应用程序并自动开始收集数据，直至应用程序退出。
- 手动开始收集：仅启动应用程序，等待用户手动开始开始数据收集，适用于需要在应用程序运行一段时间后再开始收集的场景。
- 开始收集延迟时间：启动应用程序后延迟指定时间再开始数据收集。
- 收集时长限制：限制收集数据的时长，达到设定时间后自动停止收集。
- 快捷键开始/停止：通过热键控制收集的开始和停止，默认热键为 F12。这在跟踪使用全屏显示的游戏和图形应用程序时非常有用。
容器和调度器支持
Docker 容器支持
Moore Perf System 支持在 Docker 容器中进行性能分析。要在容器中使用 Moore Perf System，需要确保：
- 容器具有访问 GPU 的权限。
- Moore Perf System 工具已安装在容器内或主机上。
- 适当的权限设置以进行性能数据收集。
Direct3D Trace
Moore Perf System 能够收集 Windows 目标上的 Direct3D 11 和 Direct3D 12 API。
D3D11 API Trace
Moore Perf System 可以捕获被分析进程中 Direct3D 11 API 调用的信息，包括 D3D11 API 函数的执行时间、性能标记和帧持续时间。
D3D12 API Trace
Direct3D 12 是一个用于 Microsoft Windows 的低开销 3D 图形和计算 API。
Moore Perf System 可以捕获被分析进程中 Direct3D 12 的使用信息，包括 D3D12 API 函数的执行时间、GPU 上执行的相关工作负载、性能标记和帧持续时间。
启用 Direct3D Trace
在 GUI 中，可以通过项目设置页面启用 Direct3D API Trace 功能。选择要 Trace 的 Direct3D API 类型（D3D11 或 D3D12）后，性能分析将自动收集相关的 API 调用信息。
WDDM 队列
Windows 显示驱动程序模型（WDDM）架构使用队列从 CPU 向 GPU 发送工作包。每个进程中的每个 D3D 设备都与一个或多个上下文关联。被分析应用程序使用的图形、计算和复制命令与上下文关联，批量到命令缓冲区，并推送到与该上下文关联的相关队列中。
有关 WDDM 架构的详细信息，请参见 Microsoft 文档。
Vulkan Trace
Vulkan 是一个低开销、跨平台的 3D 图形和计算 API，面向从 PC 到手机和嵌入式平台的各种设备。Vulkan API 由 Khronos Group 定义。
Moore Perf System 可以捕获被分析进程中 Vulkan API 调用的信息，包括 API 函数名称、执行时间、返回值、函数参数、进程 ID 和线程 ID。
启用 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 执行情况。
MUSA Graph Trace
Moore Perf System 能够以 graph 或 node 粒度捕获应用程序中的 MUSA Graph 信息。可以在 CLI 中使用 --musa-graph-trace 选项设置捕获粒度，或在 GUI 中通过设置相应的下 拉菜单来完成。
Graph 粒度
当 MUSA Graph Trace 设置为 graph 时，用户可在时间线上看到每个 graph 作为一个元素呈现：
Node 粒度
当 MUSA Graph Trace 设置为 node 时，用户可在时间线上看到每个 graph 下的所有 node：
OS Runtime Libraries Trace
Moore Perf System 支持追踪操作系统运行时库（OS Runtime Libraries）的 API 调用。这可以帮助开发者了解应用程序与操作系统底层库之间的交互。
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
配置 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 配置
在项目设置页面中：
- 勾选 Collect OS runtime libraries trace 复选框启用 OSRT Trace
- 可选：勾选 Skip if shorter than 并设置时间阈值（单位：微秒）
OpenGL Trace
可以收集 OpenGL 和 OpenGL ES API 以协助分析 CPU 和 GPU 之间的交互。
在 GUI 中查看报告
报告可以复制到任何系统，并使用 GUI 进行分析。
打开现有报告
你可以通过选择 文件 > 打开 并选择 .msys-rep 文件来打开现有文件。
导 入 ETL 文件
在 Windows 上，支持导入 .etl 文件。
注意： 当加载大型报告（包含超过 3000000 个事件）时，你需要选择一个时间范围并点击 "加载" 按钮以完成加载过程。
共享报告文件
Moore Perf System 生成的报告文件（.msys-rep）可以在不同系统之间共享，便于团队协作分析性能问题。
报告选项卡
每个打开的报告都会在一个单独的选项卡中显示，方便同时查看和比较多个报告。
概要视图
此视图提供了性能分析会话的概要信息。它特别适用于审查用于生成此报告的项目配置。
时间线视图
时间线是一个多功能控件，左侧包含树状层次结构，右侧显示相应的图表。
层次结构的内容取决于用于收集报告的项目设置。例如，如果某个特定功能未启用，则相应的行将不会显示在时间线上。
缩放和滚动
在 Moore Perf System GUI 的右上角，你将看到缩放和滚动控制部分：
滑块设置屏幕行的垂直大小，放大镜将其重置为原始设置。
在时间线上水平缩放和滚动有很多方法。点击键盘图标打开对话框，解释这些操作。
鼠标悬停在几个项目上时，会显示额外的信息作为工具提示。
在事件列表中显示事件
右键单击时间线行并选择 在事件列表中显示 或 在事件列表中显示所有事件。
点击事件列表中的特定实例将突出显示时间线上的相应事件。
显示标记事件
标记事件以便稍后在时间线上快速查看。
显示统计信息
选择 显示统计信息 以显示 GPU 使用情况信息。
固定行
右键单击并选择 固定行 以固定选定的行。
事件列表
事件列表以表格形式显示跟踪事件。
在事件列表中单击一个项目会自动将时间线视图聚焦到相应的时间线项目，并显示详细的事件信息。
可以搜索和排序视图内容。
使用 Shift 或 Ctrl 启用多选。
右键菜单提供命令，如在时间线上缩放至已选项、标记事件、清除选定事件 和 清除已筛选的事件。
统计视图
下拉框选择统计系统视图以查看详细的统计结果。
专家系统视图
下拉框选择专家系统视图以查看详细的分析结果。
过滤
输入过滤条件并突出显示行。
排序
点击标题进行排序。
多报告时间线视图
Moore Perf System 支持同时查看多个报告，便于进行性能对比分析。
打开多个报告文件
- 选择 文件 > 打开，选择多个
.msys-rep文件 - 在弹出的对话框中选择打开方式：
- 单独打开每个报告：在每个标签页中分别打开报告
- 创建新的多报告视图：在单个视图中对齐显示多个报告
新建多报告视图
选择 文件 > 新建多报告视图 可以创建一个新的空多报告视图，然后添加报告文件进行对比分析。
功能特点
- 多个报告的时间线垂直对齐，便于对比
- 共享相同的时间刻度，可同步缩放和滚动
- 支持保存多报告视图配置（
.msys-multi文件）以便后续使用
