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