Version:

Icon of a magnifying glass.
  在GitHub上编辑

本文内容

Open 3D Engine （O3DE） 的 CPU 分析支持

CPU Profiler 用于在运行编辑器或游戏时 监控处理器的性能。它收集定时事件，以便您可以轻松识别代码库中速度变慢的来源。

Tip:
调试和发布版本之间的代码行为不同，因此您很可能只想分析发布版本来查看应用程序的性能问题。

概述

快速定义分析器类型

有多种方法可以捕获分析数据，每种方法都有其优点和缺点：

  • 检测 : 您可以自己在代码中添加 Start/End 事件。它很快，结果很干净，但可能需要尝试几次才能查明确切的问题区域。
  • 采样 : 在指定的时间间隔内，将在正在运行的程序上完成数据收集，以了解代码当前执行的位置。根据间隔，它可能会对性能产生很大影响。立即找到有问题的区域很好，但数据量可能会使其难以导航。
  • 追踪 : 与采样类似，精度更高，但对性能的影响也更大。从现在开始，它被称为 “Sampling”，因为在本文档中，我们不需要区分两者。

分析器 Gems

O3DE 目前支持将多个分析工具作为 Gem。虽然您一次只能启用一个性能分析 Gem，但 Gem 管理器使您可以在它们之间切换并尝试所有 Gem。

分析器说明类型平台
内置提供 CPU 和 GPU 事件的快速概述。它是通过 ImGui 工具 嵌入的.检测所有
Tracy 一个外部免费和开源的分析器，它结合了许多功能，使其成为一个混合分析器。 Online demo 检测（带可选的采样支持）所有
Optick 一个在游戏行业中广泛使用的外部免费开源分析器。近年来，开发已停止，但它的功能是完整的。检测（带可选的采样支持）Windows
Superluminal 具有强大采样性能和 UX 的外部商用性能分析器。广泛应用于游戏行业。采样（支持 Instrumentation）Windows
Pix XBox 控制台上使用的官方 Microsoft 分析器。采样（支持 Instrumentation）Windows

在代码中添加 Instrumentation 标记

若要访问分析标记，请在 C++ 文件中包含<AzCore/Debug/Profile.h>。然后，O3DE 将标记转发到启用的分析器 Gem。大多数用例都使用以下两个宏来涵盖：

  • AZ_PROFILE_FUNCTION : 使用当前函数的名称启动 timing 事件。
  • AZ_PROFILE_SCOPE : 使用自定义名称启动计时事件。

当您到达当前范围的末尾（下一个 “}"）时，计时事件会自动结束。

使用这两个宏中的任何一个时，您必须提供 Budget 参数。它用于将这些标记分组到同一类别下。默认情况下，以下预算可用：

  • Animation
  • Audio
  • AzCore
  • Editor
  • Entity
  • Game
  • System
  • Physics

您可以通过在 C++ 文件的全局范围内使用AZ_DEFINE_BUDGET(YOUR_BUDGET_NAME) 来创建新的预算类型。

用法示例：

#include <AzCore/Debug/Profiler.h>

void AssetDataStream::Open(const AZStd::vector<AZ::u8>& data)
{
    AZ_PROFILE_FUNCTION(AzCore);

    // ...
    while (!m_isSuspended)
    {
        AZ_PROFILE_SCOPE(AzCore, "Scheduler main loop.");
        // ...
    }
}

虽然标记 如果使用采样分析器则不是必需的，但它们将帮助您导航捕获：

  • 预算名称将显示在活动名称旁边。
  • 来自同一预算组的事件在外部性能分析器应用中将共享相同的颜色。

鉴于采样事件不包含这些附加信息，您的标记将在捕获中脱颖而出，并提供有关周围区域的上下文。

使用内置分析器 （所有平台）

启用内置的分析器Gem

内置分析器是核心 O3DE 存储库中的可选 Gem。按照 本文档 了解如何使用项目管理器启用 Gem。在 Gem 管理器中，搜索Profiler以查找并启用 Gem。

Imgui profiler enable

打开 Profiler

Profiler 嵌入在 ImGui 工具 中。打开 ImGui 工具，然后单击 ImGui 菜单中的 Profiler条目以打开 CPU Profiler。

Imgui profiler overview

启动捕获

分析器将 最后 10 帧 的状态存储在内存中。打开后，您将看到时间轴随着新帧被推送到堆栈而不断更新。单击左上角的 Resume/Pause 按钮以暂停此更新。

要捕获更多帧，请按Begin按钮。分析器将能够以每秒 120 帧的速度捕获最多 2 分钟的数据。获得足够的数据后，按End按钮停止捕获。

Imgui profiler overview

导航您的捕获

使用鼠标在 Profiler 中导航。点击 Swap to visualizer/statistics 在两个主要视图之间切换。单击可视化工具视图中的某个项目将切换到统计信息视图，如下所示。

Imgui profiler statistics

使用可视化工具中的 Find Region 搜索特定事件。时间轴是交互式的，用鼠标左键单击它以聚焦它，然后：

  • 按住鼠标左键可在时间轴上移动
  • 按住 Ctrl 键并使用鼠标滚轮更改时间轴比例

Imgui profiler search

要查找超出预算的帧，请缩小时间轴比例，直到每个捕获的帧的帧时间以毫秒为单位显示。

保存您的捕获

按Capture按钮将捕获的数据保存在 json 文件中。该路径将在按钮的正上方指示。您可以使用Load file按钮加载任何以前的捕获。

Imgui profiler save

Tracy、Optick 和 Superluminal 的先决条件

这些分析器 Gem 位于 o3de-extras github 存储库中。

  1. 此存储库遵循远程内容格式，请按照 使用远程存储库指南了解如何 注册远程存储库。

  2. 如果您更喜欢自己下载 o3de-extras，您可以按照 注册 Gem 指南进行作。分析器 Gem 位于o3de-extras文件夹中的Gems/ExternalProfilers中。

注册分析器 Gem 后，启用它并重新构建项目。请参阅 启用内置分析器的第一步 了解如何为项目启用 Gem。

使用 Tracy 分析器（所有平台）

“客户端”是游戏或编辑器，而“服务器”是用于可视化捕获数据的外部 Tracy 应用程序。此应用程序在 Windows 上可用，但需要为其他平台构建。

(Windows) 获取服务器应用程序

您可以从 github 下载 最新版本 ，选择windows-x.x.zip文件。下载后，解压它，服务器应用程序是tracy-profiler.exe的，您必须随时启动它以进行新的捕获。

(Linux) 构建服务器应用程序

您必须自己构建应用程序，此过程在 文档文件 的 “2.3 构建服务器” 中进行了概述。您可以在下面找到摘要：

  1. 安装 git、CMake 和 clang（您可以通过 o3de 文档 了解如何设置它们])

然后，您可以在您选择的文件夹中打开一个终端：

  1. 克隆 Tracy 存储库。同步到 Gem 使用的相同版本（在 o3de-extra 存储库中的Gems/ExternalProfilers/TracyProfiler/Code/CMakeLists.txt下可见）。然后进入服务器应用程序文件夹。
git clone https://github.com/wolfpld/tracy.git
git checkout 5d542dc09f3d9378d005092a4ad446bd405f819a
cd tracy/profiler
  1. 安装所需的库并配置构建
echo $XDG_SESSION_TYPE

如果显示 “X11”

sudo apt install libdbus-1-dev libfreetype-dev libtbb-dev
cmake -B build -DLEGACY=1 -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER:FILEPATH=/usr/bin/clang -DCMAKE_CXX_COMPILER:FILEPATH=/usr/bin/clang++

如果显示“Wayland”

sudo apt install libglfw3-dev
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER:FILEPATH=/usr/bin/clang -DCMAKE_CXX_COMPILER:FILEPATH=/usr/bin/clang++
Tip:
通常不需要 DCMAKE_C_COMPILER 参数，但如果未设置这些参数，则可能会在构建结束时遇到链接器问题
  1. 构建 Tracy
cmake --build build --parallel --config Release --target all

如果构建成功，您可以通过以下命令启动 Tracy 应用程序

./build/tracy-profiler

如果构建失败，可能是因为缺少库，通常可以通过 sudo apt install libNAME-dev 安装。否则，您可能希望尝试使用 Visual Studio Code 进行构建，如 Tracy 文档中所述。

启动捕获

虽然不是必需的，但 以管理员身份启动编辑器或游戏 将允许分析器在插桩标签之上收集采样数据（在撰写本文时，tracy sampling 仅适用于 Linux）。

在Windows上:

  • 右键单击您使用的编辑器快捷方式，然后选择 以管理员身份运行。如果--project-path="C:/Path_To_Your_Project"尚不存在，您可能希望使用它作为启动参数。

在Linux上:

  • 打开编辑器生成旁边的终端。然后使用 sudo sudo ./Editor --project-path="/home/Path_To_Your_Project" 启动它

然后，您可以启动您下载或构建的 tracy-profiler 应用程序。在 connect 按钮下，您应该会看到 “Editor” 进程被列出。单击它以开始捕获分析数据。

Tracy connect

导航您的捕获

Tracy overview

  • Frame Navigator : 允许您快速跳转到高于 16 毫秒目标的帧。
  • Sampling Info : 允许查看上下文切换、调用堆栈或区域，而无需分析事件。
  • Event Timeline : 包含记录的所有检测事件。这是主视图。
  • Sub-Windows : 默认情况下，这些选项未停靠，用于高级筛选和统计信息选项。

基本导航

使用鼠标完成导航：

  • 按住右键单击可在 Event Timeline 中移动
  • 使用鼠标滚轮放大和缩小 Event Timeline

添加鼠标中键用于 focus ：

  • 单击鼠标中键以将焦点放在光标下方的事件上
  • 单击并拖动鼠标中键以聚焦于绘制的区域

基本搜索

如果您想 查找特定事件，请按ctrl + F打开Find zone窗口。

  1. 您需要勾选 Ignore case 选项。
  2. 输入要检查的事件的名称，然后按 Enter。
  3. 在底部滚动，打开包含线程名称的下拉列表。使用鼠标中键单击以将时间轴 聚焦 在事件上。

Tracy search

基本分析

您可能希望查看给定时间范围内成本最高的事件。为此，请打开 Statistics 面板

  1. 如果您点击 Total time 列，您可以按逗留时间排序。
  2. 点击 Limits 按钮以访问高级筛选
  3. 勾选 Statistics 按钮并点击 Limit to view。

统计信息中显示的事件现在将仅包含时间轴中红色的范围。

Tracy limit view

Tracy 提供了许多高级功能，您将在使用该工具时发现这些功能。如有需要，可参考 官方文档 .

使用 Optick 分析器（仅限 Windows）

Tip:
可以分析和保存任何平台的分析数据，但用于可视化此捕获的 GUI 应用程序仅在 Windows（使用 WPF 构建）上可用。在 linux 上可以通过 Wine ） 运行它，但这超出了本文档的范围。

如果您想快速了解一下，Optick 的创建者 制作了这个 youtube 视频 来展示该工具。

获取应用程序

您可以从 github 下载 最新版本 ，选择Optick_x.x.zip文件。下载后，将其解压缩，该应用程序是Optick.exe，您必须随时启动它以进行新的捕获。

启动捕获

虽然不是必需的，但 以管理员身份启动编辑器或游戏 将允许分析器在插桩标签之上收集采样数据。右键单击您使用的编辑器快捷方式，然后选择“以管理员身份运行”。您可能希望使用 --project-path="C:/Path_To_Your_Project" 作为启动参数。

您现在可以启动 Optick。单击左上角的 play 按钮开始捕获。跳入游戏并四处移动，直到您有足够的数据。

Optick connect

单击同一按钮将停止捕获。确保 之后单击编辑器/游戏窗口，以便它能够发送最后捕获的数据以完成配置文件捕获。

导航您的捕获

Optick overview

  • Frame Navigator: 允许 快速查看哪些帧超出您的预算。
  • Sampling Info: 显示 CPU 负载、上下文切换和调用堆栈。
  • Event Timeline: 包含所有仪器事件的主视图。
  • Sub-Windows: 高级筛选和数据搜索选项。“Function Flamegraph” 显示采样数据。

基本导航

使用鼠标完成导航：

  • 按住 右键单击 可在 Event Timeline 中移动
  • 使用鼠标滚轮放大和缩小 Event Timeline
  • 在 Event Timeline 中左键单击事件以选择它，子窗口会将其用作顶部项目

基本搜索

如果您想 查找特定事件，请按ctrl + F 并开始输入。

  1. 使用 key down 和 key up 在事件之间切换，然后按 enter 跳转到它（它将在所有事件中选择最昂贵的一个）
  2. 在“函数树”子窗口中，您将在您的事件下方看到事件，以及以毫秒为单位逗留的时间。在函数树的右上角，单击 % 按钮以显示每个事件在调用堆栈中表示的内容。

Optick search

采样调用堆栈

采样将定期捕获调用堆栈。您可以从 事件时间轴 中检查它们 ：

  1. 点击时间轴右上角的 Show callstacks
  2. 钻石将显示在时间轴中。对一个使用 ctrl + 右击 来查看调用堆栈。黄色菱形是系统调用，而红色菱形是自动采样。

Optick callstack

上下文切换

当您的线程进入休眠状态时，将发生上下文切换，以便另一个线程可以优先。Optick 区分了上下文切换的两个原因：

  • Preemption, 在事件顶部显示为一条粉红色的细线，可以在更高优先级的线程必须接管的任何时候发生。
  • Synchronisation primitives, shown 是事件顶部的一条细红线，当您在代码中显式等待时发生，例如，获取互斥锁上的锁。

如果您 按住 Ctrl 并左键单击 时间轴中的上下文开关，将打开一个对话框，显示您此时优先考虑的线程，以及您等待这些线程直到线程恢复执行的时间。

Optick contexts

更多设置

一般来说，如果您单击播放按钮旁边的 Cog 按钮，您可以对采样和捕获模式进行更精细的控制。如果要提高自动采样频率，则可能很有用。

Optick settings

Optick 可以定制以附加有关捕获、线程和事件的许多附加信息。如果您的游戏需要，请不要犹豫，跳入 Optick Gem 以满足您的需求进行扩展。

使用 Superluminal 分析器（仅限 Windows）

Superluminal 是一个商业分析器，它提供试用期，但如果您想继续使用它，则必须在此试用期后购买许可证。为防止许可问题，我们不会附上屏幕截图，我们建议您查看 查看官方文档 .

将 Superluminal 与 o3de 一起使用不需要 Superluminal Gem，它只会在现有采样数据之上提供一些仪器数据。

获取应用程序

您可以下载 Superluminal 从主网站 。在安装过程中，如果您决定不使用默认安装文件夹 （C:/Program Files/Superluminal），则必须更新 CMake 变量SUPERLUMINAL_API_PATH，如果您启用了 Superluminal o3de Gem。

启动捕获

你可以直接打开Superluminal，它将负责启动 o3de。在左侧的 Start 菜单下，单击 Run 按钮并填写以下字段：

  • 应用程序：指向Editor.exe或导出的游戏的路径
  • 工作目录：您可以使用与可执行文件相同的文件夹
  • 命令行参数：如果您使用编辑器，请输入 --project-path="C:/path/to/your/project"

然后在 Capture Options 下

  • 勾选Enable PerformanceAPI events 如果您启用了 Superluminal Gem
  • 取消勾选 Enable child process profiling 这样 Asset Processor 就不会为您的捕获添加噪点
  • 取消勾选 Start profiling immediately

您已准备好按下Run！编辑器或您的游戏将启动。准备好后，单击 Start Recording 按钮，捕获将开始。完成后停止它，片刻之后，捕获将准备好导航。

导航您的捕获

布局与 Optick 很接近，因此将使用相同的术语。**事件时间线 包含采样事件和插桩事件。采样事件是蓝色的，而插桩事件的颜色归属于其类别（Physics、System 等）。

默认情况下，所有线程都处于 折叠状态 在时间线中 ，因此您需要展开左侧的主线程下拉列表。

使用鼠标完成导航：

  • 按住 右键单击 可在 Event Timeline 中移动
  • 使用鼠标滚轮向上滚动，并在 Event Timeline 中完成
  • 按住 Ctrl 并使用鼠标滚轮放大和缩小 Event Timeline

左键用于快速过滤：

  • 在 Event Timeline 中左键单击事件以选择它，子窗口会将其用作顶部项目
  • 左键单击并拖动 Event Timeline 会将 Sub-Windows 分析限制在所选区域。

请参阅 Frame Navigator

Superluminal 没有 frame 的概念，但它可以接受任何事件并以类似于 Optick Frame Navigator 的外观显示其所有发生。只需右键单击主循环事件（编辑器为CryEditApp::OnIdle），然后单击Find all occurences**。您将看到顶部的 选项卡，以柱形图的形式显示发生次数及其毫秒时间。此选项卡称为 ‘Instance Graph’

由于捕获正在预热，前几次调用可能比平时更长，因此您可能需要在进行筛选之前在时间轴上拖动 select 以仅显示所选范围内的出现次数。另一个重要的一点是 柱形图是按性能排序的，而不是按帧编号排序的，因此将首先显示最昂贵的帧。

导航线程交互

在每个线程下拉列表的正上方，您都有 Thread Interaction view 。绿色区域是线程执行的时间，而红色区域显示线程正在等待的时间。如果单击红色区域，它将在底部打开一个视图，显示线程正在等待的内容、等待多长时间以及解决该问题的方法。

使用 Pix 分析器（仅限 Windows）

Pix 是 Microsoft 制作的免费分析器。最初用于分析 DirectX12 的 GPU 事件，现在能够分析 CPU。为防止许可问题，我们不会附上屏幕截图，我们建议您查看 官方文档 和此 官方 youtube 播放列表 。

Caution:
在撰写本文时，Pix 尚未在 o3de 中作为 Gem 实现，因此如果您想使用它，则必须 从源代码构建引擎

获取应用程序

您必须从 Microsoft 网站 下载应用程序和 WinPixEventRuntime 库。安装应用程序应该很简单，但为了向 o3de 提供 WinPixEventRuntime，需要执行一些具体步骤。

  1. 从 nuget 网站 下载 nuget 包（在“关于”部分下方的右侧查找 下载包）。
  2. 将文件的扩展名从.nuget更改为.zip
  3. 解压缩文件，并将目录重命名为winpixeventruntime
  4. 将文件夹复制到您的$LY_3RDPARTY_PATH文件夹。在 Windows 上，默认为 C:\Users\YOUR_NAME\.o3de\3rdParty
  5. 将 CMake 标志LY_PIX_ENABLED设置为 on，然后重新配置构建（在 configure 命令中为 -DLY_PIX_ENABLED=ON）

重新编译后，您将能够将 PIX 与 o3de 一起使用。

启动捕获

PIX 负责启动 o3de，因此只需启动 PIX 应用程序即可。您必须在**Select Target Process** 下填写以下字段（选择**Launch Win32**）：

  • Path to executable：您的Editor.exe 或导出的游戏的路径
  • Working directory：您可以使用与可执行文件相同的文件夹
  • Command line arguments：如果您使用编辑器，请输入--project-path="C:/path/to/your/project"
  • Launch for GPU Capture：确保它在分析 CPU 时未选中

然后，您可以单击 Launch 来启动编辑器/游戏。当您准备好进行 capture 时，点击 Start Timing Capture 开始 capture，然后再次点击相同的按钮停止它。

导航您的捕获

您将看到 Capture Summary。对于第一个概述，您应该选择 Timeline 选项卡来浏览每帧的事件。

使用鼠标完成导航：

  • 按住 右键单击 可在 Event Timeline 中移动
  • 使用鼠标滚轮向上滚动，并在 Event Timeline 中完成
  • 按住 Ctrl 并使用鼠标滚轮放大和缩小 Event Timeline

左键用于快速过滤：

  • 在 Event Timeline 中左键单击事件以选择它，子窗口会将其用作顶部项目
  • 左键单击并拖动 Event Timeline 会将 Sub-Windows 分析限制在所选区域。

基本搜索

如果您想 查找特定事件，请使用底部的Range Details选项卡并开始输入事件的名称。

  • 您可以通过下面的 Selector 视图从搜索中筛选出主题。找到的事件将与其调用堆栈一起显示在右侧。
  • 您可以右键单击事件，然后按 Show in Timeline 以专注于它。

上下文切换

在每个线程上方，您可以看到发生的每个上下文切换的红线。如果你点击它，你可以看到哪些线程导致了这个上下文切换的发生，以及我们等待了多长时间。