1#!/usr/bin/env python3
2"""Record an Xcode Instruments .trace file via `xctrace record`.
3 
4Three modes:
5  (default)          Start a recording. Stops on Ctrl+C, stop-file, or time limit.
6  --list-devices     Enumerate connected devices + simulators as JSON.
7  --list-templates   Enumerate available Instruments templates as JSON.
8 
9Attach vs launch vs all-processes is mutually exclusive and passed straight
10through to xctrace. The default template is "SwiftUI" (matches the
11SwiftUI template in Xcode 26+ — change with --template).
12 
13Manual stop options, most to least automated:
14  * Send SIGINT (Ctrl+C) to this script — forwarded to xctrace, which
15    finalises the trace before exiting.
16  * Pass --stop-file PATH; when that file appears on disk, this script
17    sends SIGINT to xctrace. Useful for `Bash run_in_background`
18    workflows where there's no interactive terminal.
19  * Pass --time-limit 30s / 5m / etc. — xctrace stops itself.
20"""
21from __future__ import annotations
22 
23import argparse
24import json
25import os
26import re
27import signal
28import subprocess
29import sys
30import time
31from datetime import datetime
32from pathlib import Path
33 
34 
35def main(argv: list[str] | None = None) -> int:
36    parser = argparse.ArgumentParser(description="Record an Instruments .trace file.")
37    list_mode = parser.add_mutually_exclusive_group()
38    list_mode.add_argument("--list-devices", action="store_true",
39                           help="List devices and simulators as JSON, then exit.")
40    list_mode.add_argument("--list-templates", action="store_true",
41                           help="List template names as JSON, then exit.")
42 
43    parser.add_argument("--template", default="SwiftUI",
44                        help="Template name (default: SwiftUI).")
45    parser.add_argument("--device", default=None,
46                        help="Device name or UDID. Defaults to the host.")
47    parser.add_argument("--output", type=Path, default=None,
48                        help="Output .trace path. Defaults to ./<template>-<timestamp>.trace.")
49    parser.add_argument("--time-limit", default=None,
50                        help="Cap recording duration (e.g. 30s, 5m, 1h). Optional.")
51    parser.add_argument("--stop-file", type=Path, default=None,
52                        help="When this path appears on disk, stop the recording.")
53    parser.add_argument("--env", action="append", default=[],
54                        metavar="KEY=VALUE",
55                        help="Env var for the launched process. Can repeat. Launch mode only.")
56    parser.add_argument("--instrument", action="append", default=[],
57                        help="Extra --instrument flag passthrough (can repeat).")
58    parser.add_argument("--run-name", default=None)
59 
60    target = parser.add_mutually_exclusive_group()
61    target.add_argument("--launch", metavar="APP",
62                        help="Launch this .app path and record it.")
63    target.add_argument("--attach", metavar="PID_OR_NAME",
64                        help="Attach to a running process by pid or name.")
65    target.add_argument("--all-processes", action="store_true",
66                        help="Record every process (system-wide).")
67 
68    args = parser.parse_args(argv)
69 
70    if args.list_devices:
71        _print_devices()
72        return 0
73    if args.list_templates:
74        _print_templates()
75        return 0
76 
77    if not (args.launch or args.attach or args.all_processes):
78        print("error: need one of --launch, --attach, or --all-processes.",
79              file=sys.stderr)
80        return 2
81 
82    if args.env and not args.launch:
83        # xctrace silently ignores --env outside launch mode; surfacing this
84        # explicitly saves agents a confusing "why didn't my env var apply?".
85        print("error: --env only applies to --launch; remove it or switch target mode.",
86              file=sys.stderr)
87        return 2
88 
89    output = args.output or Path.cwd() / _default_trace_name(args.template)
90    if output.exists():
91        print(f"error: output already exists: {output}", file=sys.stderr)
92        return 2
93 
94    cmd = _build_xctrace_cmd(args, output)
95 
96    # Tell the user (and an agent reading stdout) what's happening + how to stop.
97    print("[record] starting xctrace record", flush=True)
98    print(f"[record]   template: {args.template}", flush=True)
99    print(f"[record]   device:   {args.device or '(host)'}", flush=True)
100    print(f"[record]   target:   {_describe_target(args)}", flush=True)
101    print(f"[record]   output:   {output}", flush=True)
102    stop_hints = ["Ctrl+C"]
103    if args.stop_file:
104        stop_hints.append(f"`touch {args.stop_file}`")
105    if args.time_limit:
106        stop_hints.append(f"after {args.time_limit}")
107    print(f"[record] stop via: {', '.join(stop_hints)}", flush=True)
108    print(f"[record] cmd: {' '.join(_shell_quote(c) for c in cmd)}", flush=True)
109 
110    # Start xctrace in its own process group so we can signal cleanly.
111    proc = subprocess.Popen(cmd, start_new_session=True)
112 
113    try:
114        _wait_with_stop(proc, args.stop_file)
115    except KeyboardInterrupt:
116        _forward_sigint(proc)
117 
118    # Give xctrace up to 60s to finalise after SIGINT — large traces take time.
119    try:
120        rc = proc.wait(timeout=60)
121    except subprocess.TimeoutExpired:
122        print("[record] xctrace did not exit within 60s after stop; killing.",
123              file=sys.stderr)
124        proc.kill()
125        rc = proc.wait()
126 
127    if output.exists():
128        print(f"[record] done. trace written: {output}", flush=True)
129    else:
130        print("[record] done but output file not found — did xctrace error?",
131              file=sys.stderr)
132        return rc or 1
133    return rc
134 
135 
136def _build_xctrace_cmd(args, output: Path) -> list[str]:
137    cmd = ["xctrace", "record", "--template", args.template, "--output", str(output)]
138    if args.device:
139        cmd += ["--device", args.device]
140    if args.time_limit:
141        cmd += ["--time-limit", args.time_limit]
142    if args.run_name:
143        cmd += ["--run-name", args.run_name]
144    for inst in args.instrument:
145        cmd += ["--instrument", inst]
146    for env in args.env:
147        cmd += ["--env", env]
148    # Target must come last — --launch consumes the remainder.
149    if args.attach:
150        cmd += ["--attach", args.attach]
151    elif args.all_processes:
152        cmd += ["--all-processes"]
153    elif args.launch:
154        cmd += ["--launch", "--", args.launch]
155    return cmd
156 
157 
158def _describe_target(args) -> str:
159    if args.launch:
160        return f"launch {args.launch}"
161    if args.attach:
162        return f"attach {args.attach}"
163    if args.all_processes:
164        return "all processes"
165    return "(none)"
166 
167 
168def _default_trace_name(template: str) -> str:
169    safe = re.sub(r"[^A-Za-z0-9]+", "-", template).strip("-").lower() or "trace"
170    ts = datetime.now().strftime("%Y%m%d-%H%M%S")
171    return f"{safe}-{ts}.trace"
172 
173 
174def _wait_with_stop(proc: subprocess.Popen, stop_file: Path | None) -> None:
175    """Poll until xctrace exits or stop_file appears; then send SIGINT."""
176    while True:
177        rc = proc.poll()
178        if rc is not None:
179            return
180        if stop_file and stop_file.exists():
181            print(f"[record] stop-file detected ({stop_file}); stopping xctrace.",
182                  flush=True)
183            _forward_sigint(proc)
184            return
185        time.sleep(0.5)
186 
187 
188def _forward_sigint(proc: subprocess.Popen) -> None:
189    try:
190        # Signal the whole group so child instruments tools also get SIGINT.
191        os.killpg(os.getpgid(proc.pid), signal.SIGINT)
192    except ProcessLookupError:
193        pass
194 
195 
196def _print_devices() -> None:
197    out = subprocess.run(
198        ["xctrace", "list", "devices"], capture_output=True, text=True, check=True
199    ).stdout
200    devices: list[dict] = []
201    section = None
202    # Device lines end with "(UDID)"; real iOS devices also have "(OS version)"
203    # before the UDID. The host (macOS) line has only "(UDID)".
204    line_re = re.compile(r"^(.+?)(?:\s+\(([^()]+)\))?\s+\(([0-9A-Fa-f-]{20,})\)\s*$")
205    for line in out.splitlines():
206        stripped = line.strip()
207        if not stripped:
208            continue
209        if stripped.startswith("==") and stripped.endswith("=="):
210            section = stripped.strip("= ").strip().lower()
211            continue
212        m = line_re.match(stripped)
213        if not m:
214            continue
215        name, os_ver, udid = m.group(1).strip(), m.group(2), m.group(3)
216        devices.append({
217            "kind": section or "unknown",
218            "name": name,
219            "os": os_ver,
220            "udid": udid,
221        })
222    print(json.dumps({"devices": devices}, indent=2))
223 
224 
225def _print_templates() -> None:
226    out = subprocess.run(
227        ["xctrace", "list", "templates"], capture_output=True, text=True, check=True
228    ).stdout
229    groups: dict[str, list[str]] = {}
230    section = "unknown"
231    for line in out.splitlines():
232        stripped = line.strip()
233        if not stripped:
234            continue
235        if stripped.startswith("==") and stripped.endswith("=="):
236            section = stripped.strip("= ").strip().lower()
237            groups.setdefault(section, [])
238            continue
239        groups.setdefault(section, []).append(stripped)
240    # Flat convenience list + structured by section.
241    flat = [name for items in groups.values() for name in items]
242    print(json.dumps({"templates": flat, "by_section": groups}, indent=2))
243 
244 
245def _shell_quote(s: str) -> str:
246    if re.match(r"^[A-Za-z0-9_./:=@-]+$", s):
247        return s
248    return "'" + s.replace("'", "'\\''") + "'"
249 
250 
251if __name__ == "__main__":
252    sys.exit(main())
253