To get the most out of the many features that ship with Unreal Insights, users can customize their project's output with macros and command-line options. Also, mouse and keyboard input shortcuts allow users to navigate Insights windows more efficiently.
Trace
Trace is a structured logging framework for tracing instrumentation events from a running process.
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 |
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,... |
Allows users to manage how much trace data to generate by categorizing events into named groups -trace=cpu,frame,bookmark enables CPU profiler events, frame markers, and bookmarks. |
-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 |
Connects Browser with specified trace store -StoreHost=address and -StorePort=port are also available. |
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 . |
Input Shortcuts
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 |
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 |
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 |
Left/right mouse drag over Time Ruler | Select time region |
F | Frame the last selection and then alternate between framing the time range or the 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 |
B | Toggle visibility of bookmarks |
M | Toggle visibility of time markers (all trace logs instead of just bookmarks) |
D | Enable downsampling |
**-/+ | 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 |
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 |