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 compatible between Engine versions. 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.
Currently, we only support one user per machine that is running a Unreal Trace Server. If multiple users are logged in simultaneously, then traces will be stored in the first user's trace directory, therefore leaving them inaccessible for other users.
Tracing Runtime
1. Run Unreal Insights:
Navigate to your Engine\Binaries\Win64 folder and double-click UnrealInsights.exe.
2. Insights Session Browser:
When you launch the Unreal Insights Session Browser, you will notice that there are currently no live sessions available.
3. Run Your Game Project:
Launch the Command Prompt from your operating system and run Your Project.
cd C:\MyEngineInstallLocation\
Samples\Games\Binaries\Win64\YourProject.exe
You may need to change the file directory path to match your local installation path.
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:
`-tracetailmb=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 its 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.