feat(insights): TraceServices-backed trace analysis, plus fix insights-capture never writing a trace

[Mistweaver]

Summary

insights-analyze only ever called stat() on the .utrace file — the tool's own description said full analysis "requires TraceAnalysis module integration (future enhancement)". TraceAnalysis and TraceServices were already linked by SoftUEBridgeEditor for the Rewind Debugger, so no build-rule change was needed to do it properly.

This also fixes a pre-existing bug that made insights-capture produce no trace at all — see part 2, which is why the feature was untestable end-to-end.

Part 1 — real analysis

The tool now opens the trace with IAnalysisService::Analyze and reads the same providers the Unreal Insights UI does, under FAnalysisSessionReadScope:

analysis_type	provider
basic_info	unchanged — file metadata only, still parses nothing so it stays instant on large captures
frame_stats	IFrameProvider — per frame type, avg/median/p90/p95/p99, FPS, hitch counts
top_functions	ITimingProfilerProvider::CreateAggregation over every CPU thread and GPU queue
call_tree	CreateButterfly → GenerateCalleesTree/GenerateCallersTree, rooted at a named timer
counters	ICounterProvider — min/max/average/last
csv_stats	ICsvProfilerProvider — CSV captures embedded in the trace
threads	IThreadProvider
bottlenecks	composite — frame health, worst frames, heaviest timers by both inclusive and self time

All accept an optional [start_time, end_time] window plus top_n / hitch_threshold_ms, exposed on the CLI as --start-time / --end-time / --top-n / --hitch-threshold-ms, with --timer-name / --direction / --max-depth for call_tree and --column-filter for csv_stats.

Two design points that matter for agent callers:

• Percentiles and self time, not just averages. An average frame time hides exactly the hitches you're hunting, and inclusive time alone cannot distinguish an expensive call tree from an expensive function.
• csv_stats exists because CSV stats are a different instrumentation system. WorldTickMisc and Ticks/* are CSV profiler stats, not CPU timers, so they never appear in top_functions or call_tree — which reads as a tool failure. Worse, WorldTickMisc is declared CSV_SCOPED_TIMING_STAT_EXCLUSIVE (LevelTick.cpp:1481), making it a residual bucket: time in UWorld::Tick no other CSV stat claimed. A large value names an accounting gap, not a slow function. Asking call_tree for it returns that explanation rather than a bare "not found".

Errors are actionable throughout: an unknown timer name returns substring near-misses; a trace with no timing data explains that CPU scopes are compiled out of Shipping entirely (CPUPROFILERTRACE_ENABLED is 0 when UE_BUILD_SHIPPING), so a Shipping capture can never contain them.

ITimingProfilerProvider::ReadTimers was deprecated in 5.8 for GetTimerReader(), which does not exist in 5.7, so timer lookup is version-guarded.

Part 2 — insights-capture silently wrote nothing

It issued Trace.Start "<path>" <channels>. UE splits console command arguments on whitespace without honouring quotes, so any project path containing a space — and Unreal Projects is the UE default — arrives as 3+ args and is rejected:

Cmd: Trace.Start "../../../Users/.../Unreal Projects/.../SmokeTest" cpu,gpu,frame
LogConsoleResponse: Warning: Invalid arguments. Usage: Trace.File [Path] [ChannelSet]

GEngine->Exec still returns true, because the command was handled — so both start and stop reported success while producing no file. It now calls FTraceAuxiliary::Start/Stop directly: the path is a real parameter with no parsing, the return value is a genuine success bool, the reported path is absolute (ProjectSavedDir() is relative to the engine binaries dir), .utrace is appended if missing, and stop reports trace_file_exists.

Verification

Smoke-tested against an 85 MB trace captured from a live VR Preview session, which caught four defects that all compiled cleanly and were only reachable at runtime — each is fixed here and pinned by a regression test:

1. Crash: Trying to read from session outside of a ReadScope. IAnalysisSession::GetName()/GetDurationSeconds() read like plain accessors but are locked session reads; three call sites ran before the scope opened.
2. inf in frame_stats: the last frame is still open when tracing stops, and one infinite duration poisoned total/max/average and drove average_fps to 0. Non-finite durations are now excluded and reported as incomplete_frames_skipped.
3. Misleading timer_count: it came from ITable::GetRowCount(), already capped by TableEntryLimit, so --top-n 12 reported 12 for a trace holding 11,486 timers. Renamed returned_count.
4. top_timers_by_self_time was not ranked by self time. TableEntryLimit is applied after SortBy, so limiting the aggregation by inclusive time reduced the self-time list to a re-sort of the heaviest call trees. At --top-n 8 it bottomed out at 13.6 ms of self time while omitting CharacterMesh at 53,042 ms — second-largest in the trace — plus RHIThreadLock_Wait (35,515 ms), xrWaitFrame (31,664 ms) and two others. It now aggregates unlimited (EntryLimit > 0 gates the cap, so 0 is unlimited) and ranks each metric over the full set, reporting timers_considered.

Builds clean — 0 errors and 0 warnings from these files — on FantasyMakerVREditor (UE 5.7) and StarKnightsEditor (UE 5.8, forced clean rebuild so everything is back in unity blobs). python -m pytest tests/ — 740 passed, 3 skipped.

Sample output from the VR trace, call_tree on Tick_Engine:

Tick_Engine                       incl=68869.6ms  self=453.1ms
  UWorld_Tick                     incl=61796.8ms  self=980.0ms
     OpenXrWaitFrame              incl=31685.1ms  self=2.4ms
        xrWaitFrame               incl=31664.5ms  self=31664.5ms
     TickCompletionEvents         incl=25013.9ms  self=44.9ms
     FActorComponentTickFunction::ExecuteTick   incl=3491.5ms
        Cable                     incl=2146.5ms   self=2146.5ms  x6332

Notes

• csv_stats has been exercised against the empty case (capture_count: 0) but not yet against a trace containing real CSV captures — UE ignored the csv trace channel in my capture, which is consistent with CSV profiling needing to be started separately rather than merely having its channel enabled.
• Independent of fix(plugin): restore UE 5.7 compat for cloth dataflow and unbind APIs #353 and fix(plugin): resolve LoadSkeletalMesh unity-build collision #354; touches no files in common with either.

🤖 Generated with Claude Code