Choose your operating system:
Windows
macOS
Linux
Unreal Insights identifies areas in your project that require optimization. It is a telemetry capture and analyzing suite that provides you the capability to capture events from the application at high data rates.
The major components of Unreal Insights consist of Trace events, the Unreal Trace Server which records and saves traces from the application, and Unreal Insights which analyzes and visualizes the data.
The stored trace sessions are self-describing and backward compatible. They are stored in .utrace
files. With generated companion data being stored in .ucache
files next to the trace file.
Setup
You can run Unreal Insights directly from the Unreal Editor by navigating to Tools > Run Unreal Insights, or by downloading a source build of the Engine, and navigating to the Engine/Binaries/Win64
directory where the Unreal Insights tool ships with Unreal Engine. If you are a developer who downloaded the Unreal Engine source code and compiled it locally, you can compile it either by building the entire Unreal Engine solution in Development or Shipping mode or by building the "UnrealInsights" project directly.
Once you have located or built UnrealInsights.exe
, you can run it on the machine that you want to use to record your data or view your live session.
If Unreal Insights is started before launching the project, the project will connect with the local trace server automatically and the default trace channels will be enabled.
If the tool is running remotely, provide its IP address to the project by launching the project with the following command-line option, replacing the variable "X" with the IP address:
-tracehost=X
The tracehost argument is required when running remote devices on Mac and Linux.
When you launch your project, it will automatically connect to a local trace server if it detects a running instance of the Unreal Insights Session Browser.
The running instance needs to have access to the machine where the trace server is running (the address specified by the command -tracehost). The running instance and the trace server needs to be in the same network domain or public ip address.
You will want to ensure port 1981 is not blocked.
To minimize the tool's impact on your application's performance, we recommend running the tool on a different machine than the project you want to monitor, although this is not required.
Trace
Trace is a structured logging framework for tracing instrumentation events from a running process. The Unreal Trace Server is run in the background as a single server instance and can be shared between multiple projects or branches. It is a lightweight program that has minimal impact on performance and does not include a User Interface.
It is launched by a separate server process executable UnrealTraceServer.exe located in the Engine/Binaries/Win64
directory folder.
The Trace Server has two functionalities:
The Trace Recorder listens on port 1981 for incoming trace connections and records the live trace stream.
The Trace Store stores the recorded traces as files to a path like
C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001/
. It watches this folder for changes and exposes the list of available traces to Unreal Insights UI.
Refer to the Trace Documentation for additional information and Unreal Insights Reference for additional commands you can use to profile your data.
Unreal Insights Session Browser
After starting Unreal Insights, it will open the Unreal Insight Session Browser, which contains the Trace Store panel (1), a directory which contains the Trace Sessions (2), and a Connection menu panel (3).
The Connection menu (4) contains a Trace Recorder IP address (5), a Running Instance IP address (6), and an Initial channel to enable specific traces when connected (7).
When the tool starts up, the Unreal Insights window opens first. In the top section of the window, labeled Trace Sessions, you will see a list of all pre-recorded sessions that you can load for analysis. These correspond to the .utrace
files in your Trace Store Directory. You can double-click any of these trace sessions, or select a trace session and click Open Trace. Alternatively, you can search for .utrace
files in other locations by using the Open Trace dropdown arrow.
To immediately start an analysis of a respective trace file, drag and drop a .utrace
file from Explorer over the Unreal Insights window.
If a live Trace session connects to the tool, it will also appear in the list. 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-recorded sessions. The tool can connect multiple sessions at the same time, and it will automatically record data for all of them as the data streams in. You can analyze these sessions in real time by loading them from the list (just as you would with pre-recorded sessions).
Timing Insights Window
The Timing Insights window collects performance data. you will see per-frame performance data for different tracks along the CPU and GPU tracks. A new toolbar was added to the Timing view, splitting the Tracks drop down menu into multiple menus where you can look at different visualizations of the time your project spends on various tasks.
You can select blocks of time to view in aggregate, sort or categorize data, and review log output. You can show or hide the respective panels.
The Timing Insights window features the Frames panel (1), the Timing panel (2), the Log panel (3), the Timers and Counters tabs (4), and the Callers and Callees panels (5).
See Timing Insights for additional documentation.
Memory Insights
Memory Insights is a new component that provides you the capability to investigate memory usage and call stack tracing in your project.
The runtime component traces events for every allocation, reallocation, or free event that occurs during runtime, then reconstructs that memory usage pattern during analysis.
Refer to the Memory Insights documentation for instructions on how to set up, trace, query, and sort your data.
Networking Insights
Unreal Insights includes Networking Insights to analyze, optimize and debug network traffic.
Refer to the Networking Insights documentation for more information.
Reference
To get the most out of the many features that ship with Unreal Insights, You can customize your project's output with macros and command-line options.
Refer to the Reference