Apple Profiler — Plugin Guide
Workflow
CPU profiling (.trace files)
- Record with
xctrace record (see Recording CPU Traces)
- Open with
profiler_open_trace to see metadata and available tables
- Analyze with
profiler_top_functions, profiler_cpu_samples, etc.
GPU profiling (.gputrace files)
- Capture with Metal environment variables or
MTLCaptureManager (see Capturing GPU Traces)
- Open with
profiler_gpu_open to see kernels, command buffers, encoders
- Analyze with
profiler_gpu_timeline, profiler_gpu_dependencies, profiler_gpu_counters
Choosing a Template
Use the template that matches what you're investigating:
| Template |
Use when |
Key tables |
| Time Profiler |
General CPU hotspot analysis |
time-profile (CPU samples with stack traces) |
| CPU Profiler |
Detailed CPU profiling with cycle counts |
cpu-profile (CPU samples with stack traces) |
| Metal System Trace |
GPU performance, Metal API, shader execution |
time-profile, metal-gpu-intervals, metal-driver-intervals, metal-application-intervals |
| Allocations |
Memory allocation tracking, leaks |
allocation tables |
| Leaks |
Memory leak detection |
leak tables |
| System Trace |
Thread scheduling, syscalls, VMFault |
system trace tables |
| Swift Concurrency |
async/await, actors, task scheduling |
Swift actor/task tables |
| SwiftUI |
View body evaluation, update triggers |
SwiftUI-specific tables |
| App Launch |
Launch time analysis |
launch-related tables |
| Animation Hitches |
Frame drops, hitches, render performance |
hitch/frame tables |
| Network |
HTTP traffic, connection analysis |
HTTP/network tables |
| Hangs |
Main thread unresponsiveness |
potential-hangs |
| Core ML |
ML model inference performance |
Core ML tables |
| Game Performance |
Combined CPU/GPU/memory for games |
Multiple game-related tables |
| Power Profiler |
Energy impact, battery drain |
power/energy tables |
| RealityKit Trace |
AR/3D rendering performance |
RealityKit tables |
Recording CPU Traces
Use xctrace record to create .trace files for CPU/system analysis:
# Profile a command (records until program exits or time-limit)
xctrace record --template "Time Profiler" --time-limit 10s --launch -- ./my-app arg1 arg2
# Attach to running process
xctrace record --template "Time Profiler" --time-limit 10s --attach <pid-or-name>
# Profile all processes (system-wide)
xctrace record --template "Time Profiler" --time-limit 5s --all-processes
# CPU + GPU system-level profiling
xctrace record --template "Metal System Trace" --time-limit 10s --launch -- ./my-metal-app
# Output to specific path
xctrace record --template "Time Profiler" --output /tmp/recording.trace --launch -- ./my-app
# Set environment variables for launched process
xctrace record --template "Time Profiler" --env METAL_DEVICE_WRAPPER_TYPE=1 --launch -- ./my-app
Profiling a specific code section: Use os_signpost to mark the region of interest, then filter the trace by time range:
import os
let log = OSLog(subsystem: "com.myapp", category: .pointsOfInterest)
os_signpost(.begin, log: log, name: "HotPath")
// ... code to profile ...
os_signpost(.end, log: log, name: "HotPath")
Then record with --instrument "os_signpost" alongside the profiler template, use profiler_signpost_intervals to find the time range, and scope profiler_cpu_samples/profiler_top_functions to that window.
Capturing GPU Traces
GPU traces (.gputrace bundles) capture the full Metal command stream — every dispatch, buffer binding, barrier, and optionally shader performance counters.
Method 1: Environment Variables (simplest for CLI tools)
Set MTL_CAPTURE_ENABLED=1 and METAL_CAPTURE_ENABLED=1 to capture the entire Metal workload:
# Capture everything — produces a .gputrace in the current directory
MTL_CAPTURE_ENABLED=1 METAL_CAPTURE_ENABLED=1 ./my-metal-app
# Specify output path
MTL_CAPTURE_ENABLED=1 METAL_CAPTURE_ENABLED=1 \
METAL_CAPTURE_OUTPUT_PATH=/tmp/my_capture.gputrace \
./my-metal-app
This captures from the first Metal command to program exit. Good for short-running compute workloads.
Method 2: MTLCaptureManager (profile specific code sections)
For profiling a specific section of execution, add capture bracketing in the Metal code:
import Metal
func profileSection(device: MTLDevice, commandQueue: MTLCommandQueue) {
let captureManager = MTLCaptureManager.shared()
let descriptor = MTLCaptureDescriptor()
descriptor.captureObject = device // or commandQueue for narrower scope
descriptor.destination = .gpuTraceDocument
descriptor.outputURL = URL(fileURLWithPath: "/tmp/my_capture.gputrace")
do {
try captureManager.startCapture(with: descriptor)
} catch {
print("Capture failed to start: \(error)")
return
}
// ... Metal work to profile ...
// (encode commands, commit command buffers, wait for completion)
captureManager.stopCapture()
}
For C/Objective-C Metal code:
#import <Metal/Metal.h>
// Start capture
MTLCaptureManager *mgr = [MTLCaptureManager sharedCaptureManager];
MTLCaptureDescriptor *desc = [[MTLCaptureDescriptor alloc] init];
desc.captureObject = device; // or commandQueue
desc.destination = MTLCaptureDestinationGPUTraceDocument;
desc.outputURL = [NSURL fileURLWithPath:@"/tmp/my_capture.gputrace"];
NSError *err;
[mgr startCaptureWithDescriptor:desc error:&err];
// ... Metal work to profile ...
[mgr stopCapture];
Important: The output directory must exist and the .gputrace must not already exist (delete first if re-capturing).
Method 3: Xcode (interactive)
- Open the project in Xcode
- Run with the GPU Frame Capture button (camera icon in debug bar)
- Click "Capture GPU Workload" during execution
- Save the capture as a
.gputrace file
Getting shader performance counters
The profiler_gpu_counters tool requires shader profiling data (streamData) which is only generated when the GPU trace is replayed with profiling enabled in Xcode:
- Open the
.gputrace in Xcode
- Click the Replay button (with shader profiling enabled in settings)
- Xcode writes
streamData into the .gputrace bundle
- Now
profiler_gpu_counters can read occupancy, bandwidth, cache hit rates, etc.
Available Tools
CPU analysis (.trace files — Time Profiler, CPU Profiler, Metal System Trace)
profiler_open_trace — Open trace and return metadata + table list.
profiler_cpu_samples — Individual samples with full stack traces. Use start_time_ns/end_time_ns to scope to a time window.
profiler_top_functions — Aggregated view: which functions consumed the most CPU. Also supports time-range filtering.
Hang detection (requires Hangs instrument)
profiler_hangs — Lists unresponsiveness intervals with type, duration, and thread.
Signpost analysis (requires os_signpost instrument)
profiler_signpost_events — Raw begin/end/event entries. Filter by subsystem, category, name.
profiler_signpost_intervals — Matched begin+end pairs with durations.
Generic table access (works with any .trace)
profiler_list_tables — Discover all available schemas in the trace.
profiler_query_table — Query any table by schema name. Use this for Metal GPU tables, thermal data, disk I/O, or anything not covered by the specialized tools above.
Correlated CPU+GPU analysis (Metal System Trace .trace files)
profiler_correlated_timeline — Time-bucketed view showing CPU and GPU activity side by side. Auto-detects execution phases: CPU_BOUND, GPU_BOUND, BALANCED, PIPELINE_BUBBLE, IDLE. Returns per-bucket breakdown plus summary with bottleneck classification.
GPU trace analysis (.gputrace files)
profiler_gpu_open — Structural overview: kernels, command buffers, encoders, dispatch/barrier counts.
profiler_gpu_timeline — Detailed dispatch events with kernel names, threadgroup sizes, buffer bindings. Filter by kernel pattern, command buffer, or encoder.
profiler_gpu_dependencies — Buffer hazard DAG with critical path analysis. View at dispatch, encoder, kernel, or command buffer scale.
profiler_gpu_counters — Shader profiling counters (occupancy, bandwidth, cache rates). Summary stats or full time-series.
profiler_gpu_scheduling — Scheduling overhead analysis. Identifies inter-encoder gaps (GPU idle between encoder submissions) and dispatch fusion candidates (many small dispatches that could be combined). Returns prioritized recommendations with estimated savings. Requires shader profiling data (streamData).
profiler_gpu_export_perfetto — Export to .pftrace for visualization in ui.perfetto.dev.
Analysis Patterns
"Why is my app slow?"
- Record with Time Profiler:
xctrace record --template "Time Profiler" --time-limit 10s --launch -- ./app
profiler_open_trace to confirm recording
profiler_top_functions with n=20 to find hotspots
profiler_cpu_samples with limit=50 to see stack traces for the hot functions
"Why does the UI hang?"
- Record with Hangs template or include Hangs instrument
profiler_hangs to find hang intervals
- Use the hang's
start_ns and duration_ns to scope profiler_cpu_samples to that time window
"Is my Metal code efficient?" (system-level)
- Record with Metal System Trace:
xctrace record --template "Metal System Trace" --launch -- ./app
profiler_list_tables to see available Metal tables
profiler_query_table with metal-gpu-intervals for GPU execution
profiler_query_table with metal-driver-intervals for driver overhead
profiler_top_functions to see CPU-side costs
"What happened in this specific time window?"
- Use
profiler_cpu_samples (no limit) to find the time range of interest from timestamps
- Call
profiler_top_functions(start_time_ns=X, end_time_ns=Y) to see what was hot in that window
- Call
profiler_cpu_samples(start_time_ns=X, end_time_ns=Y, limit=30) for detailed stack traces
"Optimize my Metal compute kernels" (GPU trace)
- Capture a
.gputrace (see Capturing GPU Traces)
profiler_gpu_open to see kernel list, dispatch counts, command buffer structure
profiler_gpu_scheduling to find scheduling overhead — inter-encoder gaps and fusion candidates
profiler_gpu_dependencies at encoder or kernel scale to find the critical path
profiler_gpu_timeline with kernel_filter to inspect specific dispatches (threadgroup sizes, buffer bindings)
profiler_gpu_counters for shader performance metrics (requires Xcode replay)
profiler_gpu_export_perfetto to create a visual timeline for the user
"Which GPU dispatches could run in parallel?"
profiler_gpu_dependencies with scale=dispatch to see the full buffer dependency DAG
- Check the
critical_path_length vs total_dispatches — large gap means parallelism exists
- Look for
isolated_nodes — dispatches with no dependencies that could overlap with anything
- Use
profiler_gpu_dependencies with scale=kernel to see which kernel types have cross-dependencies
"Profile both CPU and GPU sides"
- Record with Metal System Trace:
xctrace record --template "Metal System Trace" --time-limit 10s --launch -- ./app
profiler_correlated_timeline on the .trace to see CPU and GPU activity side by side with auto-detected phases
- Check the
summary.bottleneck field — it tells you if the app is CPU_BOUND, GPU_BOUND, or BALANCED
- For GPU-bound workloads: capture a
.gputrace and use profiler_gpu_scheduling to find if encoder consolidation would help
- For CPU-bound workloads: use
profiler_top_functions to find the CPU hotspot (is it command encoding? shader compilation? data preparation?)
"Should I combine my GPU operations?"
- Capture a
.gputrace with shader profiling data (see Getting shader performance counters)
profiler_gpu_scheduling — check summary.inter_encoder_gap_pct. If >5%, combining encoders will help
- Check
encoder_gaps for specific gaps and whether they're COMBINABLE (shared kernels) or COMBINABLE_DIFFERENT_KERNELS (different work but no CPU readback needed)
- Check
fusion_candidates for sequences of many small dispatches that could be batched into fewer, larger ones
- Follow the
recommendations — they're prioritized by potential savings
All Available Instruments
These can be added to a recording with --instrument <name>:
Activity Monitor, Allocations, Audio Client, Audio Server, Audio Statistics,
CPU Counters, CPU Profiler, Core Animation Activity, Core Animation Commits,
Core Animation FPS, Core Animation Server, Core ML, Data Faults, Data Fetches,
Data Saves, Disk I/O Latency, Disk Usage, Display, Filesystem Activity,
Filesystem Suggestions, Foundation Models, Frame Lifetimes, GCD Performance,
GPU, HTTP Traffic, Hangs, Hitches, Leaks, Location Energy Model,
Metal Application, Metal GPU Counters, Metal Performance Overview,
Metal Resource Events, Network Connections, Neural Engine, Points of Interest,
Power Profiler, Processor Trace, RealityKit Frames, RealityKit Metrics,
Runloops, Sampler, SceneKit Application, Swift Actors, Swift Tasks, SwiftUI,
System Call Trace, System Load, Thermal State, Thread State Trace,
Time Profiler, VM Tracker, Virtual Memory Trace, dyld Activity,
os_log, os_signpost, stdout/stderr
1---2name: profiler-guide3description: Reference guide for Apple CPU and GPU profiling tools — workflows, recording traces, analysis patterns, and all available instruments4user-invocable: false5metadata:6 source: https://skillmd.com/skills/robtaylor/profiler-guide7---89# Apple Profiler — Plugin Guide1011## Workflow1213### CPU profiling (`.trace` files)141. **Record** with `xctrace record` (see [Recording CPU Traces](#recording-cpu-traces))152. **Open** with `profiler_open_trace` to see metadata and available tables163. **Analyze** with `profiler_top_functions`, `profiler_cpu_samples`, etc.1718### GPU profiling (`.gputrace` files)191. **Capture** with Metal environment variables or `MTLCaptureManager` (see [Capturing GPU Traces](#capturing-gpu-traces))202. **Open** with `profiler_gpu_open` to see kernels, command buffers, encoders213. **Analyze** with `profiler_gpu_timeline`, `profiler_gpu_dependencies`, `profiler_gpu_counters`2223## Choosing a Template2425Use the template that matches what you're investigating:2627| Template | Use when | Key tables |28|----------|----------|------------|29| **Time Profiler** | General CPU hotspot analysis | `time-profile` (CPU samples with stack traces) |30| **CPU Profiler** | Detailed CPU profiling with cycle counts | `cpu-profile` (CPU samples with stack traces) |31| **Metal System Trace** | GPU performance, Metal API, shader execution | `time-profile`, `metal-gpu-intervals`, `metal-driver-intervals`, `metal-application-intervals` |32| **Allocations** | Memory allocation tracking, leaks | allocation tables |33| **Leaks** | Memory leak detection | leak tables |34| **System Trace** | Thread scheduling, syscalls, VMFault | system trace tables |35| **Swift Concurrency** | async/await, actors, task scheduling | Swift actor/task tables |36| **SwiftUI** | View body evaluation, update triggers | SwiftUI-specific tables |37| **App Launch** | Launch time analysis | launch-related tables |38| **Animation Hitches** | Frame drops, hitches, render performance | hitch/frame tables |39| **Network** | HTTP traffic, connection analysis | HTTP/network tables |40| **Hangs** | Main thread unresponsiveness | `potential-hangs` |41| **Core ML** | ML model inference performance | Core ML tables |42| **Game Performance** | Combined CPU/GPU/memory for games | Multiple game-related tables |43| **Power Profiler** | Energy impact, battery drain | power/energy tables |44| **RealityKit Trace** | AR/3D rendering performance | RealityKit tables |4546## Recording CPU Traces4748Use `xctrace record` to create `.trace` files for CPU/system analysis:4950```bash51# Profile a command (records until program exits or time-limit)52xctrace record --template "Time Profiler" --time-limit 10s --launch -- ./my-app arg1 arg25354# Attach to running process55xctrace record --template "Time Profiler" --time-limit 10s --attach <pid-or-name>5657# Profile all processes (system-wide)58xctrace record --template "Time Profiler" --time-limit 5s --all-processes5960# CPU + GPU system-level profiling61xctrace record --template "Metal System Trace" --time-limit 10s --launch -- ./my-metal-app6263# Output to specific path64xctrace record --template "Time Profiler" --output /tmp/recording.trace --launch -- ./my-app6566# Set environment variables for launched process67xctrace record --template "Time Profiler" --env METAL_DEVICE_WRAPPER_TYPE=1 --launch -- ./my-app68```6970**Profiling a specific code section**: Use `os_signpost` to mark the region of interest, then filter the trace by time range:71```swift72import os73let log = OSLog(subsystem: "com.myapp", category: .pointsOfInterest)74os_signpost(.begin, log: log, name: "HotPath")75// ... code to profile ...76os_signpost(.end, log: log, name: "HotPath")77```78Then record with `--instrument "os_signpost"` alongside the profiler template, use `profiler_signpost_intervals` to find the time range, and scope `profiler_cpu_samples`/`profiler_top_functions` to that window.7980## Capturing GPU Traces8182GPU traces (`.gputrace` bundles) capture the full Metal command stream — every dispatch, buffer binding, barrier, and optionally shader performance counters.8384### Method 1: Environment Variables (simplest for CLI tools)8586Set `MTL_CAPTURE_ENABLED=1` and `METAL_CAPTURE_ENABLED=1` to capture the entire Metal workload:8788```bash89# Capture everything — produces a .gputrace in the current directory90MTL_CAPTURE_ENABLED=1 METAL_CAPTURE_ENABLED=1 ./my-metal-app9192# Specify output path93MTL_CAPTURE_ENABLED=1 METAL_CAPTURE_ENABLED=1 \94 METAL_CAPTURE_OUTPUT_PATH=/tmp/my_capture.gputrace \95 ./my-metal-app96```9798This captures from the first Metal command to program exit. Good for short-running compute workloads.99100### Method 2: MTLCaptureManager (profile specific code sections)101102For profiling a specific section of execution, add capture bracketing in the Metal code:103104```swift105import Metal106107func profileSection(device: MTLDevice, commandQueue: MTLCommandQueue) {108 let captureManager = MTLCaptureManager.shared()109 let descriptor = MTLCaptureDescriptor()110 descriptor.captureObject = device // or commandQueue for narrower scope111 descriptor.destination = .gpuTraceDocument112 descriptor.outputURL = URL(fileURLWithPath: "/tmp/my_capture.gputrace")113114 do {115 try captureManager.startCapture(with: descriptor)116 } catch {117 print("Capture failed to start: \(error)")118 return119 }120121 // ... Metal work to profile ...122 // (encode commands, commit command buffers, wait for completion)123124 captureManager.stopCapture()125}126```127128For C/Objective-C Metal code:129```objc130#import <Metal/Metal.h>131132// Start capture133MTLCaptureManager *mgr = [MTLCaptureManager sharedCaptureManager];134MTLCaptureDescriptor *desc = [[MTLCaptureDescriptor alloc] init];135desc.captureObject = device; // or commandQueue136desc.destination = MTLCaptureDestinationGPUTraceDocument;137desc.outputURL = [NSURL fileURLWithPath:@"/tmp/my_capture.gputrace"];138NSError *err;139[mgr startCaptureWithDescriptor:desc error:&err];140141// ... Metal work to profile ...142143[mgr stopCapture];144```145146**Important**: The output directory must exist and the `.gputrace` must not already exist (delete first if re-capturing).147148### Method 3: Xcode (interactive)1491501. Open the project in Xcode1512. Run with the GPU Frame Capture button (camera icon in debug bar)1523. Click "Capture GPU Workload" during execution1534. Save the capture as a `.gputrace` file154155### Getting shader performance counters156157The `profiler_gpu_counters` tool requires shader profiling data (streamData) which is only generated when the GPU trace is **replayed with profiling enabled** in Xcode:1581591. Open the `.gputrace` in Xcode1602. Click the **Replay** button (with shader profiling enabled in settings)1613. Xcode writes `streamData` into the `.gputrace` bundle1624. Now `profiler_gpu_counters` can read occupancy, bandwidth, cache hit rates, etc.163164## Available Tools165166### CPU analysis (`.trace` files — Time Profiler, CPU Profiler, Metal System Trace)167- `profiler_open_trace` — Open trace and return metadata + table list.168- `profiler_cpu_samples` — Individual samples with **full stack traces**. Use `start_time_ns`/`end_time_ns` to scope to a time window.169- `profiler_top_functions` — Aggregated view: which functions consumed the most CPU. Also supports time-range filtering.170171### Hang detection (requires Hangs instrument)172- `profiler_hangs` — Lists unresponsiveness intervals with type, duration, and thread.173174### Signpost analysis (requires os_signpost instrument)175- `profiler_signpost_events` — Raw begin/end/event entries. Filter by subsystem, category, name.176- `profiler_signpost_intervals` — Matched begin+end pairs with durations.177178### Generic table access (works with any `.trace`)179- `profiler_list_tables` — Discover all available schemas in the trace.180- `profiler_query_table` — Query any table by schema name. Use this for Metal GPU tables, thermal data, disk I/O, or anything not covered by the specialized tools above.181182### Correlated CPU+GPU analysis (Metal System Trace `.trace` files)183- `profiler_correlated_timeline` — Time-bucketed view showing CPU and GPU activity side by side. Auto-detects execution phases: `CPU_BOUND`, `GPU_BOUND`, `BALANCED`, `PIPELINE_BUBBLE`, `IDLE`. Returns per-bucket breakdown plus summary with bottleneck classification.184185### GPU trace analysis (`.gputrace` files)186- `profiler_gpu_open` — Structural overview: kernels, command buffers, encoders, dispatch/barrier counts.187- `profiler_gpu_timeline` — Detailed dispatch events with kernel names, threadgroup sizes, buffer bindings. Filter by kernel pattern, command buffer, or encoder.188- `profiler_gpu_dependencies` — Buffer hazard DAG with critical path analysis. View at dispatch, encoder, kernel, or command buffer scale.189- `profiler_gpu_counters` — Shader profiling counters (occupancy, bandwidth, cache rates). Summary stats or full time-series.190- `profiler_gpu_scheduling` — Scheduling overhead analysis. Identifies inter-encoder gaps (GPU idle between encoder submissions) and dispatch fusion candidates (many small dispatches that could be combined). Returns prioritized recommendations with estimated savings. Requires shader profiling data (streamData).191- `profiler_gpu_export_perfetto` — Export to `.pftrace` for visualization in ui.perfetto.dev.192193## Analysis Patterns194195### "Why is my app slow?"1961. Record with Time Profiler: `xctrace record --template "Time Profiler" --time-limit 10s --launch -- ./app`1972. `profiler_open_trace` to confirm recording1983. `profiler_top_functions` with n=20 to find hotspots1994. `profiler_cpu_samples` with limit=50 to see stack traces for the hot functions200201### "Why does the UI hang?"2021. Record with Hangs template or include Hangs instrument2032. `profiler_hangs` to find hang intervals2043. Use the hang's `start_ns` and `duration_ns` to scope `profiler_cpu_samples` to that time window205206### "Is my Metal code efficient?" (system-level)2071. Record with Metal System Trace: `xctrace record --template "Metal System Trace" --launch -- ./app`2082. `profiler_list_tables` to see available Metal tables2093. `profiler_query_table` with `metal-gpu-intervals` for GPU execution2104. `profiler_query_table` with `metal-driver-intervals` for driver overhead2115. `profiler_top_functions` to see CPU-side costs212213### "What happened in this specific time window?"2141. Use `profiler_cpu_samples` (no limit) to find the time range of interest from timestamps2152. Call `profiler_top_functions(start_time_ns=X, end_time_ns=Y)` to see what was hot in that window2163. Call `profiler_cpu_samples(start_time_ns=X, end_time_ns=Y, limit=30)` for detailed stack traces217218### "Optimize my Metal compute kernels" (GPU trace)2191. Capture a `.gputrace` (see [Capturing GPU Traces](#capturing-gpu-traces))2202. `profiler_gpu_open` to see kernel list, dispatch counts, command buffer structure2213. `profiler_gpu_scheduling` to find scheduling overhead — inter-encoder gaps and fusion candidates2224. `profiler_gpu_dependencies` at encoder or kernel scale to find the critical path2235. `profiler_gpu_timeline` with kernel_filter to inspect specific dispatches (threadgroup sizes, buffer bindings)2246. `profiler_gpu_counters` for shader performance metrics (requires Xcode replay)2257. `profiler_gpu_export_perfetto` to create a visual timeline for the user226227### "Which GPU dispatches could run in parallel?"2281. `profiler_gpu_dependencies` with scale=dispatch to see the full buffer dependency DAG2292. Check the `critical_path_length` vs `total_dispatches` — large gap means parallelism exists2303. Look for `isolated_nodes` — dispatches with no dependencies that could overlap with anything2314. Use `profiler_gpu_dependencies` with scale=kernel to see which kernel types have cross-dependencies232233### "Profile both CPU and GPU sides"2341. Record with Metal System Trace: `xctrace record --template "Metal System Trace" --time-limit 10s --launch -- ./app`2352. `profiler_correlated_timeline` on the `.trace` to see CPU and GPU activity side by side with auto-detected phases2363. Check the `summary.bottleneck` field — it tells you if the app is CPU_BOUND, GPU_BOUND, or BALANCED2374. For GPU-bound workloads: capture a `.gputrace` and use `profiler_gpu_scheduling` to find if encoder consolidation would help2385. For CPU-bound workloads: use `profiler_top_functions` to find the CPU hotspot (is it command encoding? shader compilation? data preparation?)239240### "Should I combine my GPU operations?"2411. Capture a `.gputrace` with shader profiling data (see [Getting shader performance counters](#getting-shader-performance-counters))2422. `profiler_gpu_scheduling` — check `summary.inter_encoder_gap_pct`. If >5%, combining encoders will help2433. Check `encoder_gaps` for specific gaps and whether they're `COMBINABLE` (shared kernels) or `COMBINABLE_DIFFERENT_KERNELS` (different work but no CPU readback needed)2444. Check `fusion_candidates` for sequences of many small dispatches that could be batched into fewer, larger ones2455. Follow the `recommendations` — they're prioritized by potential savings246247## All Available Instruments248249These can be added to a recording with `--instrument <name>`:250251Activity Monitor, Allocations, Audio Client, Audio Server, Audio Statistics,252CPU Counters, CPU Profiler, Core Animation Activity, Core Animation Commits,253Core Animation FPS, Core Animation Server, Core ML, Data Faults, Data Fetches,254Data Saves, Disk I/O Latency, Disk Usage, Display, Filesystem Activity,255Filesystem Suggestions, Foundation Models, Frame Lifetimes, GCD Performance,256GPU, HTTP Traffic, Hangs, Hitches, Leaks, Location Energy Model,257Metal Application, Metal GPU Counters, Metal Performance Overview,258Metal Resource Events, Network Connections, Neural Engine, Points of Interest,259Power Profiler, Processor Trace, RealityKit Frames, RealityKit Metrics,260Runloops, Sampler, SceneKit Application, Swift Actors, Swift Tasks, SwiftUI,261System Call Trace, System Load, Thermal State, Thread State Trace,262Time Profiler, VM Tracker, Virtual Memory Trace, dyld Activity,263os_log, os_signpost, stdout/stderr