-
Find and fix performance issues in your Metal games
Track down hard-to-find game performance issues with powerful Metal tools. Discover how to collect rich performance data using Game Performance Overview in Instruments, run background traces with metalperftrace on macOS and Control Center on iOS, and use the new StateReporting API to correlate metrics directly to your game's runtime state. Turn hours of telemetry into clear, actionable insights.
Chapters
- 0:00 - Introduction
- 1:51 - Metal performance metrics
- 3:32 - Trace collection
- 6:38 - Analyze performance traces
- 10:08 - Contextualize with StateReporting
- 17:48 - Collect field data with MetricKit
- 19:41 - Next steps
Resources
- Understanding the Metal Performance HUD metrics
- Monitoring your Metal app’s graphics performance
- Getting started with StateReporting
- Metal debugger
Related Videos
Tech Talks
-
Search this video…
-
-
5:00 - Collect a trace with metalperftrace
# Collect the last 5 hours metalperftrace collect /tmp --last 5h # Output # Metal performance traces collected to: /tmp # /tmp/MetalPerfTrace_20260401_094100_to_144100.atrc # Or collect an explicit time range metalperftrace collect /tmp \ --start 2026-04-01T09:41:00 \ --end 2026-04-01T12:41:00 -
7:02 - Print a trace overview
metalperftrace overview /Data/MyGameTrace.atrc # [Modern Renderer pid:13833] # Mem: 2146.1 MiB (2343.9 Peak, 1199.4 Metal) # Total CPU Time: 2417.601s (33.17% Sys, 66.83% User) # Instructions: 9944836683668 (5.75% P, 94.25% E) # Cycles: 5176430469224 (4.45% P, 95.55% E) # Disk Reads / Writes: 317.37 / 0.04 MiB (Logical Write 0.04) # Layer 0x729293000 (3456x2104) Interval 300.065s Active 300.065s # 59.7 FPS 17735 Frames 188 Skipped # Frame Time avg: 16.74ms min: 8.33 max: 125.00 stddev: 3.70 # CPU Begin-to-Present avg: 3.99ms min: 1.40 max: 94.37 stddev: 1.80 # On-GPU Time avg: 13.39ms min: 5.24 max: 37.57 stddev: 1.43 # Next Drawable Wait avg: 0.26ms min: 0.00 max: 91.08 stddev: 1.75 # Shader Compilation Time: 0.000s (Total: 0, Cached: 18) -
7:58 - Filter by process and emit JSON
// Report state transitions #import <StateReporting/StateReporting.h> NSString *domain = @"com.mygame.level"; SRStateReporter *reporter = [SRStateReporter reporterForDomain:domain]; [reporter reportTransitionToStateLabel:@"Level 1" stableMetadata:nil volatileMetadata:nil]; [reporter reportTransitionToStateLabel:@"Level 1" stableMetadata:@{ @"id": @1001 } volatileMetadata:nil]; [reporter reportVolatileMetadataUpdate:@{ @"health": @100 }]; -
13:55 - Include full state transitions in overview
metalperftrace overview /Data/MyGameTrace.atrc --include-state-transitions # [States] # com.mygame.graphics # High (30.59%, 14.996s) raytracing: 1 shadow: ultra # Medium (69.38%, 34.012s) raytracing: 0 shadow: medium # com.mygame.level # Level 1 (20.47%, 10.033s) biome: forest id: 1001 # Level 2 (79.53%, 38.991s) biome: volcano id: 1002 -
14:15 - Aggregate metrics by state
# Aggregate across all domains / transitions metalperftrace overview /Data/MyGameTrace.atrc --aggregate # Aggregate one domain metalperftrace overview /Data/MyGameTrace.atrc --aggregate \ --domain com.mygame.graphics # Aggregate a specific state label within a domain metalperftrace overview /Data/MyGameTrace.atrc --aggregate \ --domain com.mygame.graphics \ --state-label "High"
-
-
- 0:00 - Introduction
Overview of the challenge of maintaining consistent frame rates in games across long play sessions, and a preview of the new tools and workflows for collecting, analyzing, and contextualizing Metal performance data.
- 1:51 - Metal performance metrics
A tour of the Metal performance metrics available through tools like the Metal Performance HUD, covering FPS, GPU time, frame interval, layer sizes, composition mode, and MetalFX-related metrics.
- 3:32 - Trace collection
How to collect performance traces using the Game Performance Overview template in Instruments for desk testing, and the new always-on system-level data collection on iOS and macOS that stores Metal performance metrics for days.
- 6:38 - Analyze performance traces
How to analyze collected traces using the metalperftrace command-line tool on macOS — printing overviews, exporting JSON for scripting or AI agents — and how to open and visualize traces in Instruments to identify FPS drops and other anomalies.
- 10:08 - Contextualize with StateReporting
Introduces the StateReporting API, which lets you describe your game's behavior and state over time using domains, states, and metadata. Learn how state transitions appear in the Metal Performance HUD, metalperftrace output, and Instruments tracks to make performance issues immediately actionable.
- 17:48 - Collect field data with MetricKit
How to use MetricKit in macOS and iOS 27 to collect Metal frame rate data and other performance metrics in the field after your game ships, including per-state breakdowns using StateReporting domains.
- 19:41 - Next steps
Key takeaways and recommended next steps: adopt StateReporting, try the new trace collection tools and metalperftrace CLI, and explore related Metal developer tools documentation.