Unreal Insights

The Unreal Insights system for performance profiling

Windows
MacOS
Linux

When optimizing performance, profiling data is invaluable for identifying, and ultimately eliminating, the bottlenecks in your project. Unreal Insights is a standalone profiling system that integrates with Unreal Engine 4 (UE4) to help developers collect, analyze, and visualize data emitted by the Engine. In addition to providing robust coverage of the Engine's existing systems, Unreal Insights makes it easy to add your own profiling data. Finally, the system features the capability to record data remotely, creating the minimum possible impact on your project's execution.

Unreal Insights System Setup

The Unreal Insights Tool ships with UE4, and is located in the Engine/Binaries/Win64 directory. For users who download the UE4 source code and compile it locally, you can compile it either by building the entire UE4 solution in Development or Shipping mode, or by building the "UnrealInsights" project directly.

UnrealInsightsProjectVisualStudio.png

Once you have located or built the compiled program (UnrealInsights.exe), run it on the machine that you want to use to record your data or view your live session. We recommend that this be different from the one running your project in order to minimize the performance impact of the tool itself, but it is possible to run both the project and the tool on a single computer. It is important that the tool is running first; the project will attempt to connect to the tool as soon as it starts up. If the tool is running remotely, provide its IP to the project by launching the project with the following command-line option and replacing "X" with the IP:

-tracehost=X

You should see your live session appear in the tool similarly to how it does in the following image:

UnrealInsightsLiveSession.png

Inside the tool are three windows, each indicated by a tab at the top of the user interface. The first is the Unreal Insights Window, which helps to manage different sessions by connecting, disconnecting, and selecting live or pre-recorded sessions for viewing. The other two, the Timing Insights Window and the Asset Loading Insights Window, browse and visualize performance data, and will appear once a session is ready for viewing.

Unreal Insights Window

When the tool starts up, the Unreal Insights Window will be open. In the top section of the window, labeled Trace Sessions, you can initially see a list of all pre-recorded sessions that you can load for analysis. These correspond to the .utrace files in your Local Session Directory. You can double-click any of these trace sessions (or select a trace session and click the Open button), or you can search for .utrace files elsewhere with the Open button's dropdown arrow.

UnrealInsightsToolOpening.png

The Unreal Insights Window upon opening.

If a live UE4 session connects to the tool, it will also appear in the list, generally at the bottom. Multiple sessions can be connected at the same time, and the tool will automatically record data for all of them as it comes in. You can analyze these sessions live by loading them from the list, just as you would with pre-recorded sessions. Live sessions have the word "LIVE" in the status column, and update in real time while you analyze them, but are otherwise identical to pre-precorded sessions.

UnrealInsightsLiveSession.png

A live session available for real-time analysis in the Unreal Insights Window.

The Trace Recorder section features a Stop button to stop trace recording without closing the tool. This is useful for stopping the flow of new data into a live session after you have collected the data you need, but before the session has ended — which can make it easier to read. Pressing this button will also disconnect the tool from any sessions currently running, and prevent new sessions from connecting. While recording is stopped, the Start appears in place of the Stop button. Restarting recording will enable new remote UE4 sessions to connect, but will not connect to any sessions that started while trace recording was stopped, and will not reconnect to sessions that were dropped by the Stop button.

UnrealInsightsStopped.png

The bottom section, labeled New Connection, features an experimental Connect button and a text-entry field for users to enter the IP of a UE4 session already in progress. This is intended primarily for use with game consoles, but is still a work in progress and may not be reliable yet. Look for futher iteration on this feature in future releases. At present, starting the Unreal Insights Tool before launching the project and using the -tracehost command-line option for your project is the sole recommended procedure.

Timing Insights Window

The Timing Insights Window is where you'll see your per-frame performance data for the CPU and GPU come together. There are several panels where you can look at different visualizations of the time your project spends on various tasks, select blocks of time to view in aggregate, sort or categorize data, and review log output. You can show or hide these panels with the five buttons along the top row, labeled Frames, Timing, Timers, Stats, and Log. These buttons show or hide the Frames Panel, Timing Panel, Timers Tab, Stats Counters Tab, and Log Panel, respectively.

TimingInsightsPanels.png

The Timing Insights Window, featuring (1) the Frames Panel, (2) the Timing Panel, (3) the Log Panel, and (4) the Timers Tab and Stats Counters Tab (with the Timers Tab active)

A key feature of the Timing Insights Window is the ability to select a single frame or period of time and show performance information collected during that time by highlighting and zooming the Timing Panel, and aggregating data in the Timers Tab and Stats Counters Tab. To do this, you can click on a single frame in the Frames Panel, or click and drag a section of the scrub bar at the top of the Timing Panel, known as the Time Ruler.

Frames Panel

The Frames Panel shows the total time taken by each frame, using a bar graph format. This is good for identifying general trends, such as the framerate lowering when a certain level is loaded or an unoptimized scene is visible, or discovering the reason for an individual frame being slow, such as spawning a large number of Actors all at once. Since taller bars represent longer frames, it's easy to pick out the exact moment when these events happen, and examine the data to see which operations are responsible. Hovering the cursor over a bar causes that frame's index and the time it took to run to appear. If you then left-click the bar, you can isolate data for that frame in the Timing Panel, Timers Tab, and Stats Counters Tab.

FramesPanel.png

A selected frame within the Frames Panel. The white bracket marker shows the set of frames visible within the Timing Panel.

Timing Panel

The bulk of your focus within the Unreal Insights Tool will likely be spent on the Timing Panel. This panel shows a visual representation of each instance of every timer event that has run during a session. Unlike the Frames Panel, which provides an overview of whole frames, the Timing Panel shows individual trace events and provides time measurements with sub-microsecond precision. These events stack vertically to indicate scope, and use separate tracks to show activity on different threads. Within the track display, events are broken out by thread, divided vertically to show scope, and positioned horizontally based on their start and end times.

TimingPanel.png

(1) The tooltip that appears when hovering over a timer event within the Timing Panel. (2) A stack of nested events on the same thread.

You can turn groups of related threads on or off in the "Tracks" dropdown in the upper-left corner of the panel. Hovering the mouse cursor over a block in any track reveals information about that timer event, and clicking on it locates and selects the event in the Timers Tab.

TracksDropdown.png

The Timing Panel features a dropdown menu to hide or show groups of tracks based on what threads they contain.

When working with the Timing Panel, you may wish to see aggregate data for a specific time range. You can select the period of time that you want to examine by clicking and dragging across the Time Ruler, double-clicking a timer event in the Timing Tab, or clicking a frame in the Frames Panel. When you do this, the selected time range appears as a blue overlay with its total length shown at the top, and the Timer Tab and Stats Counter Tab show only the data that falls within that time range. You can then press "F" to zoom and pan directly to the selected time range.

Timers Tab and Stats Counters Tab

The Timers Tab lists all timer events that have run within the time range designated in the Timing Panel, while the Stats Counters Tab lists all stats that were incremented during the same period. In addition to aggregating data based on time range, this list can be sorted in ascending or descending order by the values in any active column. To change sort order, or to activate or deactivate columns, right-click anywhere in the list. The following columns are available:

For the Timers Tab:

  • Meta Group Name

  • Type

  • Instance Count

  • Total Inclusive Time

  • Max Inclusive Time (ms)

  • Average Inclusive Time (ms)

  • Median Inclusive Time (ms)

  • Min Inclusive Time (ms)

  • Total Exclusive Time

  • Max Exclusive Time (ms)

  • Average Exclusive Time (ms)

  • Median Exclusive Time (ms)

  • Min Exclusive Time (ms)

For the Stats Counter Tab:

  • Meta Group Name

  • Type

  • Count

  • Sum

  • Maximum

  • Upper Quartile (not yet implemented in 4.23)

  • Average

  • Median

  • Lower Quartile (not yet implemented in 4.23)

  • Minimum

Both lists also feature the Group By dropdown list box, which has the ability to separate the list into groups by name or type, or combine them all into a single, flat group. You can then expand or collapse groups to view just the data you need to see.

TimersTabByName.png

The Timers Tab, broken up into groups based on name.

The Stats Counters Tab will be empty by default, as this feature is considered experimental and deactivated by default.

Log Panel

The Log Panel displays all logs (generated by UE_LOG calls) from the UE4 session. The logs can be filtered by verbosity and category, just as in the Output Log window in the Editor. It also features a search box that filters out all log messages that don't match the text you enter. In addition to filtering, clicking on any row will pan the Timing Panel to the time when that row's text was logged.

LogPanel.png

Selecting a period of time in the Timing Panel will highlight all log entries that fall within that time in blue. Conversely, if you select multiple log entries, by clicking one entry and then shift-clicking another, the Timing Panel will highlight the time range between those entries.

Quick Control Reference

The following mouse and keyboard commands will help you to navigate the Timing Insights more efficiently. This is not an exhaustive list of all input operations, and may change as the tool develops in the future.

Input

Function

Mouse Wheel

Zoom in/out of a track

Shift + Mouse Wheel

Scroll or zoom the track vertically

Ctrl + Mouse wheel

Scroll or zoom the track horizontally

C

Toggle Compact mode

F

Fit the screen to the selected time range

Y

Toggle GPU Track

U

Toggle CPU tracks

I

show / hide I/O tracks (hidden by default)

V

Toggle showing empty timeline tracks

B

Toggle display of bookmarks in the Timing Panel

M

Toggle display of markers for all log messages in the Timing Panel

L

Show or hide Asset Loading tracks (hidden by default)

G

Toggle Graph

‘Ctrl’ + ‘+’

Zoom in

‘Ctrl’ + ‘-’

Zoom out

‘Ctrl’ + ‘Left’

Pan left

‘Ctrl’ + ‘Right’

Pan right

Asset Loading Insights Window

To assist in analyzing Asset loading performance, the Unreal Insights Tool features the Asset Loading Insights Window. This window contains a specialized version of the Timing Panel from the Timing Insights view that has been configured to focus on events related to loading Assets.

AssetLoadingInsights.png

The Asset Loading Insights Window focuses on performance related to loading Assets. The session shown here was recorded with the -loadtimetrace command-line option.

Customizing Your Project's Output

By making some minor changes to Engine, Plugin, or Project source code, you can activate or deactivate certain Unreal Insights features, or add custom logging.

Activating or Deactivating Logging

If you want to exercise control over which areas send logging data, or if you simply want to deactivate the entire system, you can do this by editing the Engine's source code and changing the values of certain macros. These macros are spread across the engine, generally in header files for the relevant features or modules. They use the value "1" for areas that have logging turned on, and "0" where it's off, but are always defined within a conditional structure that first determines whether or not the macro is appropriate within the context of the build. As an example, the macro that controls the entire system, LOGTRACE_ENABLED, resides in Engine/Source/Runtime/Core/Public/Logging/LogTrace.h within the following structure:

#if !IS_PROGRAM && !UE_BUILD_SHIPPING && (PLATFORM_WINDOWS || PLATFORM_PS4 || PLATFORM_XBOXONE)
#define LOGTRACE_ENABLED 1
#else
#define LOGTRACE_ENABLED 0
#endif

By default, LOGTRACE_ENABLED is defined as "1" in builds where it is appropriate to send log data to the Unreal Insights system. To deactivate it, the second line in the code above would be changed so that LOGTRACE_ENABLED is defined as "0" rather than "1". Use the following table to determine which macros you wish 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/Private/Trace.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

Off

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

Controls GPU timers and timing events

The following UE4 command-line options, combined with some of the macros above, enable additional trace data.

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.

-statnamedevents

CPUPROFILERTRACE_ENABLED

If combined with -cpuprofilertrace, this option will activate even more CPU 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 considered experimental in UE4 version 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.

Adding Custom Logging

To add logging to your own Engine features, Plugins, or Projects, invoke the TRACE_CPUPROFILER_EVENT_SCOPE macro at the scope that you wish to profile. This macro takes a single text argument to identify the trace group that will own the profiling data it generates. You can use any name you like, but common examples might look like TRACE_CPUPROFILER_EVENT_SCOPE(TEXT("MyClass::Function")) or TRACE_CPUPROFILER_EVENT_SCOPE(TEXT("ReticulatingSplines")). Remember that the UE_LOG macro shows up in Unreal Insights, so putting logs near areas of the code that you want to investigate could help you to find the information you need faster when analyzing data.

Advanced Tracing

With advanced tracing, it is possible to log events from platforms, such as Android and PC.

Android

Using Android Debug Bridge (adb), Android tools can redirect TCP traffic over a USB cable. To connect a runtime application on an Android device, first instruct adb to pass through TCP connections made on the device over USB:

adb.exe reverse tcp:1980 tcp:1980

Unreal Insights listens on TCP port 1980.

When running on the device, it should connect to localhost, such that the operating system will route traffic across the USB cable.

-tracehost=127.0.0.1

Files

Trace can output to a file using the -tracefile=PATH command line argument. The value of PATH is specific to the platform being traced, including PC and Android.

PC

-tracefile=d:/foo/bar.utrace

Android

-tracefile=/sdcard/UE4Game/foobar.utrace

While any user-specified path should work, the /sdcard/ path may vary depending on the Android OS version and device manufacturer.

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