Unreal Insights概览

应用程序分析工具Unreal Insights概览

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。

Unreal Insight s— 浏览器

在浏览器模式(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 命令行选项,然后启动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的逐帧性能数据。可使用多个面板以不同方式查看项目在各项任务上花费的时间。可选择要汇总查看的时间段、对数据排序或分类,以及查看日志输出。这些面板都可以分别选择显示或隐藏。

欲了解Timing Insights的浏览方式,可参阅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

Asset Loading Insights窗口侧重于加载资产的相关性能。此处所示会话使用 -loadtimetrace 命令行选项录制。

通道

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

要在编辑器中启用 Insights Data Source FiltersTrace 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_BOOKMARKUE_LOG 宏显示在Unreal Insights中,因此将日志放在待调查代码的邻近区域有助于在分析数据时更快找到所需信息。

平台详情

可使用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

文件

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

个人电脑

-tracefile=d:/foo/bar.utrace

Android

-tracefile=/sdcard/UE4Game/foobar.utrace

虽然可以使用用户指定的任意路径,但Android OS版本和设备制造商不同,/sdcard/ 路径可能也有所不同。

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback