Trace
An Overview of using the Trace logging framework in Unreal Insights.
Unreal Insights is a telemetry capture and analysis suite that can capture events from your project at high data rates. It identifies areas of data that require optimization. The major components of Unreal Insights are:
Trace events, which contain
EventNameandFieldNameparameters to define an event and specify a field that the event should include.The Unreal Trace Server, which recrods and saves traces from the application.
Unreal Insights, which analyzes and visualizes the data.
a visualization of the major components of the Unreal Insights framework.
Trace sessions are self-describing, and compatible with different engine release versions. They are stored in .utrace files. Any companion data that is generated is stored in .ucache files located within the same directory as your trace files.
Setting Up Unreal Insights
Launch From Editor
To start Unreal Insights from the Unreal Editor, navigate to the Trace/Insights Status Bar Widget located in the bottom toolbar of the Editor.
When you run a Trace to profile your project data, you can choose from multiple workflow options that vary depending on your Unreal Engine Build and Operating System. For more information about these workflow options. See the following pages:
Launch a prebuild of Unreal Insights
If you installed a binary version of Unreal Engine you should have a compiled version of Unreal Insights located in the following directory:
Engine\Binaries[Platform]\UnrealInsights[.exe] Build From Source
If you don't have a binary version of the engine installed, or you want to compile Unreal Insights from source, you can use the following options:
Using an Integrated Development Enviroment(IDE). Find the UnrealInsights target located in the Programs folder.
From the command prompt. In your engine installation folder build Unreal Insights using the Unreal Build Tool:
On Windows:
Engine/Build/BatchFiles/RunUBT.bat UnrealInsights Win64 DevelopmentOn Linux or Mac:
./Engine/Build/BatchFiles/RunUBT.sh UnrealInsights [Linux|Mac] DevelopmentTrace
Trace is a structured logging framework for tracing instrumentation events from a running process. The Unreal Trace Server runs in the background as a single server instance and can be shared between multiple projects or branches. It is an optimized program that has minimal impact on performance and does not include a User Interface.
The Trace Server is launched automatically by a separate server process executable, UnrealTraceServer.exe, which is located in the Engine/Binaries/Win64 directory folder.
The Trace Server has two components:
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 in a folder. It watches this folder for changes and exposes the list of available traces to Unreal Insights UI.
An example of the path to the trace folder is:
C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001/For additional documentation see the following pages:
-Trace -Trace Quick Start Guide -Trace Developer Guide
Unreal Insights Session Browser
The Unreal Insights Session Browser is an interface to observe trace data. To launch the browser, navigate to the bottom toolbar, and click Trace > Insights > Unreal Insights (Session Browser.)
Trace Store
The Trace Store is an interface for you to observe and manage all of your stored Trace Sessions. The recorded traces are stored as files in a folder and Unreal Insights watches this folder for any data changes and then exposes the list of available traces to Unreal Insights UI.
|
Numeric Index |
Category |
Description |
|---|---|---|
|
(1) |
Trace Store Panel |
Opens and manages your trace files for analysis. |
|
(2) |
Trace Story Directory |
Displays and Opens the directory path to the Trace Sessions. |
|
(3) |
Trace Sessions |
Lists pre-recorded sessions that you can load for analysis. These correspond to the |
|
(4) |
Session Filters |
Sort your trace files into Platform, App Name, Config, Target, and Branch categories. |
|
(5) |
Search Bar |
Filters your searches by command line or name. |
|
(6) |
Connection Tab |
Sets up connections to a remote trace server. |
Connection Tab
The connection tab allows you to connect to a running game or editor with a trace server. It features multiple options to change your connection settings.
|
Numeric Index |
Category |
Description |
|---|---|---|
|
(6) |
Connection Tab |
Manages the connection between a remotely running game or editor to a trace server. |
|
(7) |
Trace Recorder IP address |
The IP address of the trace server. |
|
(8) |
Running Instance IP address |
The IP address of the project(running instance) that connects with the trace server to begin tracing data. |
|
(9) |
Initial channels |
A field to specify the list of trace channels to be enabled when the trace connection begins analyzing data. |
Load a Trace for Analysis
There are multiple options to choose to load a Trace for Analysis. You can:
Double-click any trace session in the Unreal Insights Browser.
Select a trace session and click Open Trace.
Search for
.utracefiles in other locations by using the Open Trace drop-down arrow.Start an analysis of a respective trace file immediately, drag and drop a .utrace file from Explorer over the Unreal Insights window.
Live Connect
If a live Trace session connects to the tool, it also appears in the list. Live sessions display the word LIVE in the status column and update in real-time while you analyze them. Otherwise, they are identical to pre-recorded sessions.
The tool can connect to multiple sessions at the same time, and it automatically records data for all of them as the data streams in. To analyze these sessions in real-time, load them from the list the same way you load pre-recorded sessions.
Timing Insights Window
The Timing Insights window collects performance data. It displays the data for CPU and GPU tracks. These tracks feature multiple sub-menus to help you sort and visualize the various processing tasks and the amount of time your project spends on executing them.
The Timing Insights window features the Frames panel (1), the Timing panel filters (2), the Timing panel (3), the Log panel (4),Timers and Counters tabs (5) and the Callers and Callees panels (6).
See the Timing Insights
Memory Insights
The Memory Insights component allows you to investigate memory usage and call stack tracing in your project.
Memory Insights traces events for every allocation, reallocation, or free event that occurs during runtime, then reconstructs that memory usage pattern during analysis.
See 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 for additional documentation.
Slate Insights
Slate Insights extends Unreal Insights to help developers improve the performance of their UI. it provides tools to identify the root cause of a specific Slate and UMG update.
See Slate Insights for additional documentation.
Asset Loading Insights
Asset Loading Insights provides a way to profile the amount of time it takes to load a project's assets into UnrealEngine. It can give you a detailed understanding of data sets per asset type. Asset Loading Insights is based on the data traced from the AssetLoadTime trace channel.
Cooking Insights
Unreal Cooking Insights allows you to gather and display information about the way packages are cooked in your project. Long cooking times can significantly affect the productivity of teams that are working on larger projects. By displaying the time it takes to cook each package, you can observe which packages to focus your investigation into optimizing. See Cooking Insights for additional documentation.
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 for additional documentation.
