Unreal Insights Trace Quick Start Guide

Setting Up Unreal Insights

When building Unreal Insights you will have multiple options available.

Option 1: Launch Unreal Insights from the Explorer

Check if you already have a prebuilt copy of Unreal Insights with your engine by navigating to Engine\Binaries\Win64\UnrealInsights.exe

Option 2: Build from Visual Studio

You can build Unreal Insights from your Program's directory in your Solution Explorer.

Option 3: From the Command Prompt

Navigate to Start > Command Prompt, then build Unreal Insights from your command directory.

		cd C:\MyEngineInstallLocation\

		Engine\Build\BatchFiles\RunUBT.bat UnrealInsights Win64 Development

Copy full snippet

Option 4: From the Editor

Start Unreal Insights from the Unreal Editor by navigating to Tools > Unreal Insights > Run Unreal Insights. Insights will attempt to compile automatically.

When running a Trace to profile your project data, you have multiple workflow options available depending on your Unreal Engine build and operating system.

Default Tracing Workflow (Win64, Binary Launcher)

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 the Lyra Game Sample.

	cd C:\MyEngineInstallLocation\

	Samples\Games\Lyra\Binaries\Win64\LyraGame.exe

Copy full snippet

4. Live Insights Session Browser:

Navigate back to the Unreal Insights Session Browser and observe that a new session has appeared with the "LIVE" status, indicating it is currently recording.

5. Check Your Trace Status:

In Lyra, press the tilde (`) twice to open the console, then type in the command:

	Trace.Status
Copy full snippet

The channels Gpu, Bookmark, Frame, Cpu, and Log are enabled by default.

6. Open Your Trace Session:

Navigate back to the Unreal Insights Session Browser, then double-click your .utrace file to open it for analysis in a new Unreal Timing Insights window.

Opening a trace launches a new instance of Unreal Insights. Timing Insights is the default component opened and provides you the capability to interact with a trace session to see how much time your project spends on various tasks.

Refer to the Timing Insights documentation for more information on how to view your data for analysis.

Advanced Controls of Tracing

Unreal Insights provides several Trace commands for you to control how your data is profiled.

• Trace.SnapshotFile <filename>: This writes a snapshot of the current in-memory trace buffer to a file. If you are already tracing actively, it does not interrupt the active trace, but instead records a second trace file in parallel just for this snapshot.

• Trace.Bookmark <name>: This emits a Bookmark event with the given string name. Bookmarks appear in Timing Insights as a vertical line at the time the Bookmark was recorded. Previously this was available through the API only as TRACE_BOOKMARK().

• Trace.Screenshot <Name> <bIncludeUI>: As mentioned above, you can run this console command to generate a vertical line and optionally include the UI by specifying true or false for a screenshot in Timing Insights.

You may want to have visibility on specific trace channels like CPU or GPU profiling data, or to disable tracing a channel. Refer to the Trace and Reference documentation for additional information on Trace commands.

Late Connect

There may be instances where you forget to run the UnrealInsights.exe before launching your project, or perhaps you have discovered a situation you want to record without initially tracing from the beginning. You can Late Connect to Unreal Insights by following the steps below.

	Trace.Stop
Copy full snippet

1. Build, Cook, or Run your project as you normally would.

2. Open Unreal Insights.

3. Click Connection to open the Connection tab. Confirm your desired connection settings, then click Connect.

After a successful connection, click the Trace Store tab. A new LIVE session will appear in the Session list.