`insights`

Inspect, debug & data Core

Capture and post-process Unreal Insights traces for offline timing analysis.

What it’s for

This namespace drives Unreal Insights trace capture from the editor and then turns the recorded .utrace into flat tables you can analyze offline. You start a session, let the editor or a play session run, stop it, and then export the trace into CSV without ever opening the Insights GUI. It is the workflow you reach for when a frame-time regression needs a real recording and a per-scope timing breakdown, not just a live glance at the numbers.

Capture is the first half: start a trace with a chosen channel set, mutate channels mid-trace, or flush the in-memory ring buffer to a file without stopping the session. Analysis is the second half: post-process a captured trace into timer statistics, per-frame thread timing series, counters, and raw timer/thread dictionaries, so a regression can be diffed in pandas or a spreadsheet.

Use insights when you need a recorded trace and an offline timing breakdown. For live scalability and CVar tuning or one-off stat snapshots that do not need a recording, reach for performance instead.

Examples

Record a trace of a play session

Start a session with the CPU, GPU, and frame channels, then stop it and get the file back.

You: Record an Insights trace with cpu, gpu and frame channels while I fly the drone.

  call("insights.start_session", {channels:"cpu,gpu,frame"})
    → {ok:true, started:true}
  call("insights.stop_session", {})
    → {ok:true, tracePath:"C:/UnrealTrace/Store/001/20260703_hover.utrace"}

Done. Trace recorded to 20260703_hover.utrace.

Turn a trace into per-frame CSV

Export the newest trace into a frame-timing series, restricted to the game and render threads.

You: Export the last trace to a per-frame CSV for GameThread and RenderThread.

  call("insights.export_trace", {kind:["frame_series"],
        threads:["GameThread","RenderThread"]})
    → {ok:true, outDir:".pinwright/insights/hover/01/",
       files:["frame_series.csv"], truncation:[]}

Done. Wrote frame_series.csv with GameThread and RenderThread busy/span columns.

Diff a moving window against an idle window

Aggregate timer stats over two named time ranges so you can compare the same trace in two states.

You: Compare per-timer cost between a moving window and an idle window in physics.utrace.

  call("insights.export_trace", {tracePath:"D:/traces/physics.utrace",
        kind:["timer_stats"], topN:30,
        windows:[{name:"moving", startTime:4.0, endTime:9.0},
                 {name:"idle", startTime:12.0, endTime:17.0}]})
    → {ok:true, files:["timer_stats__moving.csv","timer_stats__idle.csv"],
       truncation:[]}

Done. Two window tables written; diff them on timer name by exclusive ms-per-frame.

← Back to all namespaces