/profiling

name: performance-profiling
description: Guide performance profiling with Instruments, diagnose hangs, memory issues, slow launches, and energy drain. Use when reviewing app performance or investigating specific bottlenecks.
allowed-tools: [Read, Glob, Grep, Bash]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Performance Profiling

Systematic guide for profiling Apple platform apps using Instruments, Xcode diagnostics, and MetricKit. Covers CPU, memory, launch time, and energy analysis with actionable fix patterns.

When This Skill Activates

Use this skill when the user:

• Reports app hangs, stutters, or dropped frames
• Needs to profile CPU usage or find hot code paths
• Has memory leaks, high memory usage, or OOM crashes
• Wants to optimize app launch time
• Needs to reduce battery/energy impact
• Asks about Instruments, Time Profiler, Allocations, or Leaks
• Wants to add `os_signpost` or performance measurement to code
• Is preparing for App Store review and needs performance validation

Decision Tree

What performance problem are you investigating?
│
├─ App hangs / unresponsive to taps / slow UI
│  └─ Read time-profiler.md
│
├─ Scroll or animation stutter / dropped frames / hitches
│  └─ Read hitches.md
│
├─ High memory / leaks / OOM crashes / growing footprint
│  └─ Read memory-profiling.md
│
├─ Slow app launch / time to first frame
│  └─ Read launch-optimization.md
│
├─ Battery drain / thermal throttling / background energy
│  └─ Read energy-diagnostics.md
│
├─ General "app feels slow" (unknown cause)
│  └─ Start with time-profiler.md, then memory-profiling.md
│
└─ Pre-release performance audit
   └─ Read ALL reference files, use Review Checklist below

Quick Reference

| Problem | Instrument / Tool | Key Metric | Reference | |---------|-------------------|------------|-----------| | UI hangs > 250ms | Time Profiler + Hangs | Hang duration, main thread stack | time-profiler.md | | Scroll/animation hitches | Animation Hitches template | Hitch time ratio (< 5 ms/s good, > 10 critical) | hitches.md | | High CPU usage | Time Profiler / CPU Profiler | CPU % by function, call tree weight | time-profiler.md | | Memory leak | Leaks + Memory Graph | Leaked bytes, retain cycle paths | memory-profiling.md | | Memory growth | Allocations | Live bytes, generation analysis | memory-profiling.md | | Slow launch | App Launch | Time to first frame (pre-main + post-main) | launch-optimization.md | | Battery drain | Energy Log / Power Profiler | Energy Impact score, CPU/GPU/network | energy-diagnostics.md | | Thermal issues | Activity Monitor | Thermal state transitions | energy-diagnostics.md | | Network waste | Network profiler | Redundant fetches, large payloads | energy-diagnostics.md |

The 8 Key Metrics (WWDC21 10181)

Apple enumerates exactly eight things to track for app performance, all coverable with five tools (Xcode Organizer, MetricKit, Instruments, XCTest, App Store Connect API):

| # | Metric | Threshold / signal | Tool | |---|--------|--------------------|------| | 1 | Battery usage | Energy Gauge flags **CPU use > 20%** as High CPU, plus CPU Wake Overhead regions; top subsystems to watch: CPU, Networking, Location | Energy Gauge → Time Profiler | | 2 | Launch time | Time between icon tap and first frame rendered | App Launch template, XCTApplicationLaunchMetric | | 3 | Hang rate | Unresponsive to input for **≥ 250ms** | Hangs instrument, Organizer | | 4 | Memory | Organizer charts **peak memory** and **memory at suspension**; a spike with no termination spike yet is your early warning | Allocations, Leaks, VM Tracker | | 5 | Disk writes | Exception report when the app writes **> 1 GB in 24 hours** (with stack trace + Insights annotations) | File Activity template, XCTStorageMetric | | 6 | Scrolling | Red bars in the Organizer scrolling chart = poor scroll experience, fix immediately | Animation Hitches, XCTOSSignpostMetric.scrollDecelerationMetric | | 7 | Terminations | Every termination forces a slow cold launch next time and loses user state | MXAppExitMetric, Organizer | | 8 | MXSignposts | Custom marked intervals for your critical code sections | MetricKit |

The Organizer aggregates all of these from consented user devices across the **last 16 app versions**; the **Regressions pane** (Xcode 13) isolates every metric that increased significantly in the most recent version, in one place. The same data is available as JSON via the **App Store Connect API** (WWDC21 10181).

Process

1. Identify the Problem Category

Ask the user or inspect their description to classify the issue:

• **Responsiveness**: Hangs, stutters, animation drops
• **Memory**: Leaks, growth, OOM crashes
• **Launch**: Slow cold/warm start
• **Energy**: Battery drain, thermal throttling

2. Read the Appropriate Reference File

Each file contains:

• Which Instruments template to use
• Step-by-step profiling workflow
• How to interpret results
• Common fix patterns with code examples

3. Profile on Real Hardware

Always remind users:

• **Profile on device**, not Simulator (Simulator uses host CPU/memory)
• Use **Release** build configuration (optimizations change behavior)
• Profile with **representative data** (empty databases hide real perf)
• Close other apps to reduce noise

4. Apply Fixes and Verify

After identifying bottlenecks:

• Apply targeted fix from the reference file
• Re-profile to confirm improvement
• Add `os_signpost` markers for ongoing monitoring

Xcode Diagnostic Settings

Recommend enabling these in **Scheme > Run > Diagnostics**:

| Setting | What It Catches | |---------|-----------------| | Main Thread Checker | UI work off main thread | | Thread Sanitizer | Data races | | Address Sanitizer | Buffer overflows, use-after-free | | Malloc Stack Logging | Memory allocation call stacks | | Zombie Objects | Messages to deallocated objects |

MetricKit Integration

For production monitoring, recommend MetricKit (