Unreal Insights参考

Unreal Insights中快捷键、宏和指令行选项参考。

Trace通道

Trace可以发出大量的数据，而通道用于控制Trace的数据流。每个事件都与一个或多个通道绑定，如果所需的通道没有启用，那么其中的事件不会被发射至Trace流中。

通道预设可以将许多通道分组并且提供基于场景的进入点。用户可以使用添加至[Trace.ChannelPresets]类别中的配置文件定义自己的预设。

下表展示可用的Trace通道以及每个通道的 文件路径（File Path）、 受支持平台（Supported Platforms） 以及 备注（Notes）。

名称中的复数被自动忽略，单数和复数名称完全相同。

通道

备注

受支持平台

文件路径

日志（Log）

日志信息。

Runtime\Core\Private\Logging\LogTrace.cpp

书签（BookMark）

低频率标记，用于标记重要过渡，可以帮助用户快速了解概况。 包括关卡加载或引擎启动阶段。

Runtime\Core\Private\ProfilingDebugging\MiscTrace.cpp

帧（Frame）

游戏和渲染帧。

Runtime\Core\Private\ProfilingDebugging\MiscTrace.cpp

统计信息（Stats）

基于统计数据系统给出的统计数字。

Runtime\Core\Private\Stats\StatsTrace.cpp

计数器（Counter）

通用计数器，用于追踪数值变化。计数器Trace API。同样也会启用CSV Profiler Trace。

Runtime\Core\Private\ProfilingDebugging\CountersTrace.cpp

CPU

有名称的CPU定时器。

可以使用`-statnamedevents`指令添加更多定时器。

Runtime\Core\Private\ProfilingDebugging\CpuProfilerTrace.cpp

场景切换（ContextSwitch）

追踪场景切换事件。在Windows系统中，游戏和编辑器运行时应该为"以管理员身份运行。"

  • Win64

  • XBox

  • PS4/PS5

Runtime\Core\Private\ProfilingDebugging\PlatformEvents.cpp

任务（Task）

任务图表跟踪通道。

Runtime\Core\Private\Async\TaskTrace.cpp

GPU

有名称的GPU定时器。基于GpuProfiler数据。

Runtime\RHI\Private\GpuProfilerTrace.cpp

RHI指令（RHICommands）

用于RHI指令的CPU/GPU带名称的定时器。

Runtime\RHI\Private\RHICommandList.cpp

渲染指令（RenderCommands）

用于渲染线程上运行的指令的CPU/GPU带名称的定时器。

Runtime\RenderCore\Private\RenderingThread.cpp

文件（File）

文件I/O跟踪通道（打开、重新打开、读取、写入、关闭事件）。

  • Win64

  • Mac,

  • XBox

  • PS4.

Runtime\Core\Private\ProfilingDebugging\PlatformFileTrace.cpp

加载时间（LoadTime）

资产加载Insights跟踪通道。包体加载时间（特定追踪事件）+ 包体加载特定的带名称的CPU定时器。需要"CPU"通道。同时添加 "LoadPackageInternal" CPU计时事件（连同元数据）。参阅SCOPED_LOADTIMER和SCOPED_CUSTOM_LOADTIMER宏的使用方式。

Runtime\Core\Public\ProfilingDebugging\LoadTimeTracker.h Runtime\Core\Private\Serialization\LoadTimeTrace.cpp

保存时间（SaveTime）

包体保存特定的带名称的CPU定时器。需要"CPU"通道。 添加名字带有"UPackage_Save_"前缀的CPU定时器。更多细节参考SCOPED_SAVETIMER宏的使用方式。

Runtime\CoreUObject\Private\UObject\SavePackage\SavePackageUtilities.h / .cpp

烘焙（Cook）

显示烘焙特定的带名称的CPU定时器。需要"CPU"通道。它会添加"CookByTheBook"CPU计时事件和"SaveCookedPackage"CPU计时事件（连同元数据）

Editor\UnrealEd\Private\Cooker\CookProfiling.h/.cpp

网络（Net）

网络追踪通道。需要-NetTrace=1（用于启用"帧（Frame）"通道。

Runtime\Net\Core\Private\Net\Core\Trace\Reporters\NetTraceReporter.cpp

模块（Module）

模块加载信息。

Runtime\Core\Private\ProfilingDebugging\ModuleDiagnostics.cpp

  • Win64

  • XBox

  • PS4/PS5

  • Switch

调用堆栈（Callstack）

调用堆栈信息。用于关联调用堆栈和分配。

需要启用模块（Module）通道进行符号解析。

Runtime\Core\Private\ProfilingDebugging\CallstackTrace.cpp

  • Win64

  • XBox

  • PS4/PS5

  • Switch

内存分配（MemAlloc）

内存分配。使用模块和调用堆栈。

Runtime\Core\Private\ProfilingDebugging\MemoryAllocationTrace.cpp

  • Win64

  • XBox

  • PS4/PS5

  • Switch

内存标签（MemTag）

内存标签统计数据。定期追踪各个标签的内存使用快照。依赖LLM子系统进行追踪。默认包含"-llm"。Init()之后可用。

Runtime\Core\Private\HAL\LowLevelMemTracker.cpp

可视化日志（VisualLogger）

可视化日志用于将记录写入文件。

Runtime\Engine\Private\VisualLogger\VisualLoggerTraceDevice.cpp

物理（Physics）

混乱视觉效果调试器。

Runtime\Experimental\Chaos\Private\ChaosVisualDebugger\ChaosVisualDebuggerTrace.cpp

动画（Animation）

动画Insights(GameplayInsights/RewindDebugger)插件。

Runtime\Engine\Private\Animation\AnimTrace.cpp

物体（Object）

GameplayInsights/RewindDebugger 插件。 UObject 类、世界、实例和事件。

Runtime\Engine\Private\ObjectTrace.cpp

物体属性（ObjectProperties）

GameplayInsights/RewindDebugger 插件。

Plugins\Animation\GameplayInsights\Source\GameplayInsights\Private\ObjectPropertyTrace.cpp

网络预测（NetworkPrediction）

网络预测Insights插件。

Plugins\Runtime\NetworkPrediction\Source\NetworkPrediction\Private\NetworkPredictionTrace.cpp

RDG

RDG Insights 插件。

Runtime\RenderCore\Private\RenderGraphTrace.cpp

Slate

Slate Insights插件。

Runtime\SlateCore\Private\Trace\SlateTrace.cpp

Niagara

Niagara 插件。

Plugins\FX\Niagara\Source\Niagara\Private\NiagaraTrace.cpp

消息（Messaging）

UDP通信插件。

Plugins\Messaging\UdpMessaging\Source\UdpMessaging\Private\UdpMessagingTracing.cpp

追踪源过滤（TraceSourceFilters）

追踪源过滤插件。

Plugins\Developer\TraceSourceFiltering\Source\SourceFilteringTrace\Private\SourceFilterTrace.cpp

姿势搜索（PoseSearch）

姿势搜索插件。

Plugins\Experimental\Animation\PoseSearch\Source\Runtime\Private\Trace\PoseSearchTraceLogger.cpp

Concert

Concert插件。

Plugins\Developer\Concert\ConcertMain\Source\ConcertTransport\Private\ConcertLogGlobal.cpp

关卡快照（LevelSnapshots）

关卡快照插件。

Plugins\VirtualProduction\LevelSnapshots\Source\LevelSnapshots\Private\LevelSnapshotsLog.cpp

一些插件或运行时代码会自动启用或禁用通道，如下表所示：

插件

通道描述

游戏Insights/回溯调试器（Gameplay Insights/ Rewind Debugger）

当编辑器内播放（Play in Editor（PIE））启动时切换开关 物体（Object） 通道，并且在开始记录时切换开关 物体属性（ObjectProperties）、 动画（Animation） 和 帧（Frame) 通道。

追踪源过滤（TraceSourceFiltering）

当插件启动时，追踪源过滤（TraceSourceFilters） 通道会打开。

网络预测（NetworkPrediction）

当插件启动时，网络预测（NetworkPrediction） 通道会打开。

姿势搜索（PoseSearch）

当插件启动时，姿势搜索（PoseSearch） 通道会打开。

可视化日志（VisualLogger）

进行记录时，可视化日志（Visual Logger） 通道会打开。

-NetTrace=1

从指令行启用时，网络（Net） 和 帧（Frame） 通道会打开。

控制运行时

宏

为了将 虚幻引擎 的众多功能最大化，你可以使用宏和指令行来自定义项目输出。除此之外，鼠标和键盘输入快捷键可以帮助用户更高效地使用Insights窗口。 参考下表来基于你想要看到的数据判断要调整哪一个宏：

宏名称

默认状态

源文件

区域描述

UE_TRACE_ENABLED

开启

Engine/Source/Runtime/TraceLog/Public/Trace/Config.h

整个系统的中央控制。

UE_TASK_TRACE_ENABLED

开启

Engine/Source/Runtime/Core/Public/Async/TaskTrace.h

控制任务图表（Task Graph）事件的追踪。 -trace=default,task

LOGTRACE_ENABLED

开启

Engine/Source/Runtime/Core/Public/Logging/LogTrace.h

控制是否将日志消息报告至虚幻引擎。 -trace=log

MISCTRACE_ENABLED

开启

Engine/Source/Runtime/Core/Public/ProfilingDebugging/MiscTrace.h

控制书签、帧、线程和线程组的追踪。 -trace=bookmark,frame

CPUPROFILERTRACE_ENABLED

开启

Engine/Source/Runtime/Core/Public/ProfilingDebugging/CpuProfilerTrace.h

控制CPU定时器和计时事件。 -trace=cpu

LOADTIMEPROFILERTRACE_ENABLED

开启

Engine/Source/Runtime/CoreUObject/Public/Serialization/LoadTimeTrace.h

控制加载资产相关事件的追踪。

加载时间追踪（Load time tracing）在编辑器版本中可能无法正常工作（在使用运行时加载器的打包游戏中，流送代码完全不同）。建议只在打包游戏的情况下使用加载时间跟踪。

-trace=loadtime

STATSTRACE_ENABLED

开启

Engine/Source/Runtime/Core/Public/Stats/StatsTrace.h

控制统计数据计数的追踪。 -trace=stats

PLATFORMFILETRACE_ENABLED

开启

只在Windows、Mac和PS4平台上默认启用。

Engine/Source/Runtime/Core/Public/ProfilingDebugging/PlatformFileTrace.h

控制文件活动的追踪，比如打开、关闭、读取和写入文件。 -trace=file

PLATFORM_SUPPORTS_PLATFORM_EVENTS

开启

Engine/Source/Runtime/Core/Private/ProfilingDebugging/PlatformEvents.h

在支持平台事件（场景切换事件）的平台上启用。 -trace=ContextSwitch

GPUPROFILERTRACE_ENABLED

开启

Engine/Source/Runtime/RHI/Public/GpuProfilerTrace.h

控制GPU定时器和计时事件。 -trace=gpu

UE_NET_TRACE_ENABLED

开启

Engine/Source/Runtime/Net/Core/Public/Net/Core/Trace/NetTrace.h Engine/Source/Runtime/Net/Core/Public/Net/Core/Trace/Config.h

控制网络包体内容的追踪。 -trace=net

UE_MEMORY_TAGS_TRACE_ENABLED

开启

Engine/Source/Runtime/Core/Public/ProfilingDebugging/TagTrace.h

启用标签scope的追踪。禁用后，追踪到的内存分配不会被关联标签。 -trace=memtag

UE_CALLSTACK_TRACE_ENABLED

开启

Engine/Source/Runtime/Core/Public/ProfilingDebugging/CallstackTrace.h

启用追踪调用堆栈。禁用后，追踪到的内存分配不会包含调用堆栈。 -trace=callstack

UnrealInsights.exe的指令行选项

指令行选项

使用方式

描述

-OpenTraceId

-OpenTraceId=id

Unreal Insights强制开始分析 "查看模式（Viewer mode）" 中指定的ID。

-OpenTraceFile

-OpenTraceFile=file.utrace

Unreal Insights强制开始分析 "查看模式（Viewer mode）" 中指定的文件。

-Store

-Store=address:port

-StoreHost=address 和 -StorePort=port

控制台指令

指令

描述

Trace.Send <Host> [ChannelSet]

开始追踪至一个追踪存储器。是追踪存储器的IP地址或者主机名。[ChannelSet]是可选的要启用的通道/预设的逗号分隔列表。

Trace.File [<File>] [ChannelSet]

开始将事件追踪至一个文件。如果不指定文件路径，默认的utrace文件保存路径为 YourProject/Saved/Profiling。如果不指定文件名，utrace文件名会基于当前时间戳自动生成。支持Late Connect。

用例：

  • trace.file [ChannelSet] 文件的路径为 YourProject}/Saved/Profiling/。文件名 *.utrace. Filename 自动生成。

  • trace.file MyFile.utrace [ChannelSet] 的路径为 YourProject/Saved/Profiling/MyFile.utrace。

  • trace.file C:/Path/ [ChannelSet] 是绝对的文件路径，文件名自动生成。

  • trace.file Path/ [ChannelSet] 是 YourProject/Saved/Profiling/ 的相对路径，文件名自动生成。

Trace.Start[ChannelSet]

保持默认启用的通道。

Trace.Stop

停止追踪分析事件。

Trace.Enable[ChannelSet]

启用一组通道。

Trace.Disable[ChannelSet]

停用一组通道。如果不指定通道组，所有通道都会禁用。

Trace.Pause

暂停所有正在传输事件的追踪通道。

Trace.Resume

继续先前暂停的追踪（重新启动暂停的通道）。

Trace.Status

在控制台显示追踪状态。

控制Unreal Insights

指令行选项

与宏结合，以下指令行选项会启用追踪数据：

指令行选项

描述

-trace -trace=<channel1>

-trace=cpu,frame,bookmark

tracehost=<ip>

-tracehost 的相关信息，参阅Unreal Insights

-tracefile, -tracefile =<filename>

运行 "WriteTo" 文件追踪控制指令。将会运行追踪默认指令。

-tracefiletrunc

-tracetailmb= N

N指定追踪尾部缓冲大小，以MiB为单位。默认追踪尾部缓冲大小为4MiB。

-notraceserver

如果指定，游戏或者编辑器不i会启动本地追踪服务器。

-statnamedevents

记录统计命名事件的追踪数据。通过 GCycleStatsShouldEmitNamedEvents = 1; 启用，或者调用 "Stat NamedEvents" 控制台指令。

-verbosenamedevents

记录冗长命名事件的追踪数据。通过 GCycleStatsShouldEmitVerboseNamedEvents = 1; 启用，或者调用 "Stat VerboseNamedEvents" 控制台指令。冗长循环状态示例："CPU Stall - [...]", "Other TaskGraph Stalls", "FQueuedThread::Run.WaitForWork"。

键盘输入快捷键

所有输入和控制参考都是有限的并且可能改变。

计时Insights窗口（Timing Insights）

以下鼠标和键盘指令可以帮助你更高效地使用计时Insights：

帧面板（Frames Panel）

输入快捷键

功能

左键点击

选择一帧

时间视图会将选中的帧居中。

右键点击

打开菜单

左/右键拖动

水平缩放

鼠标滚轮

水平缩放

Shift + 鼠标滚轮

垂直缩放

计时面板（Timing Panel）

输入快捷键

功能

左/右键拖动

水平或垂直拖动

Ctrl + 左/右键拖动

水平拖动

Shift + 左/右键拖动

垂直拖动

*鼠标滚轮**

缩放

Ctrl + 鼠标滚轮

水平滚动

Shift + 鼠标滚轮

垂直滚动

右键点击

打开菜单

选项可以用于图表轨道（Graph track）。

左键点击时间事件

选择时间事件

左键点击空白

清楚选择

Ctrl + 左键双击

选择选中时间事件的时间区间

回车键也是相同的功能。

时间尺（Time Ruler）上左/右键拖动

选择时间区域

计时（Timers）和计数（Counters）视图中会自动更新汇总。

Ctrl+F

开关快速查找菜单。

F

构建上一个选择，然后会在构建时间区间和时间事件之间切换

上一个选择可以是时间区间也可以是时间事件。

G

切换图表轨道（Graph track）可视度，显示游戏和渲染帧，包括计数（Counter Series）的占位符。

Y

切换GPU计时轨道（GPU Timing track）可视度

U

切换CPU计时轨道（CPU Timing track）可视度

I

切换I/O概况和活动轨道（Activity track）可视度

O

切换I/O活动轨道（I/O Activity track）内文件活动的背景事件的可视度

L

切换资产加载轨道（Asset Loading track）可视度

C

在正常和紧凑模式中切换，改变时间事件的显示方式。

V

自动隐藏空白时间轴。

空白时间轴中没有时间事件。

X

选择下一个事件深度限制：单线（Single Lane）、4线、无限。

B

切换书签的可视度

书签默认显示。

M

切换时间标记（Time markers）的可视度（全部追踪日志而不只是书签）

时间标记默认不显示。

缩放

Ctrl + 方向箭头

水平和垂直移动视角

方向键

选择其前一个或者下一个子母时间事件

回车键

选择当前选中时间事件的时间区间

Ctrl + 左键双击也是同样的功能。

网络Insights窗口

以下鼠标和键盘指令可以帮助你更高效地使用网络Insights：

输入快捷键

功能

左键点击包体

选择对应的包体

Shift + 左键点击不同的包体

选择一个区间的包体

Ctrl + A

选择所有包体

左右方向键

选择上一个/下一个包体

Shift + 左右方向键

左右延申选择（多个包体）

Ctrl + shift + 左右方向键

左右收缩选择（多个包体）

双击事件

选中全部含有包体内容视图中事件的包体，同时遮住所有其它事件