Unreal Insights介绍

简要介绍应用分析工具Unreal Insights

Choose your operating system:

Windows

macOS

Linux

Unreal Insights 可帮助开发者识别瓶颈，适用于优化性能。从较高层面看，Unreal Insights是一款集成了虚幻引擎的standalone分析系统，用于收集、分析和显示引擎发出的数据。除充分覆盖引擎的现有系统外，利用Unreal Insights还可轻松添加用户自身的分析数据。最后，该系统拥有远程数据录制功能，对项目执行的影响非常低。

设置

虚幻引擎随附的Unreal Insights工具位于 Engine/Binaries/Win64 目录中。下载并在本地编译UE4源码用户可使用以下方式编译：在开发或发布模式中构建整个UE4解决方案；或直接编译"UnrealInsights"项目。

UnrealInsightsProjectVisualStudio.png

找到或构建编译程序（UnrealInsights.exe）后，在用于录制数据或查看实时会话的机器上运行该程序。为尽量减少工具对应用程序的影响，建议运行工具时最好选择另一台机器，而非监控项目的机器。项目与工具可在同一台机器中运行，但请注意：由于项目在启动时会尝试连接工具，因此必须先运行工具。

若远程运行工具，使用以下命令行选项启动项目来向项目提供IP，其中IP替代"X"：-tracehost=X

  • 只有在远程设备、Mac或Linux上运行时才需要"-tracehost=X"参数。

  • 在Windows上启动时（若能发现工具），运行时会自动连接Unreal Insights。

追踪运行时事件

使用 -trace[=channel0[,channel1...]] 命令行参数后，可以启用从运行时到Unreal Insights的条件检测事件（instrumentation event）。该参数可以是一个逗号分隔的跟踪通道列表（可选），或者一个.ini定义的通道集的名称 （详情参见下文）。假如没有为 -trace 提供参数，则会使用默认的通道列表（cpu、frames、log 和 bookmarks）。 生成的 .utrace 文件会出现在您的项目的默认剖析目录中(通常是/Saved/Profiling)。Unreal Insights可以读取该文件；把它拖放到**浏览器**窗格中来加载它。

trace.stop 命令会暂停所有通道中的追踪；使用 trace.start 来恢复追踪。由于 trace.stop 适用于所有通道，所以它不接受任何参数。

有关性能分析指令的更多详情，请参阅Unreal Insights参考。

预定义通道集可以在 .ini 文件中的 Trace.ChannelPresets 部分中定义。在 Engine/Config/BaseEngine.ini中可以找到一个默认集（以前叫 "Default"）。它是 -trace 和 trace.start 使用的默认设置。用户可以在.ini文件中轻松添加自己的设置，如下所示。 

[Trace.ChannelPresets]
MyChannelSet=log,frame

该预设然后可以通过 -trace=MyChannelSet 或 trace.start MyChannelSet 使用。

有关追踪器工作线程的更多信息，请参阅Trace

Unreal Insight—浏览器

在浏览器模式（4.25版新增功能）下启动应用程序后，显示追踪会话（Trace Sessions）（1）、追踪存储目录（Trace Store Directory）（2）功能按钮和新连接（New Connection）（3）菜单。

UnrealInsightsBrowser.png

工具启动时首先会打开Unreal Insights窗口。在窗口顶部标有 追踪会话（Trace Sessions） 的部分将显示可加载进行分析的所有预录会话列表。此类会话对应 追踪存储目录（Trace Store Directory） 中的 .utrace 文件。可双击任一追踪会话（或选择追踪会话并点击 打开（Open）），或使用 打开（Open） 下拉箭头在其他位置搜索 .utrace 文件。要立即启动对每个追踪文件的分析，可以将一个 `.utrace`文件从Explorer拖放到Unreal Insights窗口上。

若有实时UE4会话连接工具，列表也会显示该会话。实时会话在状态列为 LIVE 一词，分析它们时会实时更新，其他方面则与预录会话相同。工具可同时连接多个会话，在数据流入时会自动录制所有此类会话的数据。可从列表中加载此类会话（与加载预录会话一样）来实时分析。

底部（新连接（New Connection））拥有实验性 连接（Connect） 按钮和文本输入字段，可在其中输入正在进行的会话IP。此功能主要用于游戏主机，尚在开发中，可能不稳定。未来版本会有此功能的进一步迭代。目前唯一的推荐程序为：启动项目并为项目使用 -tracehost=%ADDRESS% 命令行选项，然后启动Unreal Insights工具。

已废弃功能

追踪录制器部分包含无需关闭工具即可停止追踪录制的 停止（Stop） 按钮，4.25版已弃用该按钮。收集所需数据后，在会话结束前，可使用此按钮停止新数据流入实时会话，便于读取数据。按下此按钮还会断开工具与运行中会话的连接，并阻止新会话连接。

停止录制时，显示 开始（Start），替代 停止（Stop）。重新启动录制后，可连接新的远程虚幻引擎会话，但不会连接追踪录制停止时启动的会话，也不会重新连接被 停止（Stop） 功能放弃的会话。

UnrealInsightsStopped.png

带开始按钮的Unreal Insights v0.10

Unreal Insights—查看器

4.25版新增了单独启动追踪会话分析的功能（查看器模式）。用户可以同时打开多个分析（查看器）窗口。

打开追踪会话分析后，Unreal Insights显示三个窗口选项卡。其中**Timing Insights 窗口和 Asset Loading Insights** 窗口选项卡在会话可供查看时显示，用于浏览和显示性能数据。

Timing Insights窗口

Timing Insights窗口包含CPU和GPU的逐帧性能数据。可使用多个面板以不同方式查看项目在各项任务上花费的时间。可选择要汇总查看的时间段、对数据排序或分类，以及查看日志输出。这些面板都可以分别选择显示或隐藏。

Unreal Insights参考

TimingInsightsPanels.png

Timing Insights窗口包含帧面板（1）、时间面板（2）、日志面板（3）、定时器和计数器选项卡（4），以及调用项和被调用项面板（5）。

Timing Insights窗口的一项关键功能是选择单个帧或时间段并显示该段时间内收集的性能信息，其方法是高亮显示和缩放时间面板，并聚合定时器选项卡和统计信息计数器选项卡中的数据。具体步骤为点击帧面板中的单个帧，或点击并拖动时间面板顶部拖动条的一部分，也称 时间标尺。

!0

帧面板

帧（Frames）面板用条形图显示各帧总占时。这有助于识别一般趋势，例如在加载特定关卡或未优化场景可见时帧率出现降低，或有助于发现单个帧变慢的原因，例如一次生成大量Actor。由于条越高表示帧越长，因此可轻松找出此类事件发生的确切时刻，并检查数据以确定对应操作。将光标悬停在条上会显示该帧的索引和运行时间。若点击该条，可在时间面板、定时器选项卡和统计信息计数器选项卡中隔离该帧的数据。

FramesPanel.png

帧面板中的选定帧。白色括号标记显示时间面板中可见的一组帧。

时间面板

在Unreal Insights中进行操作中，用户的大部分时间可能都会花在时间（Timing）面板上。此面板显示会话期间运行的所有计时器事件的每个实例可视化表现。不同于帧面板提供的全体帧概览，时间面板显示单独的追踪事件，并提供亚微秒精度级的时间测量。此类事件垂直堆叠以指示范围，并使用单独轨迹显示不同的线程活动。在轨迹画面中，事件按线程垂直划分以显示范围，并基于其开始和结束时间水平放置。

TimingPanel.png

将鼠标悬停在时间面板中的定时器事件上时显示的提示文本。(1) 同一线程上嵌套事件的堆栈。(2)

可在面板左上角的 轨迹（Tracks） 下拉框中打开或关闭相关线程组。将鼠标光标悬停于任意轨迹中的块上，都会显示该定时器事件的信息，点击它即可在定时器选项卡中找到并选择该事件。

TracksDropdown.png

时间面板含有下拉菜单，可基于轨迹组所含线程隐藏或显示相关轨迹组。

使用时间面板时，可能需要查看特定时间范围的聚合数据。在时间标尺上点击并拖动鼠标指针，就能选择要查看的时间段。也可以 Ctrl+双击 时间选项卡内的事件，或左键点击定时事件将其选中然后按下 回车键。另一个选择是点击帧面板中的帧。进行此操作时，选中时间范围显示为蓝色覆层，在顶部显示其总长度，定时器选项卡和计数器选项卡仅显示该时间范围内的数据。然后可按 F 直接缩放和平移至选定时间范围。

在4.25中，可以双击时间视图中的时间事件，即可高亮显示同一类型（定时器）的所有时间事件。

UnrealInsightsEventFiltering.png

类似时间事件高亮显示，所有其他时间事件颜色消褪

定时器选项卡

定时器选项卡将列出时间面板中指定时间范围内运行的所有定时器事件。除基于时间范围聚合数据外，还可根据任何活动列中的值对此列表进行升序或降序排序。右键点击列表中任意位置，即可更改排序顺序或激活或停用列。以下列可用于定时器选项卡：

  • 元组名

  • 类型

  • 实例计数

  • 总包含时间

  • 最大包含时间（毫秒）

  • 平均包含时间（毫秒）

  • 中间包含时间（毫秒）

  • 最小包含时间（毫秒）

  • 总独占时间

  • 最大独占时间（毫秒）

  • 平均独占时间（毫秒）

  • 中间独占时间（毫秒）

  • 最小独占时间（毫秒）

分组依据（Group By）

TimersTabByName.png

按定时器名称分组的定时器选项卡数据

计数器选项卡

计数器选项卡将列出与计时器选项卡同一时间段内增加的所有统计数据。用户可按定时器选项卡中的方式更新排序顺序和列组织。以下列可用于计数器选项卡：

  • 元组名

  • 类型

  • 计数

  • 总和

  • 最大值

  • 上四分位数（4.23中未实现）

  • 平均值

  • 中值

  • 下四分位数（4.23中未实现）

  • 最小值

分组依据（Group By）

UnrealInsightsCounters.png

组成平面组的计数器选项卡数据

Unreal Insights参考

双击计数器即可在添加计数器的图表序列时开启图表轨迹可视性。

UnrealInsightsCountersGraph.png

STAT_PageAllocatorTree

日志面板

日志面板显示UE4会话中的所有日志（由 UE_LOG 调用生成）。日志可按冗余和类别过滤，与编辑器的输出日志窗口相同。它还提供搜索框，可过滤掉与输入文本不符的所有日志消息。除过滤外，点击任意行都会将时间面板平移至该行文本的记录时间。

LogPanel.png

在时间面板中选择时间段将（用蓝色）高亮显示该段时间内的所有日志条目。相反，若点击一个日志条目然后按住shift并点击另一日志条目来选择多个条目，则时间面板将高亮显示此类条目之间的时间范围。

Asset Loading Insights窗口

Unreal Insights工具提供Asset Loading Insights窗口，用于分析资产加载性能。此窗口包含Timing Insights视图中时间面板的专属版本，已配置为关注与加载资产相关的事件。

AssetLoadingInsights.png -loadtimetrace

内存Insights窗口

Memory Insights让开发人员得以了解其应用如何使用内存。将内存使用情况可视化后，团队能够更好地了解他们的工作如何影响应用性能和引擎行为。

UnrealInsightsMemory.png

内存图表面板(1) 和LLM标签面板 (2)

显示内存使用情况的默认图形跟踪。

  • 全部（Total）

  • 全部的追踪（TrackedTotal）

  • 未追踪（Untracked）

  • 网格体（Meshes）

  • 纹理（Textures）

  • 物理（Physics）

  • 音效（Audio）

用例

要跟踪应用程序的内存使用情况，请在 关卡编辑器（Level Editor） - 播放（Play） > Play in Standalone Game 下的 其他启动参数（Additional Launch Parameters） 文本框中输入 -trace=memory。

-trace=memory implies -llm

内存图表面板

LLM图表面板能够为各个LLM标签，显示内存随时间变化的情况。内存图表面板配有自定义垂直网格，注明了可见范围以及最小最大值。将鼠标光标悬停在轨道右侧时，只要当前最小值和最大值不相等，就显示这两个值的差值。

LLM标签面板

LLM标签面板会显示可见LLM标签列表。列表中的每个LLM标签都有如下属性。

属性

介绍

颜色

用于显示LLM标签是否有内存图表轨道。

名称

LLM标签的名称。

追踪器

标识哪个追踪器在使用LLM标签。

双击一个LLM标签可添加或删除其内存图表轨道。你还可以对每个追踪器的LLM标签列表进行排序和分组。

UnrealInsightsMemoryLLMTagsToggle.png

启用后，该选项将过滤当前跟踪器使用的LLM标签。

通道

通道是一种新概念，开发者可利用它将事件分类到指定组。开发者可用其管理生成追踪数据数量，提高性能并节约空间。通道目前默认禁用，但可在实时会话中启用或关闭。

要在编辑器中启用 Insights Data Source Filters 和 Trace Data Filtering 插件，可在 编辑器（Editor）> 插件（Plugins）> 内置（Built-In） 中寻找。也可在项目的 *.uproject 文件中启用插件。 

{
    "FileVersion": 3,
    "EngineAssociation": "4.25",
    "Category": "",
    "Description": "",
    "Plugins": [
        {
            "Name": "TraceSourceFilters",
            "Enabled": true
        },
        {
            "Name": "TraceDataFilters",
            "Enabled": true
        }
    ]
}

Unreal Insights参考

自定义项目输出

细微更改引擎、插件或项目源代码，即可激活或停用特定Unreal Insights功能。同时可添加自定义日志记录。

激活或停用日志记录

若要控制发送日志记录数据的区域，或要停用整个系统，需编辑引擎源代码并更改某些宏的值。此类宏遍布整个引擎，通常位于相关功能或模块的标头文件中。已开启日志记录的区域使用值"1"，已关闭日志记录的区域使用值"0"，但始终在条件结构中定义，该条件结构首先确定宏是否适用于编译情境。控制日志消息追踪的宏 LOGTRACE_ENABLED 位于 Engine/Source/Runtime/Core/Public/Logging/LogTrace.h 中，具有以下结构： 

#if !IS_PROGRAM && !UE_BUILD_SHIPPING && (PLATFORM_WINDOWS || PLATFORM_PS4 || PLATFORM_XBOXONE)
#define LOGTRACE_ENABLED 1
#else
#define LOGTRACE_ENABLED 0
#endif

在将日志数据正确发送至Unreal Insights系统的版本中，LOGTRACE_ENABLED 默认定义为"1"。要将其停用，修改上述代码中的第二行，将 LOGTRACE_ENABLED 定义为"0"而非"1"。

Unreal Insights参考

添加自定义CPU范围定时器

要向自己的引擎功能、插件或项目添加日志记录，对要分析的范围调用 TRACE_CPUPROFILER_EVENT_SCOPE 宏。此宏采用单个文本参数来辨识将拥有其生成的分析数据的追踪组。可使用任何名称，常见用例如 TRACE_CPUPROFILER_EVENT_SCOPE(TEXT("MyClass::Function")) 或 TRACE_CPUPROFILER_EVENT_SCOPE(TEXT("ReticulatingSplines"))。请注意：TRACE_BOOKMARK 和`UE_LOG` 宏显示在Unreal Insights中，因此将日志放在待调查代码的邻近区域有助于在分析数据时更快找到所需信息。

Insights日志

Insights日志 显示Unreal Insights相关的消息日志。在下面的例子中，Insights日志会显示因为解析LLM XML报告文件而产生的警告和错误。

UnrealInsightsMemoryInsightsLog.png

平台详情

可使用Unreal Insights收集一些平台上的追踪数据，例如Android和个人电脑。

Android

凭借Android Debug Bridge (adb)，Android工具可通过USB线重定向TCP流量。要在Android设备上连接运行时应用程序，首先指示adb经由设备上通过USB建立的TCP连接传递： 

adb.exe reverse tcp:1980 tcp:1980

Unreal Insights聆听TCP端口1980。

在设备上运行时应连接到 localhost，因此操作系统将通过USB线路由流量。 

-tracehost=127.0.0.1

你可以用两种方法在Android项目中使用这些CLI参数。

首先，你可以把 -tracehost=127.0.0.1 添加到一个名为 UE4CommandLine.txt 的空文本文件中。然后，运行 adb push <path_to>\UE4CommandLine.txt /mnt/sdcard/UE4Game/<project_name>/UE4CommandLine.txt 。

或者，你可以运行 adb shell setprop debug.ue4.commandline -tracehost=127.0.01。效果只在设备开启时存在。

命令 adb shell setprop debug.ue4.commandline \"\" 会删除命令行参数。

这两种方法都会把命令行参数添加到你设备上的应用程序中。之后，你就能正常运行应用程序，或使用 adb shell am start -n com.<your_company_name>.<project_name>/com.epicgames.ue4.GameActivity 运行该应用程序。

文件

追踪可使用 -tracefile=PATH 命令行参数输出至文件。PATH 的值专属于被追踪的平台，包括个人电脑和Android。

个人电脑

-tracefile=d:/foo/bar.utrace

Android

-tracefile=/sdcard/UE4Game/foobar.utrace

/sdcard/

欢迎帮助改进虚幻引擎文档！请告诉我们该如何更好地为您服务。
填写问卷调查
取消