How to Capture and Download a Trace (Unreal Engine, Windows)
Goal
Run a game session with trace capture active, optionally trigger a targeted mid-session snapshot, and download the resulting .utrace file from ADT Web to open in Unreal Insights.
Prerequisites
- Trace capture is enabled for the channel or track you are launching from. If it is not, complete How to Enable Trace Capture in ADT Hub first.
- The build you are launching was compiled with the
UE_TRACE_ENABLEDflag. Builds without this flag will not produce a.utracefile regardless of session or configuration settings. - You are running Unreal Engine 5.3 or later.
- You have Unreal Insights installed on your machine for the final analysis step.
Steps
Step 1: Launch the Session from ADT Hub
In ADT Hub, navigate to Distribution > [channel name] > [track name] and launch the game as you normally would.
When you launch through ADT with trace capture enabled, ADT injects the trace launch arguments automatically. You do not need to add -trace= flags manually. The game starts recording as soon as the engine initializes.
There is no visible in-game indicator that auto-capture is running. This is expected.
Step 2: Play Through the Session
Run the session normally. The auto-capture trace records continuously until the session ends.
If you observe a specific performance issue — a frame rate drop, a hitch, a spike — and want to capture a focused trace around that moment, see the next step. Otherwise, skip to Step 4.
Step 3: (Optional) Capture a Mid-Session Snapshot or Recording
Choose the appropriate method based on whether auto-capture is currently running.
If auto-capture is ON (the default when trace capture is enabled in the channel or track settings):
Use Trace.SnapshotFile to capture the current in-memory trace buffer as a separate file without stopping auto-capture.
- Open the Unreal Engine in-game console by pressing the
~key. - Run the following command, using a file path within
Saved/Profiling/:
Trace.SnapshotFile Saved/Profiling/snapshot.utrace
The snapshot captures what is currently in the trace buffer at that moment and writes it to a separate .utrace file. The auto-capture trace continues running and is not interrupted.
ADT picks up the snapshot file automatically and uploads it as a separate entry on the session detail page.
Do not use Trace.Start while auto-capture is already running. Trace.Stop is a global command — it halts ALL active trace channels, including the auto-capture trace. If you run Trace.Start and then Trace.Stop during an auto-capture session, the full auto-capture trace stops at that point and the remainder of the session is not recorded.
Use Trace.SnapshotFile for mid-session captures when auto-capture is active.
If auto-capture is OFF:
Use Trace.Start and Trace.Stop to record a focused window.
Trace.Start run from the in-game console without explicit channel arguments uses whatever channels are currently active in the Unreal Engine trace system — this may not match the channel set configured in ADT Hub. To match the ADT-configured channels, pass them explicitly:
Trace.Start cpu gpu frame bookmark
- Open the Unreal Engine in-game console by pressing the
~key. - Run:
Trace.Start
- Play through the moment you want to capture.
- When you are done, run:
Trace.Stop
ADT picks up the resulting .utrace file automatically and uploads it as a mid-session entry.
Step 4: End the Session
Exit the game normally. ADT Hub detects the .utrace file in Saved/Profiling/ and begins uploading it in the background.
If your connection is slow, the upload continues after the game closes. You do not need to keep ADT Hub open.
Step 5: Find the Trace in ADT Web
- In ADT Web, go to Versions > [your version] > [your build].
- Open Sessions and click the session ID for the session you just ran.
- Select the Traces tab.
The Traces tab lists all trace entries for this session. Each entry shows:
| Column | What it tells you |
|---|---|
| Type | Auto or Mid-session |
| Time | Capture timestamp |
| Duration | Length of the recorded window |
| Channels | Recording channels active during capture |
| Platform | Platform the trace was captured on |
| Size | File size |
The expiry date and remaining days are shown below each entry. Download the trace before it expires — the default retention is 3 days from capture.
If the entry shows "Uploading...", the file is still being transferred. Refresh the page after a few minutes.
If the Traces tab shows "No trace captured for this session," see the Troubleshooting section below.
Step 6: Download the Trace
Click the Download button next to the trace entry you want to analyze.
The .utrace file downloads to your machine.
Step 7: Open in Unreal Insights
Open the downloaded .utrace file in Unreal Insights on your machine.
If Unreal Insights is not already open, double-clicking the file in Windows Explorer opens it directly if Unreal Insights is registered as the default handler. Alternatively, open Unreal Insights and use File > Open Trace File to locate the downloaded file.
Validation
A successfully completed workflow looks like this:
- The session detail page in ADT Web shows at least one entry in the Traces tab with status Available (not Uploading, not Failed).
- The entry shows the correct capture timestamp, duration, and channels for your session.
- The downloaded file opens in Unreal Insights without errors.
Troubleshooting
The Traces tab shows "No trace captured for this session." See No trace captured for this session in the setup guide for causes and fixes.
The trace entry shows "Uploading..." and does not update. The upload is still in progress or encountered a slow connection. Wait a few minutes and refresh. If the status does not change after 15 minutes, check the tester's network connection. If the upload fails permanently, the entry shows "Upload failed" with instructions to retrieve the file from the tester's machine manually.
The trace entry has a warning badge (⚠).
This trace was captured mid-session using Trace.Start. Some event labels may appear as "unknown" in Unreal Insights because CPU scope names and thread names are emitted only once at engine init. The trace is still usable — events are recorded, but some labels may be missing. This is expected behavior for mid-session captures.
Trace.SnapshotFile does not produce a file.
The build must be compiled with UE_TRACE_ENABLED for the snapshot command to have any effect. If the build was compiled correctly but no file appears, verify that the path you specified is within Saved/Profiling/ — ADT only monitors that directory.
The trace entry shows "Trace expired" and there is no Download button. The file was purged when its retention window expired. The default retention is 3 days. The entry remains visible on the session detail page, but the file cannot be recovered from ADT. If your team routinely needs more time, ask your Studio Administrator to increase the File retention setting in Channel Settings or Track Settings.
A custom -tracefile= path is not producing a trace entry in ADT.
ADT Hub only monitors Saved/Profiling/. Trace files written to any other directory via -tracefile=<custom_path> are not detected or uploaded. Remove the custom -tracefile= argument or change it to point to Saved/Profiling/.
The file opens in Unreal Insights but many events show "unknown" labels.
This is the expected behavior for mid-session traces captured with Trace.Start. The auto-capture trace (captured from session launch) will have full labels. If you need complete metadata, use the auto-capture trace or use Trace.SnapshotFile instead of Trace.Start/Trace.Stop.
Next Steps
- How to Enable Trace Capture in ADT Hub (Unreal Engine) — configure trace capture settings for your channel and tracks
- Unreal Insights Trace Capture — understand capture methods, retention, and limitations