Ios ettrace profiler

Skill Xopoko/build-swift-apps/skills/ios-ettrace-profiler

Swift-focused AI agent skills for iOS and macOS: build, debug, simulator, SwiftUI, Xcode, App Store workflows. Part of Plug'n Skills.

Install

npx -y skills add Xopoko/build-swift-apps --skill ios-ettrace-profiler

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Capture and interpret symbolicated ETTrace profiles for iOS simulator startup, scrolling, navigation, rendering, runtime flows, before/after comparisons, and CPU hotspots.

SKILL.md

4.0 KB, as published. Nobody here has run it

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

Define one flow with clear start/stop points; avoid broad "use the app for a while" traces.
Build the exact simulator app.
Temporarily link ETTrace.xcframework into the app target, then remove it unless the user wants to keep it.
Collect UUID-matched app and first-party framework dSYMs.
Capture launch or runtime trace with a TTY.
Preserve fresh processed output_<thread>.json files immediately.
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.