performance_analyze_insight
Query loaded .utrace profiling data to diagnose performance problems: find bottlenecks, spikes, hot paths, and compare frame times.
Instructions
Query profiling data from a loaded .utrace trace.
RECOMMENDED WORKFLOW (compact output, saves context):
"diagnose" — ONE CALL full report: verdict, findings, categories, top timers
"spikes" — Auto worst frames + category breakdown
"flame" — Top timers by exclusive (self) time — actual bottleneck code
"hotpath" — Drill into a category or event's children
"search" — Find a timer across all frames (stats + worst frames)
"histogram" — Frame time distribution (periodic hitches vs sustained?)
"compare" — Compare frame vs trace median, show outlier events
Use performance_start_trace/stop_trace to record and auto-load a trace, or use query="load" to load an existing .utrace file.
Args: query: Type of analysis. One of:
SMART QUERIES (compact output, do analysis in C++):
- "diagnose" — ONE CALL full performance report. Returns: verdict string,
severity-rated findings with recommendations, category
breakdown (avg per-frame exclusive ms), top 10 exclusive
timers, GPU-bound detection. Start here.
- "bottlenecks" — Auto-categorize frame into Animation/Slate/Network/etc
with total time per category and top event. VERY compact.
- "hotpath" — Drill into a category or event's children, sorted by time
- "compare" — Compare frame vs trace median, show outlier events only
- "spikes" — Auto worst frames + category breakdown (combines worst_frames
+ bottlenecks). Shows top 3 categories per spike frame.
- "search" — Find a timer across ALL frames. Returns min/avg/max/p95/p99
stats + worst frames list. Use filter= for timer name.
- "histogram" — Frame time distribution. Shows bucket counts + budget
summary (on-budget / slightly over / 2x / 4x over).
- "flame" — Top timers by EXCLUSIVE (self) time. Shows per-frame avg
exclusive ms, self_pct (excl/incl ratio), category label.
Answers "what code actually consumes the most CPU?"
STANDARD QUERIES:
- "load" — Load an existing .utrace file (requires trace_path)
- "summary" — Overview: duration, frame count, avg/min/max/p95 frame time
- "worst_frames" — Find the slowest frames with top events
- "frame_details" — Per-thread timing breakdown for one frame (use bottlenecks first!)
- "timer_stats" — Aggregated stats for timers (top N by inclusive time)
- "butterfly" — Callers/callees for a specific timer (requires timer_name)
- "threads" — List all threads in the trace
- "counters" — List counters (GPU memory, draw calls, etc.)
PROVIDER QUERIES:
- "net_stats" — Network profiling (needs 'net' channel)
- "loading" — Asset loading analysis (needs 'loadtime' channel)
- "logs" — Log messages (needs 'log' channel)
- "memory" — LLM memory tags (needs 'memtag' channel)
- "regions" — Timing regions (needs 'region' channel)
- "bookmarks" — Bookmark events (needs 'bookmark' channel)
EXTENDED PROVIDER QUERIES:
- "session" — Session metadata: platform, app, project, build version,
branch, changelist, config, target type. Essential context.
- "modules" — Loaded modules/DLLs with symbol resolution stats.
Shows resolved/failed/pending counts per module.
- "file_io" — File I/O activity: per-file read/write counts, bytes,
duration. Sorted by impact. Needs 'loadtime' channel.
- "tasks" — Task graph: task lifecycle (created→finished), duration,
wait time, prerequisites, nested tasks. Sorted by duration.
- "context_switches" — CPU core scheduling: core count, per-thread context
switch frequency. Needs elevated/admin trace.
- "allocations" — Memory allocation timeline: peak/min memory, live alloc
count, alloc/free events, heaps, swap. Needs 'memalloc'.
- "stack_samples" — CPU sampling profiler: flat profile of hotspot functions
by sample count with percentage. Needs sampling enabled.
- "screenshots" — Screenshot metadata captured during trace recording.
Needs 'screenshot' channel.
trace_path: (load) Absolute path to a .utrace file
frame_index: (bottlenecks, hotpath, compare, frame_details) Which frame (0-based)
target_fps: (bottlenecks, spikes, histogram) Target FPS for budget (default: 60)
category: (hotpath) Category to drill into: Animation, Slate, Network, Physics,
Rendering, Gameplay, Audio, Loading, GarbageCollection, Other
event_name: (hotpath) Specific event name to show children of
min_deviation_pct: (compare) Min deviation % to report (default: 50)
thread: (bottlenecks, hotpath, compare, spikes, search) Thread (default: GameThread)
count: (worst_frames, spikes, search, timer_stats, hotpath, file_io, tasks,
modules, stack_samples) Max results
threshold_ms: (worst_frames, spikes) Only show frames slower than this
max_depth: (frame_details, butterfly, hotpath) Max call stack depth
min_duration_ms: (frame_details) Hide events shorter than this
thread_name: (frame_details) Filter to threads containing this string
filter: (search, timer_stats, counters, logs, memory, regions, bookmarks,
modules, file_io, tasks, stack_samples) Name/path filter
start_time: Start of time range in seconds (-1 = trace start)
end_time: End of time range in seconds (-1 = trace end)
include_values: (counters) Include sampled values
max_samples: (counters) Max value samples per counter
timer_name: (butterfly) Function/scope name to analyze
mode: (butterfly) "callers", "callees", or "both"
connection_index: (net_stats) Connection index for packet details
verbosity: (logs) Filter: Fatal, Error, Warning, Display, Log, Verbose
tracker: (memory) Memory tracker ID
bucket_size_ms: (histogram) Custom bucket width in ms (0 = auto based on target_fps)Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | both | |
| count | No | ||
| query | Yes | ||
| filter | No | ||
| thread | No | ||
| tracker | No | ||
| category | No | ||
| end_time | No | ||
| max_depth | No | ||
| verbosity | No | ||
| event_name | No | ||
| start_time | No | ||
| target_fps | No | ||
| timer_name | No | ||
| trace_path | No | ||
| frame_index | No | ||
| max_samples | No | ||
| thread_name | No | ||
| threshold_ms | No | ||
| bucket_size_ms | No | ||
| include_values | No | ||
| min_duration_ms | No | ||
| connection_index | No | ||
| min_deviation_pct | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |