Unreal Insights Reference

Unreal Insights reference covering input shortcuts, macros, and command-line options

Choose your operating system:

Windows

macOS

Linux

Trace

Trace is a structured logging framework for tracing instrumentation events from a running process.

Trace

Macros

Reference the following table to determine which macros you want to adjust based on the data that you want to see in the Unreal Insights Tool:


Macro name	Default State	Source File	Area Description
`UE_TRACE_ENABLED`	On	`Engine/Source/Runtime/TraceLog/Public/Trace/Config.h`	Master control for the entire system
`LOGTRACE_ENABLED`	On	`Engine/Source/Runtime/Core/Public/Logging/LogTrace.h`	Controls whether log messages are reported to Unreal Insights
`MISCTRACE_ENABLED`	On	`Engine/Source/Runtime/Core/Public/ProfilingDebugging/MiscTrace.h`	Controls tracing for bookmarks, frames, threads, and thread groups
`CPUPROFILERTRACE_ENABLED`	On	`Engine/Source/Runtime/Core/Public/ProfilingDebugging/CpuProfilerTrace.h`	Controls tracing for CPU timers and timing events
`LOADTIMEPROFILERTRACE_ENABLED`	On	`Engine/Source/Runtime/CoreUObject/Public/Serialization/LoadTimeTrace.h`	Controls tracing for events related to load assets
`EXPERIMENTAL_STATSTRACE_ENABLED` and `STATSTRACE_ENABLED`	Off	`Engine/Source/Runtime/Core/Public/Stats/StatsTrace.h`	Controls tracing for stats counters. Define both macros as "1" to activate
`PLATFORMFILETRACE_ENABLED`	Off On by default for Windows.	`Engine/Source/Runtime/Core/Public/ProfilingDebugging/PlatformFileTrace.h`	Controls tracing for file activity, such as opening, closing, reading, and writing files
`GPUPROFILERTRACE_ENABLED`	On	`Engine/Source/Runtime/RHI/Public/GpuProfilerTrace.h`	Controls GPU timers and timing events
`UE_NET_TRACE_ENABLED`	On	`Engine\Source\Runtime\Net\Core\Public\Net\Core\Trace\NetTrace.h` * `Engine\Source\Runtime\Net\Core\Public\Net\Core\Trace\Config.h`	Controls tracing of network packet content

Command-Line Options

When combined with macros, the following command-line options enable trace data:


Command-Line Option	Usage	Description
`-statnamedevents`	`CPUPROFILERTRACE_ENABLED`	If combined with `-trace=cpu` , this option will activate even more CPU timing events.
`-trace`	`-trace=channel1,channel2,...`	`-trace=cpu,frame,bookmark`
`-tracehost`	`tracehost=X`	`-tracehost` , read the Unreal Insights Overview

Available trace channels include:

Log
Bookmark
Frame
CPU
GPU
LoadTime
File
Net

Removed Command-Line Options

The following command-line options were removed:


Command-Line Option	Required Macro	Effect
`-cpuprofilertrace`	`CPUPROFILERTRACE_ENABLED`	Running with this option populates the Timing View with multiple CPU thread tracks containing timing events.
`-filetrace`	`PLATFORMFILETRACE_ENABLED`	For traces generated with this option, the Unreal Insights Tool will feature two I/O activity tracks in the Timer tab, which you can view by pressing the "I" key or enabling "I/O Tracks" in the "Tracks" dropdown. This functionality is experimental in 4.23.
`-loadtimetrace`	`LOADTIMEPROFILERTRACE_ENABLED`	This option causes the Asset Loading Insights window to include a "Loading - Main Thread" track and a "Loading - Async Thread" track.

Command-Line Options for UnrealInsights.exe


Command-Line Option	Usage	Description
`-OpenTraceId`	`-OpenTraceId=id`	Forces Unreal Insights to start analyzing the specified ID in "Viewer mode"
`-OpenTraceFile`	`-OpenTraceFile=file.utrace`	Forces Unreal Insights to start analyzing the specified file in "Viewer mode"
`-Store`	`-Store=address:port`	`-StoreHost=address` and `-StorePort=port`

Experimental Stats and Counters

The Counters tab can display counters from two API sources:


API Source	Example	Command Line Argument	Notes
Stats	`TRACE_STAT_*` macros	`-trace=frame,stats,...` `-statstrace`	Enable with `#define EXPERIMENTAL_STATSTRACE_ENABLED 1` in `Engine\Source\Runtime\Core\Public\Stats\StatsTrace.h` .
Counters	`TRACE_COUNTER_*` macros	`-trace=frame,counters,...` `-counterstrace`	See `Source\Runtime\Core\Public\ProfilingDebugging\CountersTrace.h` .

Stats System Overview

Input Shortcuts

All input operations and control references are limited and subject to change.

Timing Insights Window

The following mouse and keyboard commands help you navigate Timing Insights more efficiently:

Frames Panel


Input Shortcut	Function
Left mouse click	Select a frame The timing view centers on the selected frame.
Right mouse click	Open context menu
Left/right mouse drag	Horizontal zoom
Mouse wheel	Horizontal zoom
Shift + mouse wheel	Vertical zoom

Timing Panel


Input Shortcut	Function
Left/right mouse drag	Horizontal or vertical pan
Ctrl + left/right mouse drag	Horizontal pan
Shift + left/right mouse drag	Vertical pan
Mouse wheel	Zoom
Ctrl + mouse wheel	Horizontal scroll
Shift + mouse wheel	Vertical scroll
Right mouse click	Open context menu Options available for Graph track.
Left mouse click on Timing Event	Select the timing event
Left mouse click on empty space	Clear selection
Ctrl + double left mouse click	Select time range of selected timing event Pressing ENTER performs the same function.
Left/right mouse drag over Time Ruler	Select time region Aggregated states automatically update in Timers and Counters views.
F	Frame the last selection and then alternate between framing the time range or the timing event The last selection can be a time range or a timing event.
G	Toggle Graph track visibility, showing Game and Rendering frames, including a placeholder for Counter series
Y	Toggle GPU Timing track visibility
U	Toggle CPU Timing track visibility
I	Toggle I/O Overview and Activity track visibility
O	Toggle visibility of background events for file activities in the I/O Activity track
L	Toggle Asset Loading track visibility
C	Switch between normal and compact mode, affecting how timing events are visualized
V	Auto hide empty timelines Empty timelines are ones without timing events.
B	Toggle visibility of bookmarks Bookmarks display by default.
M	Toggle visibility of time markers (all trace logs instead of just bookmarks) Time markers do not display by default.
D	Enable downsampling This debug functionality is enabled by default.
	Zoom
Ctrl + left/right/Up/Down arrows	Horizontal and vertical pan
Left/right/Up/Down arrows	Select timing event that is its previous or next sibling/parent/largest child
Enter	Select time range of selected timing event Pressing Ctrl + Double Left Mouse Click performs the same function.

Networking Insights Window

The following mouse and keyboard commands help you navigate Networking Insights more efficiently:


Input Shortcut	Function
Left mouse click on packet	Selects the respective packet
Shift + left mouse click on different packet	Selects a range of packets
Ctrl + A	Select all packets
Left/right arrows	Selects previous/next package
Shift + left/right arrows	Extends selection (multiple packages) toward Left/right side
Ctrl + shift + left/right arrows	Shrink selection (multiple packages) from Left/right side
Double click an Event	Highlights all packets containing the event in the Packet Content view while masking out all other events