playbooks

home / skills / steipete / agent-scripts / native-app-performance

native-app-performance skill

/skills/native-app-performance

This skill helps you profile native macOS/iOS apps using CLI xctrace workflows to record, extract samples, symbolicate, and identify hotspots.

npx playbooks add skill steipete/agent-scripts --skill native-app-performance

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.1 KB
---
name: native-app-performance
description: Native macOS/iOS app performance profiling via xctrace/Time Profiler and CLI-only analysis of Instruments traces. Use when asked to profile, attach, record, or analyze Instruments .trace files, find hotspots, or optimize native app performance without opening Instruments UI.
---

# 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):

```bash
# 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):

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

3) Extract time samples:

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

4) Get load address for symbolication:

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

5) Symbolicate + rank hotspots:

```bash
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`.

Overview

This skill profiles native macOS and iOS apps using xctrace and CLI-only analysis of Instruments .trace files. It records Time Profiler captures, extracts time samples, symbolicates stacks, and ranks hotspots so you can find performance bottlenecks without opening the Instruments UI. The toolset is implemented in TypeScript with helper scripts for fast, repeatable profiling runs.

How this skill works

The skill uses xcrun xctrace to record Time Profiler traces either by attaching to a running PID or by launching the app binary. It exports the trace to a time-sample XML, then uses the runtime __TEXT load address from vmmap and local binary symbols to symbolicate samples with atos. Finally, it aggregates and ranks frames to propose top hotspots and callsite candidates for optimization.

When to use it

  • When asked to profile or attach to a running macOS/iOS app to reproduce a performance issue.
  • To record a Time Profiler capture without opening the Instruments GUI.
  • When you need CLI-only symbolication and hotspot ranking from .trace files.
  • To verify whether a slow path is triggered during a user interaction or background task.
  • When you want repeatable automated profiling in scripts or CI environments.

Best practices

  • Confirm the traced binary exactly matches the build you launched; use the direct binary path for launch-mode captures.
  • Obtain the runtime __TEXT load address from vmmap for the target PID to counter ASLR before symbolication.
  • Trigger the slow behavior during capture and avoid long idle periods; increase capture duration if stacks are empty.
  • Prefer short, focused captures (30–120s) around the user action that exposes the issue.
  • Use xcrun xctrace help record and export to verify flags and templates for your Xcode version.

Example use cases

  • Attach to a production-like process to capture CPU hotspots during a sluggish UI refresh.
  • Launch a local build under Time Profiler to compare performance between releases.
  • Automate profiling in a CI job to collect hotspots for flaky performance regressions.
  • Analyze a .trace file from a tester or crash report and produce ranked hotspot suggestions.
  • Symbolicate samples for a remote debugging session where Instruments GUI is unavailable.

FAQ

What if stacks are unsymbolicated or empty?

Ensure the binary path matches the traced build and supply the runtime __TEXT load address from vmmap; capture longer or ensure active workload to avoid idle samples.

Can I use this without opening Instruments?

Yes. The workflow explicitly records, exports, and symbolicates traces via CLI tools like xctrace, vmmap, and atos so Instruments UI is not required.