SwiftUI instrument · Cause & Effect · hitches & hangs

debugging · folio

In one line: The SwiftUI template (Instruments 26+) times every SwiftUI update: lanes flag the long ones, Time Profiler shows what ran, the Cause & Effect Graph shows why. A hitch = a frame left on screen too long (one late refresh is enough); a hang = a discrete input (tap, key) left waiting on a busy or blocked main thread.

Download PDF Print view LaTeX source

SwiftUI instrument · Cause & Effect · hitches & hangs — figure 1

The SwiftUI template (Instruments 26+)

  • Contents: the next-generation SwiftUI instrument + Time Profiler + Hangs + Hitches. Needs Xcode 26 and a device OS that records SwiftUI traces; any Instruments 27 recording needs iOS 17+. Command-I (Profile) builds Release. The old View Body / View Properties instruments: deprecated, still in the library.

laneshows
Update Groupswhen SwiftUI works at all — CPU busy while it is empty ⇒ the cost is outside SwiftUI
Long View Body Updatesbody runs: orange > 500 µs, red > 1000 µs
Long Representable UpdatesUIKit / AppKit views hosted in SwiftUI (docs: Long Platform View Updates)
Other Long Updatesother SwiftUI work: geometry, text layout

  • Orange / red = how likely an update is to cause a hitch or hang — start with red; long ones just after launch (the first hierarchy) are normal. Expanded: View Body / Representable / Other Updates subtracks per module (your app, an SDK, the system); the rest grey.
  • Detail pane: summary by process → module → view type, with counts; filter to Long View Body Updates or All Updates. 26: Show View Hierarchy. 27: Summary of Updates focus action in the View Hierarchy view; layout passes + why a layout was not cached.

Two questions, two workflows

  • Too long? Hover the view → arrow → Show Updates → Control-click one → Set Inspection Range and Zoom → click the Time Profiler track: the call tree (or Flame Graph) of that update only. Too few samples in one update: repeat it, then Show Calls Made by MyView.body merges every instance.
  • Too often? A long Update Group with no long update = many short ones. Set Inspection Range on the group (start it earlier to catch the cause) → All Updates counts → hover a view → Show Cause & Effect Graph. A blue → grey → blue chain = your code causing an update your own code then reacts to (e.g. onGeometryChange driving layout): act only past a threshold.
  • Why a body runs (AttributeGraph): view structs are rebuilt all the time; attributes keep identity and state. A state change opens a transaction; at the next frame it marks that attribute outdated, flags every dependent (cheap), then recomputes the outdated ones. “Why did body run?” = “what marked it outdated?” Self._printChanges() (debug only, best effort) names what changed, never who changed it.
  • Environment: reading @Environment depends on all of EnvironmentValues — any change notifies every reader, each checks its value, so a skipped body still costs. Keep geometry and timers out of it.

A Cause & Effect Graph

SwiftUI instrument · Cause & Effect · hitches & hangs — figure 2

Hang vs hitch — Apple’s definitions

hanghitch
noticedmain thread unresponsive ~50–100 ms+one refresh interval: 8.3 ms (120 Hz), 16.7 ms (60 Hz)
budget< 100 ms in all, under half of it on mainmain-thread work < 5 ms per frame is usually on time
causemain thread busy or blockedapp late: commit; render server late: render (rarely a hang)
seenrun loop busy past the threshold, input or not (a potential hang)only while a frame is due (scroll, animation)
fieldHang Rate: s/hour of hangs > 250 ms (median, p90)Hitches (27): ms/s — ≤10 good, ≤25 warning, ≤50 critical

Three kinds of hang

kindtypical causefix
busyone call too long, or called too often: 70 bodies × ~50 ms > 3 sdo less (lazy container, cache) or move off main
asyncevery handler short, but work queued earlier on main runs first — a sync call inside .task, which inherits MainActorasync + nonisolated (SE-0461 on: @concurrent)
blockedwaiting in a syscall (mach_msg2_trap), on a lock or semaphore, in a lazy static let init (await does not help)never wait on main

Before release

  • Settings → Developer → Hang Detection (development + TestFlight builds, from 250 ms) → hang log + tailspin. Hang reporting times only the main run loop: event delivery + render add 10–50 ms more to what the user feels.

Traps

  • Fix hangs first — that removes many commit hitches too.
  • One changed property per graph edge: after a fix, record again.
  • Blocked ≠ unresponsive — an idle main thread is blocked; Hangs decides.

Report a problem ·Discuss this folio