Performance Instruments

Performance & Instruments

Measure first, then fix the thing the measurement points at. Guessing at performance wastes days. Pair with ios-test (perf tests) and ios-standards (concurrency).

> Rule: never optimize without a profile. A 2-line fix at the real hot spot beats a week of speculative micro-optimization elsewhere.

---

Pick the right instrument

| Problem | Instrument / tool | |---------|-------------------| | CPU hot spots, "where is time going" | Time Profiler | | App launch breakdown | App Launch template | | Main-thread stalls (UI freezes) | Hangs / Thread State | | Dropped frames while scrolling/animating | Animation Hitches / SwiftUI | | Memory growth, abandoned memory | Allocations + Leaks + Memory Graph | | Battery / wakeups / networking | Energy Log, Points of Interest | | Real-world data from users | MetricKit (MXMetricManager) |

Profile a Release/optimized build on a real device — Debug builds and the simulator lie about performance.

---

Launch time (the first impression)

Target ~250ms (user sees a freeze). A hitch** = a frame misses its deadline (stutter). On ProMotion (120Hz) the per-frame budget is ~8ms, so hitches are easier to hit.

• Get work off the main thread. Heavy decoding, file I/O, image resizing, JSON parsing → background (an actor or Task.detached), then hop back to @MainActor for UI only. See ios-standards.
• Don't block on await of slow work inside view updates. Load asynchronously and render a placeholder.
• In lists: pre-size rows, avoid synchronous image decode, use lazy stacks/List recycling.
• The Hangs instrument (and Xcode's runtime "Hang" warnings) pinpoint the blocking call stack.

---

Memory

• Leaks (cycles): the usual culprit is a closure capturing self strongly. Use [weak self] in escaping closures, delegates, and Tasks that outlive the view. The Memory Graph Debugger (Xcode → Debug Memory Graph) shows retain cycles visually; Leaks flags them live.
• Abandoned memory / growth: Allocations with "Mark Generation" — repeat an action, mark, and see what never frees. Caches without limits are a classic.
• Respond to memory pressure; don't cache unbounded. Large images: downsample to display size before keeping them.

---

MetricKit — performance from real users

Instruments shows your device; MetricKit shows the field.

import MetricKit
final class Metrics: NSObject, MXMetricManagerSubscriber {
    func didReceive(_ payloads: [MXMetricPayload]) { /* launch, hang, hitch, memory, disk, energy */ }
    func didReceive(_ payloads: [MXDiagnosticPayload]) { /* crash, hang, CPU-exception diagnostics */ }
}
// MXMetricManager.shared.add(subscriber)

Payloads arrive ~once/day. Aggregate applicationLaunchMetrics, applicationHangTime, animationMetrics (hitch ratio), and memoryMetrics to catch regressions you'd never reproduce locally. Feed these into your analytics (see app-analytics).

---

Workflow (/perf-audit)

1. Reproduce the complaint on a real device, Release build.
2. Pick the instrument for the symptom (table above) and capture a trace.
3. Find the single biggest contributor; fix it; re-measure to confirm the win.
4. Add a signpost or perf test (ios-test) so the regression can't silently return.
5. Check MetricKit trends after release to verify the fix holds in the field.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: markdavidgan
• Source: markdavidgan/apple-dev-skills
• License: MIT

Install and usage instructions live in the source repository linked above.