Unreal Insights Trace Capture

Last updated on August 18, 2026

Overview

Unreal Insights Trace Capture lets Unreal Engine studios automatically collect .utrace performance recordings during game sessions managed through ADT and store those files centrally alongside all other session data. Because ADT already tracks each session's build version, platform, device, and player identity, every trace arrives pre-enriched — developers open a file already tied to a specific build, tester, and device without any manual correlation work.

The feature is opt-in, configured at the channel or track level. Trace analysis still happens in Unreal Insights; ADT handles storage, context, and access. ADT does not replace Unreal Insights.

Why Trace Capture Exists

When a performance issue is reported from a game session, developers typically need a .utrace file to investigate it. Under a manual workflow, that file is stored locally on the tester's machine — not in a shared location — and has no record of which build it came from, which session produced it, or who ran it.

The result is that developers either skip deep diagnosis entirely, because finding and contextualizing the trace takes longer than the investigation justifies, or they ask testers to reproduce the session specifically to capture a trace — which testers find disruptive and which does not reproduce the original conditions.

ADT already holds the session context. The gap is that .utrace files are not captured and attached to it. This feature closes that gap.

How Trace Capture Works

When trace capture is enabled for a channel or track in ADT Hub, the following happens for each session launched from that configuration:

1. At launch, ADT injects the appropriate trace launch arguments so the game starts recording immediately. No action is required from the tester.
2. During the session, the trace is recorded to the default Unreal Engine output directory (Saved/Profiling/). QA can also trigger a targeted snapshot mid-session using built-in Unreal Engine console commands without interrupting the running auto-capture trace.
3. At session end, ADT Hub detects the .utrace file in Saved/Profiling/ and uploads it to ADT in the background. If the connection is slow, the upload continues after the game closes.
4. On the session detail page, the trace appears in a Traces tab alongside crashes, bug reports, and other session artifacts. Each entry shows capture type, timestamp, duration, recording channels, platform, and file size.
5. To investigate, the developer downloads the trace from ADT and opens it in Unreal Insights. ADT does not provide an in-browser trace viewer.

Enable trace capture in ADT Hub (Channel or Track settings)
        ↓
Tester launches game → trace records automatically
        ↓
Session ends → ADT Hub detects and uploads trace file
        ↓
Trace appears on Session detail page in ADT Web
        ↓
Developer downloads trace and opens in Unreal Insights

Capture Methods

There are three ways a trace can be produced within this feature:

Method	Who triggers it	When to use
Automatic at launch	ADT (no tester action)	Default path — captures the full session
Mid-session snapshot	QA via UE in-game console (Trace.SnapshotFile)	Targeted capture at a specific moment without stopping auto-capture
Mid-session start/stop	QA via UE in-game console (Trace.Start / Trace.Stop)	Focused capture when auto-capture is not running

For mid-session captures, ADT picks up and uploads the file automatically when it appears in Saved/Profiling/. No additional action is required from QA.

Key Benefits

• Context is already assembled. Every trace is linked to a specific build version, session, platform, and tester. Developers arrive with full diagnostic context rather than reconstructing it manually.
• No tester action required. Automatic capture at launch means traces are collected for every session without requiring testers to configure or trigger anything.
• Centralized access. Traces are available in ADT Web for any developer with session access — not locked on a tester's local machine.
• Works with your existing workflow. ADT does not replace Unreal Insights. It stores and surfaces the trace so developers can open it in their existing tool immediately.
• Configurable by channel and track. Studios can enable trace capture for specific channels or individual tracks, and can configure recording channels and retention separately per configuration. This lets studios balance trace detail against file size and storage cost.

Limitations and Considerations

Build requirement. Trace capture requires the game to be compiled with the UE_TRACE_ENABLED flag. Builds without this flag will not produce a .utrace file. If a session runs with trace capture enabled but no trace appears, the most likely cause is that the build was not compiled with this flag.

Default recording profile is lightweight. The default channel set — CPU, GPU, Frame, and Bookmark — produces trace files in the low tens of megabytes per minute. Heavier channels (Memory, Load time, RHI commands, Object tracking) are available as opt-in additions but can push trace sizes past 100 MB per minute on longer sessions.

Short retention window. Trace files have a separate retention policy from sessions and builds, configurable between 1 and 7 days per studio. A trace file can expire before its parent session and build records do. Expired traces remain visible in the session detail page with an "Expired" label, but the file can no longer be downloaded.

Mid-session warning. Traces captured mid-session using Trace.Start (not Trace.SnapshotFile) may display "unknown" labels for some events in Unreal Insights. This occurs because some metadata — CPU scope names, thread names — is emitted only once at engine init and may be missing from traces that started after launch. ADT marks these entries with a warning.

Trace.Stop halts all channels globally. This is native Unreal Engine behavior. If auto-capture is running and a QA tester runs Trace.Stop to end a manual mid-session capture, both traces stop simultaneously. Use Trace.SnapshotFile instead of Trace.Start/Trace.Stop when auto-capture is active.

Hitch-triggered capture is not in v1.x. Automatic capture triggered by a detected FPS drop is planned for a future phase. In v1.x, capture is either automatic at session launch or manually triggered via UE console commands — a session's Traces tab will only ever show Auto or Mid-session entries.

Supported Platforms

Engine	Platform	Status
Unreal Engine 5.3+	Windows, macOS, Linux	Supported
Unreal Engine 5.3+	Consoles, mobile	Not yet supported
Unity	All	Not supported

Console and mobile support is deferred to a future version; the ADT SDK's file-system monitoring is validated for desktop builds (Windows, macOS, Linux) only in v1.x.

Next Steps

• How to Enable Trace Capture in ADT Hub (Unreal Engine) — configure trace capture for a channel or track
• How to Capture and Download a Trace (Unreal Engine, Windows) — run a session and retrieve a trace file