Profiling
Every Profiling command in CodeFizz Editor Agent, with parameters and examples.
Loading…
Every Profiling command in CodeFizz Editor Agent, with parameters and examples.
11 commands. Each shows its parameters and an example, and has a copyable deep link, so you (or an AI agent) can jump straight to one.
performance_start_traceStart recording a live.utrace from the running editor
Requires UE 5.7+ (all profiling commands do, on a 5.6 editor they return an explanatory error). Begins recording a Unreal Insights.utrace from the running editor. Pick what to capture with `preset` (a goal-oriented channel group) and/or `channels` (comma-separated channel names or preset names, combined and de-duped). Run performance_list_channels first to discover every channel the running engine has (engine + custom) and the available presets. Unknown channel names are reported back in `ignored_unknown_channels`. Presets: default, cpu, gpu, render, memory, loading, network, tasks, sampling, animation, jiggi. Set connection=network to stream live to Unreal Insights instead of a file. Stop with performance_stop_trace.
| Parameter | Type | Required | Description |
|---|---|---|---|
| file_path | string | No | Output file path for connection=file (empty = auto) |
| preset | string | No | Investigation preset: default,cpu,gpu,render,memory,loading,network,tasks,sampling,animation,jiggi |
| channels | string | No | Channel names and/or preset names, comma-separated (combined with preset). Empty + no preset = engine 'default' |
| connection | string | No | file (write.utrace) or network (live stream to Unreal Insights) |
| target | string | No | Host for connection=network (default 127.0.0.1) |
| exclude_tail | bool | No | Exclude the in-memory tail of important events (smaller trace) |
| stat_named_events | bool | No | Enable named events (stats.NamedEvents on) so CPU scopes capture stat names |
cfa performance_start_trace --preset jiggi
cfa performance_start_trace --preset memory --exclude-tail
cfa performance_start_trace --channels "cpu,gpu,frame,mass,niagara"
cfa performance_start_trace --connection network --target 127.0.0.1 --preset cpu
cfa performance_start_trace --file-path "C:/Traces/my.utrace" --channels "loading,counters"performance_stop_traceStop recording and optionally auto-load for analysis
Stops the active trace recording. When auto_load is true (default), the trace is immediately loaded for analysis so you can run performance_analyze_insight queries against it without a separate load step.
| Parameter | Type | Required | Description |
|---|---|---|---|
| auto_load | bool | No | Auto-load trace for analysis |
cfa performance_stop_trace
cfa performance_stop_trace --auto-load=falseperformance_analyze_insightAnalyze a performance trace (diagnose, spikes, flame, hotpath, etc.)
Requires UE 5.7+ ('objects' query needs 5.8). Runs analysis queries against a loaded.utrace file. The recommended workflow is: (1) performance_start_trace to record, (2) performance_stop_trace to stop and auto-load, (3) performance_analyze_insight with query="diagnose" for a full automatic report, then drill down with "spikes", "flame", "hotpath", or "search" as needed. Use query="load" with trace_path to analyze a previously saved trace. The "diagnose" query returns a one-call verdict with severity findings, category breakdown, and top bottlenecks. The "flame" query shows timers by exclusive (self) time to find actual CPU-consuming code. The "search" query finds a specific timer across all frames with min/avg/max/p95/p99 stats.
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Query type: diagnose, bound, breakdown, calltree, gpu_sync, gpu_passes, inspect_frame, gc, hitch_cause, memory_growth, critical_path, objectproperties, spikes, flame, bottlenecks, hotpath, compare, compare_traces, search, histogram, load, summary, worst_frames, frame_details, timer_stats, butterfly, threads, counters, counter_series, csv, between, net_stats, net_packets, net_objects, loading, logs, memory, memory_series, alloc_query, stack_tree, cook, trace_channels, animation, mass, iostore, chaos_locks, render_trace (5.8+), world_streaming (5.8+), regions, bookmarks, session, modules, file_io, tasks, context_switches, allocations, stack_samples, screenshots, objects (5.8+) |
| trace_path | string | No | Path to.utrace file (for 'load' query) |
| frame_index | int | No | Frame index |
| count | int | No | Result count |
| threshold_ms | float | No | Time threshold in ms |
| max_depth | int | No | Max depth |
| min_duration_ms | float | No | Min duration filter |
| thread_name | string | No | Thread name filter |
| thread | string | No | Thread filter (alias) |
| filter | string | No | Name filter |
| start_time | float | No | Start time in seconds |
| end_time | float | No | End time in seconds |
| include_values | bool | No | Include counter values |
| max_samples | int | No | Max samples |
| timer_name | string | No | Timer name (for butterfly query) |
| mode | string | No | Mode (callers/callees/both) |
| connection_index | int | No | Network connection index |
| verbosity | string | No | Log verbosity filter |
| tracker | int | No | Memory tracker index |
| target_fps | float | No | Target FPS for analysis (diagnose/bound) |
| category | string | No | Category filter |
| event_name | string | No | Event name filter |
| min_deviation_pct | float | No | Min deviation percentage |
| bucket_size_ms | float | No | Histogram bucket size |
| snapshot_index | int | No | Snapshot index for the 'objects' query (-1 = latest) |
| skip_frames | int | No | Warmup frames to skip for 'bound' (-1 = auto-detect startup spikes) |
| warmup_seconds | float | No | Skip frames in the first N seconds for 'bound' (warmup window) |
| skip_waits | bool | No | For 'calltree': skip Wait/Idle children in the hot path to land on the real work leaf |
| object | string | No | For 'objectproperties': traced object name (substring). Omit to list traced objects |
| object_id | string | No | For 'objectproperties': trace object id (the trace_object_id string from performance_trace_object, or from traced_objects). Direct-reads the property timeline by id. |
| property | string | No | For 'objectproperties': a property name (substring) → returns its value time series |
| name | string | No | For 'counter_series': counter name (substring, case-insensitive). Omit to list all counters |
| from | string | No | For 'between': start anchor, a bookmark name (substring) or a seconds value |
| to | string | No | For 'between': end anchor, a bookmark name (substring) or a seconds value |
| capture_id | int | No | For 'csv': capture id to read (-1 = first capture) |
| queue | string | No | For 'gpu_passes': GPU queue filter (e.g. Graphics, Compute) |
| wait_seconds | float | No | For 'compare_traces'/'alloc_query': max seconds to wait for results (blocks the editor; max 60) |
| rule | string | No | For 'alloc_query': allocation rule, aAf (live at A), AaBf (growth A..B), AaBCf (leaks), AafB (short-living), aABf (long-living)... |
| time_a | float | No | For 'alloc_query': time marker A in seconds (default: trace end) |
| time_b | float | No | For 'alloc_query': time marker B in seconds |
| time_c | float | No | For 'alloc_query': time marker C in seconds |
| time_d | float | No | For 'alloc_query': time marker D in seconds |
| direction | string | No | For 'net_packets'/'net_objects': out or in |
| packet_start | int | No | For 'net_objects': first packet index of the analysis window |
| packet_count | int | No | For 'net_objects': packets to analyze from packet_start |
| view | string | No | For 'animation': overview, tickrecords, graph, notifies, montages (with --object; omit --object to list animated objects) |
| enable_analyzer | bool | No | For 'render_trace': opt in to the RenderTrace analyzer (disabled by default, a UE 5.8 engine bug can crash the editor on mid-session traces) |
cfa performance_analyze_insight --query diagnose
cfa performance_analyze_insight --query bound --target-fps 60
cfa performance_analyze_insight --query bound --skip-frames 30
cfa performance_analyze_insight --query breakdown --thread GPU --count 15
cfa performance_analyze_insight --query breakdown --thread GameThread
cfa performance_analyze_insight --query calltree --timer-name "FTickFunctionTask" --max-depth 8
cfa performance_analyze_insight --query calltree --timer-name "FEngineLoop::Tick" --thread GameThread --skip-waits
cfa performance_analyze_insight --query gpu_sync
cfa performance_analyze_insight --query gpu_passes --count 20
cfa performance_analyze_insight --query gpu_passes --filter Shadow
cfa performance_analyze_insight --query inspect_frame --frame-index 137
cfa performance_analyze_insight --query objectproperties
cfa performance_analyze_insight --query objectproperties --object BP_Miner --property StoredAmount
cfa performance_analyze_insight --query counter_series
cfa performance_analyze_insight --query counter_series --name "DrawCall" --count 200
cfa performance_analyze_insight --query between --from MARK_A --to MARK_B
cfa performance_analyze_insight --query between --from 5 --to 10 --count 15
cfa performance_analyze_insight --query gc
cfa performance_analyze_insight --query hitch_cause
cfa performance_analyze_insight --query hitch_cause --frame-index 137
cfa performance_analyze_insight --query csv
cfa performance_analyze_insight --query csv --filter DrawCalls --count 200
cfa performance_analyze_insight --query compare_traces --trace-path "C:/Traces/after.utrace"
cfa performance_analyze_insight --query memory_growth --count 15
cfa performance_analyze_insight --query critical_path
cfa performance_analyze_insight --query critical_path --frame-index 137
cfa performance_analyze_insight --query load --trace-path "C:/Traces/my_trace.utrace"
cfa performance_analyze_insight --query spikes --count 5 --target-fps 60
cfa performance_analyze_insight --query flame --count 10 --thread GameThread
cfa performance_analyze_insight --query hotpath --frame-index 42 --category Animation
cfa performance_analyze_insight --query search --filter "ConveyorProcessor" --count 10
cfa performance_analyze_insight --query butterfly --timer-name "MassProcessor" --mode both
cfa performance_analyze_insight --query frame_details --frame-index 100 --max-depth 5 --min-duration-ms 0.5performance_list_channelsList every trace channel the running engine has (engine + custom) plus presets
Enumerates all trace channels registered in the running editor, engine channels AND any custom channels defined by plugins, each with its enabled state, category, cost, a one-line summary, and when to use it. Also returns the named investigation presets. Run this BEFORE performance_start_trace to decide exactly what to capture for a target. Filter by name/desc substring, by category (CPU, GPU, Memory, Loading, Network, Gameplay...), or show only currently-enabled channels.
| Parameter | Type | Required | Description |
|---|---|---|---|
| filter | string | No | Substring match on channel name or description |
| category | string | No | Filter by category (CPU, GPU, Memory, Loading, Network, Gameplay, UI, Physics, Core...) |
| enabled_only | bool | No | Only channels currently enabled |
| include_presets | bool | No | Include the investigation presets in the output |
cfa performance_list_channels
cfa performance_list_channels --category Memory
cfa performance_list_channels --filter mass
cfa performance_list_channels --enabled-onlyperformance_toggle_channelEnable or disable a trace channel at runtime (mid-trace)
Enables or disables a single trace channel on the running engine without restarting the trace. Use it to add a channel mid-session once you've narrowed down a suspect, or to drop an expensive channel. Channel name is matched leniently (case-insensitive, optional 'Channel' suffix).
| Parameter | Type | Required | Description |
|---|---|---|---|
| channel | string | Yes | Channel name (e.g. cpu, mass, memalloc) |
| enabled | bool | No | true to enable, false to disable |
cfa performance_toggle_channel --channel mass
cfa performance_toggle_channel --channel memalloc --enabled=falseperformance_trace_bookmarkInsert a named bookmark into the live trace timeline
Emits a named bookmark into the active trace so you can mark exactly when something happened (e.g. 'spawned 10k belts') and find it later in performance_analyze_insight --query bookmarks. Only recorded while a trace is active with the 'bookmark' channel enabled.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Bookmark label |
cfa performance_trace_bookmark --name "spawned 10k belts"performance_trace_snapshotWrite a trace snapshot (tail buffer) to a.utrace file
Writes the current in-memory trace tail to a.utrace file without stopping the recording. Useful to capture the moments leading up to a spike you just saw. Leave file_path empty for an auto-generated path under the project's Profiling directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
| file_path | string | No | Output snapshot path (empty = auto) |
cfa performance_trace_snapshot
cfa performance_trace_snapshot --file-path "C:/Traces/spike.utrace"performance_trace_screenshotCapture a screenshot into the live trace
Requests a screenshot to be embedded into the active trace on the next frame, so you can visually correlate the viewport with a timing spike in Unreal Insights. Needs an active trace with the 'screenshot' channel enabled.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | No | Screenshot label (default CFA_Screenshot) |
| show_ui | bool | No | Include editor UI in the capture |
cfa performance_trace_screenshot --name "before-spike"performance_trace_objectRegister UObject(s) for per-frame property tracing (objectproperties query)
Registers actors (matched by name and/or class in the editor/PIE world) so the trace records their UObject property values every frame, and enables the 'object' + 'objectproperties' channels. Object-property tracing is opt-in per object, nothing is recorded until you register. After registering, record (or keep recording) a trace, then read the values back with performance_analyze_insight --query objectproperties --object <name>. Pass --enabled=false to unregister.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | No | Actor label/name substring to match |
| class | string | No | Class-name substring to match (combine with name to narrow) |
| enabled | bool | No | true to register for tracing, false to unregister |
| count | int | No | Max objects to register |
cfa performance_trace_object --name BP_Miner
cfa performance_trace_object --class StaticMeshActor --count 5
cfa performance_trace_object --name BP_Miner --enabled=falseperformance_live_startStart sampling live per-frame timing (no trace needed)
Begins sampling the engine's per-frame timing counters every frame (frame time plus game/render/rhi/gpu thread ms) via FCoreDelegates::OnEndFrame. No trace and no 'stat unit' are needed, it reads the always-fresh engine counters directly. Let the editor or PIE run for a while, then call performance_live_stop to get the distribution across all sampled frames (min/avg/max/p50/p95/p99 + avg and 1%-low fps), so a single biased frame can't mislead. Sampling self-stops at --max-frames.
| Parameter | Type | Required | Description |
|---|---|---|---|
| max_frames | int | No | Stop sampling automatically after this many frames |
cfa performance_live_start
cfa performance_live_start --max-frames 600performance_live_stopStop live sampling and return the multi-frame timing distribution
Stops the live sampler started by performance_live_start and returns the distribution over all sampled frames: for frame time and each of game/render/rhi/gpu thread ms, the min/avg/max/p50/p95/p99, plus avg fps and 1%-low fps (1000 / p99 frame ms, worst-case smoothness). frame_ms reflects displayed frame time (vsync / t.MaxFPS / editor throttle capped); the thread and gpu ms show the actual per-thread work.
cfa performance_live_stop