ios-ettrace-profiler

name	ios-ettrace-profiler
description	Capture and interpret symbolicated ETTrace profiles for iOS simulator startup, scrolling, navigation, rendering, runtime flows, before/after comparisons, and CPU hotspots.

iOS ETTrace Profiler

Capture one focused, symbolicated ETTrace profile from an iOS simulator app. Pair with ios-simulator-debugger for build/install/launch/UI/log work.

Workflow

1. Define one flow with clear start/stop points; avoid broad "use the app for a while" traces.
2. Build the exact simulator app.
3. Temporarily link ETTrace.xcframework into the app target, then remove it unless the user wants to keep it.
4. Collect UUID-matched app and first-party framework dSYMs.
5. Capture launch or runtime trace with a TTY.
6. Preserve fresh processed output_<thread>.json files immediately.
7. Analyze processed JSON only; report artifacts, hotspots, symbols, and caveats.

Setup

RUN_DIR="${RUN_DIR:-$(mktemp -d "${TMPDIR:-/tmp}/codex-ios-ettrace.XXXXXX")}"
mkdir -p "$RUN_DIR"
brew install emergetools/homebrew-tap/ettrace

The host runner is ettrace; the app must link an iOS Simulator ETTrace.xcframework. Expect ETTrace v1.1.0-style processed JSON with top-level nodes.

Prefer a repo-vendored simulator xcframework. Otherwise build one into RUN_DIR from EmergeTools/ETTrace using the runner-matching tag. Link the app target, not tests/resources/launcher targets. Confirm launch logs include Starting ETTrace. Profile one instrumented simulator app at a time because simulator mode uses a fixed localhost port.

Bazel: apple_dynamic_xcframework_import. Xcode: temporary Link Binary With Libraries / Embed Frameworks for the debug simulator build.

dSYM Gate

Do not interpret unsymbolicated traces.

SKILL_DIR="<absolute skill dir>"
APP="<built simulator App.app>"
DSYMS="$RUN_DIR/dsyms"
"$SKILL_DIR/scripts/collect_ios_dsyms.sh" \
  --app "$APP" --out-dir "$DSYMS" \
  --search-root "$(dirname "$APP")" --search-root "$PWD" \
  --extra-dsym "$RUN_DIR/ETTrace-iphonesimulator.xcarchive/dSYMs/ETTrace.framework.dSYM"

Add --require-framework <Name> for app-owned dynamic frameworks. Use --require-all-frameworks only when every embedded framework should have symbols. If required dSYMs are missing, rebuild that exact app with dSYM generation or add the right build output as a search root. Use dwarfdump --uuid when symbolication looks suspicious. Meaningful first-party "have library but no symbol" lines fail the trace; small system/ETTrace buckets are usually acceptable.

Capture

Run with a TTY and answer prompts with write_stdin.

cd "$RUN_DIR"
CAPTURE_MARKER="$RUN_DIR/.ettrace-capture-start"; : > "$CAPTURE_MARKER"
find "$RUN_DIR" -maxdepth 1 \( -name 'output.json' -o -name 'output_*.json' \) -delete
ettrace --simulator --launch --verbose --dsyms "$DSYMS"

For runtime flow, omit --launch:

cd "$RUN_DIR"
CAPTURE_MARKER="$RUN_DIR/.ettrace-capture-start"; : > "$CAPTURE_MARKER"
find "$RUN_DIR" -maxdepth 1 \( -name 'output.json' -o -name 'output_*.json' \) -delete
ettrace --simulator --verbose --dsyms "$DSYMS"

Use --launch only for startup/first render. For first launch after install, set ETTraceRunAtStartup=YES, run ettrace --simulator, then launch from the home screen. Add --multi-thread only when needed.

Preserve And Report

PRESERVED_DIR="$(mktemp -d "$RUN_DIR/run-$(date +%Y%m%d-%H%M%S).XXXXXX")"
: > "$PRESERVED_DIR/summary.txt"
find "$RUN_DIR" -maxdepth 1 -name 'output_*.json' -newer "$CAPTURE_MARKER" -print | while read -r json; do
  cp "$json" "$PRESERVED_DIR/${json##*/}"
  python3 "$SKILL_DIR/scripts/analyze_flamegraph_json.py" "$PRESERVED_DIR/${json##*/}" >> "$PRESERVED_DIR/summary.txt"
done
test -s "$PRESERVED_DIR/summary.txt"

Do not analyze output.json or raw emerge-output/output.json. Report flow, build, simulator/runtime, run count, preserved JSON paths, top active leaves/inclusive first-party stacks, symbolication completeness, caveats, and comparable before/after deltas.