1# Recording an Instruments Trace
2 
3Use this reference when the user asks to record a new trace — either to
4attach to a running app, launch one fresh, or capture a specific session
5of actions they'll perform interactively.
6 
7The bundled `scripts/record_trace.py` wraps `xctrace record` with:
8 
9- The **SwiftUI** template by default (override with `--template`).
10- **Manual stop** via Ctrl+C, a stop-file, or `--time-limit`.
11- JSON discovery for devices and templates.
12- Normal Python exit codes so an agent can orchestrate.
13 
14## Typical flows
15 
16### A) Attach to a running app on a connected device
17 
18```bash
19python3 "${SKILL_DIR}/scripts/record_trace.py" \
20  --device "Pol's iPhone" \
21  --attach "Helm" \
22  --output ~/Desktop/helm-session.trace
23```
24 
25Leave it running while the user exercises the app. Stop with **Ctrl+C**.
26 
27### B) Launch an app and record from the first frame
28 
29```bash
30python3 "${SKILL_DIR}/scripts/record_trace.py" \
31  --device "<UDID>" \
32  --launch "/path/to/App.app" \
33  --output ~/Desktop/launch.trace
34```
35 
36Useful for diagnosing cold-start hitches and view-creation cost.
37 
38### C) Agent-driven: start in background, stop via stop-file
39 
40When you (the agent) are running non-interactively — e.g. via
41`Bash run_in_background` — use a stop-file so you can signal the
42recording to end cleanly:
43 
44```bash
45# Start recording (background)
46python3 "${SKILL_DIR}/scripts/record_trace.py" \
47  --attach Helm --stop-file /tmp/stop-trace \
48  --output ~/Desktop/session.trace
49 
50# ...user does their thing...
51 
52# Stop cleanly (from another shell or tool call)
53touch /tmp/stop-trace
54```
55 
56The script polls every 0.5s for the stop-file, sends SIGINT to xctrace
57when it appears, and waits up to 60s for the trace to finalise.
58 
59### D) Time-boxed recording
60 
61```bash
62python3 "${SKILL_DIR}/scripts/record_trace.py" \
63  --attach Helm --time-limit 30s --output ~/Desktop/30s.trace
64```
65 
66xctrace stops itself at the limit.
67 
68## Discovery helpers
69 
70```bash
71# List every connected device, simulator, and the host — JSON.
72python3 "${SKILL_DIR}/scripts/record_trace.py" --list-devices
73 
74# List all Instruments templates — JSON with a flat list + by-section map.
75python3 "${SKILL_DIR}/scripts/record_trace.py" --list-templates
76```
77 
78Device entries have `kind` (`devices`, `devices offline`, `simulators`),
79`name`, `os`, `udid`. Offline devices are known but unplugged / unpaired —
80plug them in before recording.
81 
82## Picking a template
83 
84> **Hard rule: the `SwiftUI` template only populates the SwiftUI lane on a
85> real device — a physical iOS/iPadOS device or the host Mac. On the iOS
86> Simulator it records but the SwiftUI lane comes back empty.** If the
87> chosen UDID falls under the `simulators` kind from `--list-devices`,
88> switch to `Time Profiler`. It still gives you Time Profiler + Hangs +
89> Animation Hitches, which `analyze_trace.py` analyses and correlates
90> normally; only the `swiftui` lane will report `available: false`.
91 
92Decision flow:
93 
94| Target                                       | Template to pass     |
95|----------------------------------------------|----------------------|
96| Physical iOS/iPadOS device (connected)       | `SwiftUI` (default)  |
97| Host Mac (macOS app, `--all-processes`, etc.)| `SwiftUI` (default)  |
98| iOS / iPadOS / watchOS / tvOS Simulator      | `Time Profiler`      |
99 
100Always confirm the target kind with `--list-devices` before starting a
101recording: entries under `simulators` mean you must switch to Time
102Profiler; entries under `devices` (both connected devices and the host
103Mac) support the SwiftUI template. Entries under `devices offline` need
104the user to connect/unlock/trust the device before recording.
105 
106For ad-hoc hang hunting on any target, `Time Profiler` or
107`Animation Hitches` alone may be enough.
108 
109## Chaining into analysis
110 
111The recording script prints `trace written: <path>` on exit. Feed that
112path straight into `analyze_trace.py`:
113 
114```bash
115TRACE=$(python3 "${SKILL_DIR}/scripts/record_trace.py" \
116    --attach Helm --stop-file /tmp/stop-trace --output ~/Desktop/session.trace \
117    2>&1 | awk '/trace written:/ {print $NF}')
118python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace "$TRACE" --json-only
119```
120 
121If the user wanted a specific scope, combine with `--list-logs` /
122`--list-signposts` / `--window` from `references/trace-analysis.md`.
123 
124## Failure modes to handle
125 
126- **Device offline** — `--list-devices` shows it in `devices offline`.
127  Ask the user to connect/unlock the device and retry.
128- **Output path exists** — the script refuses to overwrite. Either pick
129  a new `--output` or delete the existing bundle.
130- **App not running (for `--attach`)** — xctrace exits with an error;
131  fall back to `--launch` or tell the user to open the app first.
132- **Signing / trust on device** — iOS requires a development build
133  signed with the user's team. If xctrace returns a signing error, point
134  the user to trust the developer profile on the device.
135