Trace User Guide

An Overview of using the Trace logging framework in Unreal Insights.

Choose your operating system:

Windows

macOS

Linux

Trace is a structured logging framework for tracing instrumentation events from a running process. The framework produces a stream of high-frequency traced events that is self-describing, easily consumed, and easily shared. The modules TraceLog and TraceAnalysis are the principal modules that constitute the framework.

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.

A Tour of Trace

In Unreal, Trace is launched by a separate server process executable UnrealTraceServer.exe located in the Engine/Binaries/Win64 directory folder.

The executable is automatically launched by Unreal Editor builds when you make a connection from the Unreal Trace sessions browser. The Unreal Trace server runs in the background as a single server instance and can be shared between multiple projects and branches.

It is a lightweight program that has minimal impact on performance and does not include a User Interface.If you wish to shut down the process manually, you can do so by accessing your System's Task Manager.

The System Task Manager displays the running Server Trace in the Processes tab.

It can receive and record data from multiple sources simultaneously, and runs in the background as a single instance that does not need to be terminated in order to launch a new version.

Tracing Runtime

You can enable tracing instrumentation events from a runtime to Unreal Insights using the -trace[=channel0[,channel1...]] command line argument. The argument takes an optional comma-separated list of trace channels to trace, or alternatively the name of a .set of channels defined in an .ini file.

To begin using command lines, navigate to Visual Studio and right-click on the Uproject.sln name. Then navigate to Properties > Debugging > Command Arguments > YourGame -trace=default

The .utrace file that is created as a result will be located in the C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001 directory.

You can record trace files even when Unreal Insights is closed, by pressing the tilde key ~ to access the Command line in the Editor and typing in the following command :

    `Trace.Start`

Once the trace has been started, it can be stopped by using the command:

    `Trace.Stop`

if the trace is already running, then you can pause by using the Command:

    `Trace.Pause`  

Or you can resume the trace by using the Command:

    `Trace.Resume`

For a complete list of Trace commands, refer to the Trace reference page documentation.

Tail Tracing

Tail Tracing tracks events over the last few seconds (depending on the buffer size), therefore any machines that may be able to display a lead-up.

The default size of the buffer is 4MB, however if you wish to modify or deactivate it, you can do so by entering the following command using the Command line:

    `-tailtracemb=x` 

Setting X to 0 MB will deactivate it, other values will change the buffer size accordingly.

Improved Late Connect

In previous versions of Unreal Insights, if your connection to the Insights program was late, then any one-time events(Important Events) would be missed before you could make a connection.

Important events are now cached on the Unreal Engine client side, therefore they are sent to late-connecting machines during connection.

Insights can instruct remote running Unreal Engine instances to connect to the remote trace servers from it's local UI instance without needing to involve the local machine.

Late connect can be initiated by navigating to Unreal Insights > Connect, or from the Editor cmd console by typing any of the following commands:

    `"trace.send [ip]" / "trace.start [filename]"

    -trace.start[file][channelSet] -tracehost=[ip]      

    -tracefile = [filepath]

Unreal Insights has a file-based caching system which provides the application the capability to attach additional information to a trace. This can be used to retrieve previously calculated results faster, or store data that would otherwise be lost such as symbols. The cache is stored in a .ucache file next to the trace file.

Trace Developer Guide

You can develop your own traces in Unreal Insights. Refer to the Trace Developer Guide for more information.