How to Enable Trace Capture in ADT Hub (Unreal Engine)

Last updated on August 18, 2026

Goal​

Enable Unreal Insights trace capture for a build channel or track in ADT Hub so that .utrace files are automatically collected and uploaded when testers run sessions.

Prerequisites​

  • You have Studio Administrator access in ADT Hub.
  • Your Unreal Engine project builds are compiled with the UE_TRACE_ENABLED flag. Builds without this flag will not produce a .utrace file regardless of how trace capture is configured in ADT. If you are unsure, confirm with your build engineer before enabling trace capture.
  • You are running Unreal Engine 5.3 or later. Earlier engine versions are not supported.

Steps​

Step 1: Open Channel Settings​

In ADT Hub, go to Distribution and open the channel you want to configure.

Click the gear icon in the top-right corner of the channel page. The Channel Settings modal opens.

Select the Settings tab.

Step 2: Enable Trace Capture for the Channel​

In the Settings tab, locate the Trace Capture section below "Disable auto-delete."

Toggle Trace Capture ON.

When the toggle is ON, ADT will automatically inject trace launch arguments for all sessions launched from tracks in this channel. If a track already has manual -trace= flags set under Set Launch Arguments, ADT's injected arguments are additive — both apply.

Step 3: Configure Recording Channels​

The Recording channels field is pre-populated with the default light profile:

cpu gpu frame bookmark

This profile covers CPU activity, GPU activity, frame timing, and bookmark annotations. For most performance investigations, this is the right starting point.

To add heavier channels, click + Add and enter the channel name. Supported additions include:

Channel nameWhat it records
memoryMemory allocations and heap usage
loadtimeAsset and level load timing
rhicommandsGraphics command list detail
objectUObject creation, destruction, and reference tracking

Channel names must be valid Unreal Engine trace channel identifiers — the same names accepted by the -trace= launch argument and the Trace.Start console command. Invalid names are highlighted in red when the field loses focus, and the Save button remains disabled until all invalid entries are removed.

To remove a channel from the default set, click the × on its tag.

Step 4: Set File Retention​

Under File retention, choose how long trace files are kept before they are automatically purged. The available range is 1 to 7 days. The default is 3 days.

Trace file retention is independent of session and build retention. A trace can expire before its parent session and build records do. Once a trace expires, the entry remains visible on the session detail page with an "Expired" label, but the file can no longer be downloaded.

Choose a retention window that gives your developers enough time to investigate performance issues after a session ends.

Step 5: Save Channel Settings​

Click Save. Trace capture is now enabled for all tracks in this channel that do not have a per-track override.

The new configuration takes effect on the next session launch. Sessions already in progress are not affected.

Optional: Override Trace Capture for a Specific Track​

If you need different trace settings for a specific track — for example, a heavier channel set for a dedicated performance testing track, or trace capture disabled on a track used for quick smoke tests — you can override the channel-level settings per track.

Step A: Open the Track's Trace Capture Panel​

On the channel page, locate the track card. Click the "..." menu on the track card, then select Track > Trace Capture.

The Trace Capture panel opens for that track.

Step B: Switch to Per-Track Override​

By default, the track shows Follow channel settings as ON. This means it inherits the channel-level configuration.

Toggle Override for this track to ON. The Status, Recording channels, and File retention fields become active and editable.

Step C: Configure the Override​

Set the Status (Enabled or Disabled for this track), configure Recording channels, and set File retention as needed. The same validation rules apply as in the channel-level settings.

Step D: Save the Override​

Click Save. The per-track configuration applies to sessions launched from this track only. Other tracks in the channel continue to use the channel-level settings.

Validation​

To confirm trace capture is configured correctly:

  1. Launch a session from a track with trace capture enabled.
  2. After the session ends, go to ADT Web > Versions > [your version] > [your build] > Sessions > [session ID] > Traces tab.
  3. You should see a trace entry with status "Uploading..." that updates to show file details once the upload is complete.

If the Traces tab shows "No trace captured for this session," see Troubleshooting below.

Troubleshooting​

The Traces tab shows "No trace captured for this session." The build was most likely not compiled with UE_TRACE_ENABLED. Trace capture requires this compile flag to be present. Confirm with your build engineer and rebuild.

Trace capture is enabled but no entries appear after sessions run. Verify that the channel or track configuration was saved after enabling the toggle. Also confirm the build is UE 5.3 or later and was compiled with UE_TRACE_ENABLED. Check that the session was launched from ADT Hub and not started independently outside of ADT.

The Save button is disabled after editing Recording channels. One or more channel names in the field are invalid. Invalid tags are highlighted with a red background. Remove or correct the invalid entries before saving.

Trace files are expiring before developers can download them. Increase the File retention window in the channel or track settings. The maximum is 7 days. Note that changes to retention apply to new traces only — files already uploaded follow the retention window that was active when they were uploaded.

A track is not following the channel-level settings. That track likely has a per-track override enabled. Open the track's Trace Capture panel (track card > "..." > Track > Trace Capture) and confirm whether "Override for this track" is ON. If you want the track to inherit channel settings, switch it back to "Follow channel settings."

Next Steps​

Last updated on
On this page