Unreal Insights Reference

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

Windows
MacOS
Linux

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.

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,...

Allows users to manage how much trace data to generate by categorizing events into named groups

For example, -trace=cpu,frame,bookmark enables CPU profiler events, frame markers, and bookmarks.

-tracehost

tracehost=X

To learn about -tracehost, read the Unreal Insights Overview .

Available trace channels include:

  • Log

  • Bookmark

  • Frame

  • CPU

  • GPU

  • LoadTime

  • File

  • Net

Deprecated Command-Line Options

The following command-line options are deprecated (still available, but will be removed in a future version of UE):

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,...

For 4.24, use -statstrace.

Enable with #define EXPERIMENTAL_STATSTRACE_ENABLED 1 in Engine\Source\Runtime\Core\Public\Stats\StatsTrace.h.

Counters

TRACE_COUNTER_* macros

-trace=frame,counters,...

For 4.24, use -counterstrace.

See Source\Runtime\Core\Public\ProfilingDebugging\CountersTrace.h.

Learn more in the 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

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

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