@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/debugging-instruments/references/instruments-guide.md

@@ -1,395 +1,247 @@
-# Instruments Guide Reference
-
-Detailed template-by-template guide for profiling iOS apps with Instruments. Companion to the main `debugging-instruments` skill.
-
-## Contents
-
-- [General Workflow](#general-workflow)
-- [Time Profiler](#time-profiler)
-- [Allocations](#allocations)
-- [Leaks](#leaks)
-- [Network](#network)
-- [SwiftUI Instruments](#swiftui-instruments)
-- [Animation Hitches and Core Animation](#animation-hitches-and-core-animation)
-- [Power Profiler](#power-profiler)
-- [File Activity](#file-activity)
-- [System Trace](#system-trace)
-- [xctrace CLI](#xctrace-cli)
-- [Custom Instruments with os_signpost](#custom-instruments-with-os_signpost)
-- [Automation and CI Integration](#automation-and-ci-integration)
-
-## General Workflow
-
-1. **Build for profiling**: Product > Profile (Cmd+I). This builds with Release optimization by default.
-2. **Select a template** from the Instruments chooser.
-3. **Configure recording**: Set the target device and process.
-4. **Record**: Press the red record button and reproduce the scenario.
-5. **Analyze**: Use the timeline, detail views, and call tree to find issues.
-6. **Filter**: Check "Hide System Libraries" and use the search bar to focus on your code.
-
-Always profile on a **physical device** for accurate measurements. Simulator
-performance does not reflect real-world behavior.
+# Instruments Guide
 
-## Time Profiler
-
-**When to use**: CPU is high, UI is slow, animations stutter, or you need to
-find which functions consume the most time.
-
-### Key Workflow
+Companion to the `debugging-instruments` skill: what each template is for, how
+to read it, and how to drive recordings from scripts.
 
-1. Record while reproducing the slow interaction.
-2. Select the time range of interest in the timeline.
-3. Switch to the **Call Tree** view in the detail pane.
-4. Enable these checkboxes:
-   - **Separate by Thread**  -  isolate main thread vs background
-   - **Invert Call Tree**  -  show leaf functions (actual work) first
-   - **Hide System Libraries**  -  focus on your code
-5. Sort by **Weight** (self time) to find the hottest functions.
-6. Double-click a function to view source with per-line timing.
+## Workflow That Fits Every Template
 
-### Reading the Call Tree
+Product > Profile (Cmd+I) builds the app for profiling, which uses the Release
+configuration unless the scheme says otherwise. Then:
 
-- **Weight**: total time in this function and all its callees
-- **Self Weight**: time spent in this function alone (not callees)
-- **Symbol Name**: the function  -  look for your module prefix
+1. Choose a template.
+2. Pick the device and the process to launch or attach to.
+3. Record while you reproduce the problem.
+4. Read the timeline, the detail pane and the call tree.
+5. Narrow the data with Hide System Libraries and the search field.
 
-Focus on functions with high **Self Weight**  -  these are doing the actual work.
+Profile on a physical device. Simulator runs on the Mac's CPU and memory and
+does not tell you how the app performs on a phone.
 
-### Tips
-
-- Profile the same user interaction 3 times to get stable measurements.
-- Use the **Comparison** view to diff traces before/after a fix.
-- Check "Flatten Recursion" if recursive calls make the tree hard to read.
-
-## Allocations
+## Time Profiler
 
-**When to use**: Memory grows over time, you suspect objects are not being
-freed, or you need to track object lifetimes.
+Use it for high CPU, slow screens, stuttering animations and for finding the
+most expensive functions.
 
-### Key Workflow
+Reading the call tree:
 
-1. Record while reproducing the scenario.
-2. Use **Mark Generation** (button in the detail pane) to snapshot allocations
-   at specific points. For example:
-   - Mark before navigating to a screen
-   - Navigate to the screen
-   - Navigate back
-   - Mark again
-   - The difference shows objects that were not freed
-3. Expand a generation to see allocations grouped by category.
-4. Filter by your module name to exclude system allocations.
+1. Drag across the timeline to select the slow period.
+2. Open the Call Tree and turn on Separate by Thread, Invert Call Tree (leaf
+   functions first) and Hide System Libraries.
+3. Sort by Weight and double-click a function to see its source with per-line
+   cost.
 
-### Allocation Lifespan
+Weight is time spent in the function including its callees; Self Weight counts
+only the function's own code. Functions with a high Self Weight are the ones
+doing the work.
 
-- **Created & Still Living**: objects allocated and not yet freed
-- **Created & Destroyed**: objects with normal lifetimes
-- **Persistent**: long-lived allocations (singletons, caches)
-- **Transient**: short-lived allocations (autoreleased, temporary)
+Tips:
+- Perform the interaction three times so the numbers settle.
+- Record before and after a change and diff them in the comparison view.
+- Flatten Recursion collapses deep recursive trees into one entry.
 
-Focus on "Created & Still Living" objects in the generation diff  -  these
-are your potential leaks.
+## Allocations
 
-### Heap Growth Analysis
+Generation analysis:
 
-Enable the **Allocations List** and sort by **Persistent Bytes**. Look for:
-- Classes with unexpectedly high instance counts
-- Image data or NSData objects that should have been released
-- View controllers that persist after dismissal
+1. Click Mark Generation.
+2. Open the screen under suspicion.
+3. Leave it again.
+4. Click Mark Generation once more.
 
-## Leaks
+The second generation holds what the round trip left behind. Expand it to see
+allocations grouped by category and filter by your module name.
 
-**When to use**: Suspected retain cycles or abandoned memory.
+Lifespan filters:
 
-### Key Workflow
+| Category | Meaning |
+|----------|---------|
+| Created & Still Living | Allocated in the range and still alive |
+| Created & Destroyed | Allocated and freed in the range |
+| Persistent | Long-lived by design: singletons, caches |
+| Transient | Short-lived temporaries and autoreleased objects |
 
-1. Run with the Leaks template.
-2. The tool automatically checks for leaks every 10 seconds.
-3. Red "Leak" markers appear in the timeline when leaks are detected.
-4. Click a leak marker to see the leaked object and its retain/release history.
-5. The **Cycles & Roots** view shows the reference graph  -  follow the arrows
-   to find the cycle.
+In a generation diff, "Created & Still Living" is where leaks hide.
 
-### Interpreting Results
+For overall heap growth, sort the Allocations List by Persistent Bytes. Watch
+for types with surprisingly high counts, images or `Data` buffers that are
+never released, and view controllers that outlive their dismissal.
 
-- **Leak**: an object with no references pointing to it (true orphan)
-- **Root Leak**: the object at the head of a leaked object graph
-- **Cycles & Roots graph**: arrows show retain relationships  -  look for
-  bidirectional arrows indicating a cycle
+## Leaks
 
-### Common Cycle Patterns
+- A leak check runs automatically every 10 seconds.
+- Red markers on the timeline show where leaks were found; click one to see the
+  object and its retain and release history.
+- Cycles & Roots draws the reference graph; arrows in both directions mean a
+  cycle.
+- A *leak* is an object nothing refers to any more; a *root leak* is the top of
+  a leaked object graph.
 
-Leaks instrument commonly catches:
-- Closure -> self -> closure cycles
-- Delegate strong reference cycles
-- NotificationCenter observer blocks retaining self
-- CADisplayLink/Timer retaining target
+Cycles this usually finds: a closure stored on an object that captures that
+object, strong delegate references, block-based `NotificationCenter` observers
+that capture `self`, and `CADisplayLink` or `Timer` retaining its target.
 
 ## Network
 
-**When to use**: Inspecting HTTP request/response timing, payload sizes,
-or connection reuse.
-
-### Key Workflow
+Each HTTP request appears as a bar on the timeline. Selecting one shows the
+URL, method, status code, headers, a timing split (DNS, connect, TLS, request,
+response) and the payload size.
 
-1. Record with the Network template.
-2. Each HTTP request appears as a bar in the timeline.
-3. Select a request to see:
-   - URL, method, status code
-   - Request/response headers
-   - Timing breakdown (DNS, connect, TLS, request, response)
-   - Payload size
+What to look for:
+- Gaps in a waterfall where requests run one after another but could run in
+  parallel.
+- Large responses that need pagination or compression.
+- The same request sent more than once.
+- Slow DNS or TLS setup that connection prewarming could hide.
 
-### What to Look For
+## SwiftUI
 
-- **Waterfall gaps**: sequential requests that could be parallelized
-- **Large payloads**: responses that could use pagination or compression
-- **Redundant requests**: duplicate calls to the same endpoint
-- **DNS/TLS latency**: consider connection prewarming
+Use it for bodies that run too often, redraws with no visible change, and list
+rows whose identity keeps changing.
 
-## SwiftUI Instruments
+Lanes to read:
+- **Update Groups**: batches of work SwiftUI performed together.
+- **Long View Body Updates**: bodies that took longer than the threshold.
+- **Cause and Effect Graph**: the chain of changes that made a view update.
 
-**When to use**: SwiftUI view body is evaluated too frequently, unnecessary
-redraws, or identity churn in lists.
-
-### Key Workflow
-
-1. Select the **SwiftUI** template in Instruments.
-2. Record while interacting with the UI.
-3. Check these lanes:
-   - **Update Groups**: shows batches of view updates triggered together
-   - **Long View Body Updates**: highlights body evaluations exceeding a time threshold
-   - **Cause and Effect Graph**: traces why a view was re-evaluated
-4. Look for views with excessive body evaluations during a single interaction.
-
-### Tips
-
-- Filter by view name to focus on a specific component.
-- Cross-reference with Time Profiler to see if body evaluations are expensive.
-- See the `swiftui-performance` skill for remediation patterns.
+Filter by view name and cross-check hot spots against Time Profiler. How to fix
+what you find belongs to the `swiftui-performance` skill.
 
 ## Animation Hitches and Core Animation
 
-**When to use**: Frame drops, off-screen rendering, excessive blending.
-
-### Key Workflow
-
-1. Record with the **Animation Hitches** template on a real device when the
-   symptom is stutter or missed frames.
-2. Add Core Animation instruments such as **Core Animation FPS**,
-   **Core Animation Commits**, or **Core Animation Activity** when you need
-   lower-level render pipeline detail.
-3. Check FPS, hitches, commits, and frame lifetime lanes for drops or long
-   commit/render work.
-4. Enable these debug options in Recording Options or Xcode view debugging:
-   - **Color Blended Layers**  -  red areas have multiple overlapping layers
-   - **Color Off-screen Rendered**  -  yellow areas use off-screen passes
-   - **Color Hits Green and Misses Red**  -  rasterization cache hits/misses
+Record Animation Hitches on a real device when scrolling or animations stutter
+or frames are missed. For lower-level rendering detail add Core Animation FPS,
+Core Animation Commits or Core Animation Activity, and read the FPS, hitch,
+commit and frame-lifetime lanes.
 
-### Common Issues
+Rendering diagnostics live in Xcode (Debug > View Debugging > Rendering) and
+in Simulator's Debug menu rather than in current Instruments:
+- **Color Blended Layers**: overlapping translucent layers show in red.
+- **Color Off-screen Rendered**: layers rendered off screen show in yellow.
+- **Color Hits Green and Misses Red**: rasterization cache hits and misses.
 
-| Issue | Indicator | Fix |
-|-------|-----------|-----|
-| Transparent overlapping views | Red blended layers | Use opaque backgrounds |
-| Corner radius + clip | Off-screen rendering | Use `cornerCurve` with pre-masked images |
-| Shadow without path | Off-screen rendering | Set `shadowPath` explicitly |
-| Large images not downsampled | High memory + slow rendering | Downsample before display |
+| Problem | Why it costs | Fix |
+|---------|--------------|-----|
+| Stacked transparent views | Blending, red in Color Blended Layers | Give views opaque backgrounds |
+| Rounded corners with `masksToBounds` over image content | Off-screen pass | Round the image once before display, or avoid masking |
+| Shadows without a path | Off-screen pass to find the shape | Set `shadowPath` |
+| Full-size images in small views | Memory and decode cost | Downsample to display size first |
 
 ## Power Profiler
 
-**When to use**: Battery drain complaints, background energy impact, or
-App Store rejection for excessive energy use.
+Use it for battery complaints, energy spent in the background, or an App Store
+rejection that cites energy use. Record on a physical device.
 
-### Key Workflow
+Read the power, thermal state and energy impact lanes, and the per-component
+split: CPU, network, location, GPU and background tasks.
 
-1. Record with the **Power Profiler** template on a physical device.
-2. Check power, thermal, and energy-impact lanes for high readings.
-3. Examine component breakdown:
-   - CPU
-   - Network
-   - Location
-   - GPU
-   - Background tasks
-
-### Tips
-
-- Profile typical user sessions (5-10 minutes of real usage).
-- Compare foreground vs background energy impact.
-- Check that background tasks complete and do not run indefinitely.
-- Cross-reference with MetricKit energy metrics from production.
+Tips:
+- Record a realistic session of 5 to 10 minutes.
+- Compare the app in the foreground with the app in the background.
+- Make sure background tasks finish and stop.
+- Cross-check against MetricKit energy metrics from the field.
 
 ## File Activity
 
-**When to use**: Slow file operations, excessive disk I/O, or disk write
-exceptions from MetricKit.
-
-### Key Workflow
-
-1. Record with the File Activity template.
-2. Look for:
-   - Frequent writes to the same file (journaling, logging)
-   - Large reads on the main thread
-   - Unintended file access patterns
+Use it for slow file operations, heavy disk I/O and MetricKit disk-write
+exceptions. Look for the same file written again and again, large reads on the
+main thread and access patterns you did not expect.
 
 ## System Trace
 
-**When to use**: Deep investigation of thread scheduling, virtual memory
-faults, system calls, and inter-process communication.
-
-### Key Workflow
+Use it when you need to see thread scheduling, virtual memory faults, system
+calls or IPC. Start from the main thread's lane and look for:
+- threads blocked on locks, semaphores or dispatch queues,
+- VM page faults,
+- a high number of context switches.
 
-1. Record with the System Trace template.
-2. Focus on the main thread lane.
-3. Look for:
-   - **Thread blocks**: main thread waiting on locks, semaphores, or dispatch queues
-   - **VM faults**: page faults from memory-mapped files or large allocations
-   - **Context switches**: excessive switching between threads
+It is the most detailed template. Reach for it after Time Profiler, when you
+need to know what the operating system was doing.
 
-This is the most advanced template  -  use it after Time Profiler when you
-need OS-level detail.
-
-## xctrace CLI
-
-### Recording
-
-```bash
-# Record Time Profiler trace
-xcrun xctrace record \
-    --template "Time Profiler" \
-    --device "iPhone" \
-    --output ~/traces/profile.trace \
-    --time-limit 30s \
-    --launch -- /path/to/MyApp.app
-
-# Record Allocations trace for a running app
-xcrun xctrace record \
-    --template "Allocations" \
-    --device "iPhone" \
-    --output ~/traces/alloc.trace \
-    --attach MyApp
-
-# Record with multiple instruments
-xcrun xctrace record \
-    --template "Time Profiler" \
-    --instrument "Allocations" \
-    --output ~/traces/combined.trace \
-    --launch -- /path/to/MyApp.app
-```
-
-### Exporting Data
+## xctrace
 
 ```bash
-# List available tables in a trace
-xcrun xctrace export --input profile.trace --toc
-
-# Export specific table as XML
-xcrun xctrace export --input profile.trace \
-    --xpath '/trace-toc/run/data/table[@schema="time-profile"]'
-
-# Export to a file
-xcrun xctrace export --input profile.trace \
-    --xpath '/trace-toc/run/data/table[@schema="time-profile"]' \
-    --output profile_data.xml
-```
-
-### Listing Resources
-
-```bash
-# Available templates
-xcrun xctrace list templates
-
-# Connected devices
-xcrun xctrace list devices
-
-# Available instruments
+xcrun xctrace record --template "Time Profiler" --time-limit 30s \
+  --output scroll.trace --launch -- /path/to/Atlas.app
+xcrun xctrace record --template "Allocations" --attach Atlas --output memory.trace
+xcrun xctrace export --input scroll.trace --toc
+xcrun xctrace export --input scroll.trace \
+  --xpath '/trace-toc/run/data/table[@schema="time-profile"]' --output time-profile.xml
 xcrun xctrace list instruments
 ```
 
-## Custom Instruments with os_signpost
+- `--time-limit` stops the recording on its own.
+- `--attach` records an app that is already running, instead of `--launch`.
+- `--toc` lists the tables inside a trace; `--xpath` picks one to export.
 
-### Emitting Signposts for Instruments
+## Custom Intervals with Signposts
 
 ```swift
 import os
 
-let signposter = OSSignposter(subsystem: "com.example.app", category: "Networking")
+let signposter = OSSignposter(subsystem: "com.example.atlas", category: "Catalog")
 
-func fetchUser(id: String) async throws -> User {
-    let signpostID = signposter.makeSignpostID()
-    let state = signposter.beginInterval("fetchUser", id: signpostID)
-    defer { signposter.endInterval("fetchUser", state) }
+func loadCatalog(from url: URL) async throws -> [Product] {
+    let id = signposter.makeSignpostID()
+    let state = signposter.beginInterval("loadCatalog", id: id)
+    defer { signposter.endInterval("loadCatalog", state) }
 
-    let (data, _) = try await URLSession.shared.data(from: userURL(id))
-    signposter.emitEvent("dataReceived", id: signpostID, "\(data.count) bytes")
-
-    return try JSONDecoder().decode(User.self, from: data)
+    let (data, _) = try await URLSession.shared.data(from: url)
+    signposter.emitEvent("downloaded", id: id, "\(data.count) bytes")
+    return try JSONDecoder().decode([Product].self, from: data)
 }
 ```
 
-### Viewing in Instruments
-
-1. Open Instruments with a Blank document, then add the **os_signpost**
-   instrument, or start from a template that includes **Points of Interest**.
-2. Your custom intervals appear as labeled bars in the timeline.
-3. Events appear as point markers.
-4. Filter by subsystem or category to isolate your signposts.
+To see them, start from a Blank document and add the os_signpost instrument,
+or use any template that includes Points of Interest. Intervals appear as
+labelled bars and events as single markers; filter by subsystem and category.
 
-### Integration with MetricKit
+Signposts written to a log from `MXMetricManager.makeLogHandle(category:)` are
+also counted in MetricKit payloads; the `metrickit-diagnostics` skill covers
+that side.
 
-Signposts emitted through `MXMetricManager.makeLogHandle(category:)` are
-also reported in MetricKit payloads. See the `metrickit` skill
-for details on custom signpost metrics.
+## Automation and CI
 
-## Automation and CI Integration
-
-### Performance Baselines with xctrace
-
-Create a shell script for CI:
+A script a CI job can run:
 
 ```bash
 #!/bin/bash
 set -euo pipefail
 
-APP_BUNDLE="build/MyApp.app"
-TRACE_OUTPUT="traces/ci_profile_$(date +%s).trace"
-TEMPLATE="Time Profiler"
-
-# Record trace
-xcrun xctrace record \
-    --template "$TEMPLATE" \
-    --output "$TRACE_OUTPUT" \
-    --time-limit 60s \
-    --launch -- "$APP_BUNDLE"
+stamp=$(date +%Y%m%d-%H%M%S)
+trace="traces/launch-$stamp.trace"
+mkdir -p traces
 
-# Export data for analysis
-xcrun xctrace export \
-    --input "$TRACE_OUTPUT" \
-    --toc > "traces/toc.xml"
-
-echo "Trace saved to $TRACE_OUTPUT"
+xcrun xctrace record --template "Time Profiler" --time-limit 60s \
+  --output "$trace" --launch -- "$APP_PATH"
+xcrun xctrace export --input "$trace" --toc > "traces/launch-$stamp-toc.xml"
 ```
 
-### XCTest Performance Metrics
-
-Complement Instruments with in-test measurements:
+XCTest can measure a flow and compare it with a stored baseline:
 
 ```swift
-func testScrollPerformance() {
-    let app = XCUIApplication()
-    app.launch()
-
-    let measureOptions = XCTMeasureOptions()
-    measureOptions.iterationCount = 5
-
-    measure(metrics: [
-        XCTClockMetric(),
-        XCTCPUMetric(),
-        XCTMemoryMetric(),
-        XCTStorageMetric()
-    ], options: measureOptions) {
-        app.swipeUp()
-        app.swipeDown()
+import XCTest
+
+final class FeedScrollPerformanceTests: XCTestCase {
+    @MainActor
+    func testFeedScrolling() {
+        let app = XCUIApplication()
+        app.launch()
+
+        let options = XCTMeasureOptions()
+        options.iterationCount = 5
+
+        measure(metrics: [XCTClockMetric(),
+                          XCTCPUMetric(application: app),
+                          XCTMemoryMetric(application: app),
+                          XCTStorageMetric(application: app)],
+                options: options) {
+            app.swipeUp()
+            app.swipeDown()
+        }
     }
 }
 ```
 
-Set performance baselines in Xcode to automatically flag regressions in CI.
+`XCUIApplication` and its gestures are main-actor isolated, hence `@MainActor`
+on the test method. Set a baseline for each measurement in Xcode's test report; later runs that
+exceed it fail, so CI flags the regression without anyone reading traces.