/native-app-performance

name: native-app-performance
description: "Native app performance: xctrace, Time Profiler, traces, hotspots."

Native App Performance (CLI-only)

Goal: record Time Profiler via `xctrace`, extract samples, symbolicate, and propose hotspots without opening Instruments.

Quick start (CLI)

1) Record Time Profiler (attach):

# Start app yourself, then attach
xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --attach <pid>

2) Record Time Profiler (launch):

xcrun xctrace record --template 'Time Profiler' --time-limit 90s --output /tmp/App.trace --launch -- /path/App.app/Contents/MacOS/App

3) Extract time samples:

scripts/extract_time_samples.py --trace /tmp/App.trace --output /tmp/time-sample.xml

4) Get load address for symbolication:

# While app is running
vmmap <pid> | rg -m1 "__TEXT" -n

5) Symbolicate + rank hotspots:

scripts/top_hotspots.py --samples /tmp/time-sample.xml \
  --binary /path/App.app/Contents/MacOS/App \
  --load-address 0x100000000 --top 30

Workflow notes

• Always confirm you’re profiling the correct binary (local build vs /Applications). Prefer direct binary path for `--launch`.
• Ensure you trigger the slow path during capture (menu open/close, refresh, etc.).
• If stacks are empty, capture longer or avoid idle sections.
• `xcrun xctrace help record` and `xcrun xctrace help export` show correct flags.

Included scripts

• `scripts/record_time_profiler.sh`: record via attach or launch.
• `scripts/extract_time_samples.py`: export time-sample XML from a trace.
• `scripts/top_hotspots.py`: symbolicate and rank top app frames.

Gotchas

• ASLR means you must use the runtime `__TEXT` load address from `vmmap`.
• If using a new build, update the `--binary` path; symbols must match the trace.
• CLI-only flow: no need to open Instruments if stacks are symbolicated via `atos`.