Tommy Lahitte | Debug Vault
QA Workflow

Capture Unreal Insights Traces with the Right Arguments

Unreal Insights trace files give you a frame-by-frame breakdown of CPU, GPU, task graph, rendering commands, and more. The right combination of -trace= channels makes the difference between a useful trace and an overwhelming one.

unreal-insightstraceprofilingperformanceswitchboard

When reproducing a performance regression or investigating a frame hitch, capturing a good Unreal Insights trace is the first step. The -trace= channels you choose determine what data is captured.

Basic Trace Capture

bash
-tracefile="C:\Logs\MySession.utrace" -trace="default,concert,messaging,tasks" -statnamedevents

Extended Trace for Rendering Analysis

bash
-statnamedevents -trace=cpu,gpu,frame,log,task -tracefile=D:\logs\session.utrace

Full Rendering Pipeline Trace

bash
-trace=log,cpu,gpu,frame,bookmark,concert,messaging,task,rendercommands,rhicommands,rdg

Channels Reference

  • cpu — CPU thread activity and named scopes
  • gpu — GPU timing per pass
  • frame — frame boundaries and frame time
  • log — log messages correlated to timeline
  • task — Task Graph worker activity
  • rendercommands — high-level render command queue
  • rhicommands — low-level RHI command timing
  • rdg — Render Dependency Graph pass execution
  • bookmark — named event markers you add in code
  • concert — Multi-User session events (for nDisplay debugging)

Enabling Trace at Runtime

You can also start/stop a trace from the console without a launch argument:

bash
trace.Enable cpu,gpu,frame,log,task    // Start capturing
trace.Disable                           // Stop capturing
The -statnamedevents flag emits named stat scopes as bookmarks, which makes it much easier to correlate code paths with timeline spikes in Unreal Insights.