argent-native-profiler
starsforks
How to install argent-native-profiler?
software-mansion/argent/argent-native-profiler
$npx -y skills add software-mansion/argent --skill argent-native-profilerNative profiling for CPU hotspots, UI hangs, memory issues. iOS via xctrace; Android via Perfetto. Use when diagnosing native-level performance issues.
SKILL.md
| 1 | ## 1. Tools |
| 2 | |
| 3 | - `native-profiler-start` — start profiling on a booted device. iOS: xctrace recording for CPU, hangs, and leaks. |
| 4 | - `native-profiler-stop` — stop the profiler and export trace data to timestamped XML files. |
| 5 | - `native-profiler-analyze` — parse exported trace data and return a structured bottleneck payload. |
| 6 | - `profiler-stack-query` — drill into parsed data: hang stacks, function callers, thread breakdown, leak details. |
| 7 | - `profiler-load` — list and reload previous trace sessions from disk for re-investigation. |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## 2. Platform Support |
| 12 | |
| 13 | - **iOS**: Backend: Xcode Instruments via `xctrace` on a booted simulator or connected device. Requires Xcode command-line tools on PATH. Surfaces CPU hotspots, UI hangs, and memory leaks (instruments `Leaks` table). |
| 14 | - **Android**: Backend: Perfetto via `adb shell perfetto` + an in-process WASM trace-processor engine. Surfaces CPU hotspots and UI hangs, with per-hang jank reason codes, a main-thread state breakdown with `blocked_function` attribution, and a GC overlap annotation. Also reports an RSS-growth signal for memory pressure; treat it as a hint to confirm manually, not a confirmed leak. The target app must be debuggable or include `<profileable android:shell="true"/>` in its manifest for `perf_sample` callstacks to be captured. |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## 3. Investigation Patterns |
| 19 | |
| 20 | After `native-profiler-analyze` surfaces findings, use `profiler-stack-query` to drill into root causes: |
| 21 | |
| 22 | - **Hang detected** → `profiler-stack-query` mode=`hang_stacks` for full native call chains → mode=`function_callers` for the suspected function → read native source. |
| 23 | - **CPU hotspot** → `profiler-stack-query` mode=`thread_breakdown` for per-thread distribution → mode=`function_callers` for the dominant function. |
| 24 | - **Memory leak** → `profiler-stack-query` mode=`leak_stacks` filtered by `object_type` for responsible frames and libraries. |
| 25 | - iOS: if leaks come back unattributed (responsible frame `<Call stack limit reached>`), re-run `native-profiler-start` with `malloc_stack_logging: true`. This cold-launches the app with Malloc Stack Logging so leaks carry a real allocation backtrace (responsible frame + library). It restarts the app and adds overhead, so use it only when you need leak attribution — not for CPU/hang passes. |
| 26 | |
| 27 | After presenting findings, ask the user whether to investigate further, implement fixes, or stop. After applying fixes, always re-profile the same scenario and compare with `profiler-load`. Report honestly whether the target metric improved, regressed, or stayed flat. If the fix showed no net benefit or introduced regressions elsewhere, say so and reconsider. |
| 28 | |
| 29 | **Tip:** For reproducible before/after comparisons, record the interaction sequence as a flow using the `argent-create-flow` skill before the first profiling run. Replay with `flow-execute` on subsequent runs to eliminate interaction variance. |
| 30 | |
| 31 | > **Note:** The `argent-react-native-profiler` instructs to start native profiling automatically alongside React profiling. This skill's workflow and investigation patterns apply in both cases. |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## 4. Workflow |
| 36 | |
| 37 | **Complete all steps in order — do not break mid-flow.** |
| 38 | |
| 39 | ### Step 0: Ensure the target app is running |
| 40 | |
| 41 | The `native-profiler-start` tool **auto-detects** the running app on the device. |
| 42 | You do not need to derive `app_process` manually — just make sure the app is launched. |
| 43 | |
| 44 | 1. If the app is already running on the device, skip to Step 1 (do not pass `app_process`). |
| 45 | 2. If the app is not running, use `launch-app` with the correct bundle ID first. |
| 46 | 3. Only pass `app_process` explicitly if the tool reports multiple running user apps and you need to disambiguate. |
| 47 | |
| 48 | > **Note**: If multiple build flavors are installed (dev, staging, prod), the tool will detect whichever one is currently running. If both are running, it will ask you to specify. |
| 49 | |
| 50 | ### Step 1: Start recording |
| 51 | |
| 52 | Call `native-profiler-start` with `device_id` (iOS UDID or Android serial). The tool auto-detects the running app and saves the trace to `/tmp/argent-profiler-cwd/` with a timestamped filename. |
| 53 | Let the user interact with the app or drive interaction via simulator tools (see `argent-device-interact` skill). |
| 54 | |
| 55 | ### Step 2: Stop and export |
| 56 | |
| 57 | Call `native-profiler-stop` with `device_id`. iOS sends SIGINT to xctrace, waits for trace packaging, and exports CPU, hangs, and leaks data to XML — check `exportDiagnostics` for any export warnings. Android sends SIGTERM to the on-device perfetto daemon, polls `/proc/<pid>` until it exits, then `adb pull`s the `.pftrace` to the host. |
| 58 | |
| 59 | ### Step 3: Analyze |
| 60 | |
| 61 | Call `native-profiler-analyze` with `device_id`. Returns a markdown report with bottlenecks categorized as CPU hotspots, UI hangs, or memory leaks, sorted by severity. |
| 62 | |
| 63 | ### Step 4: Present findings and ask about next step |
People who liked this also viewed
6 picksType
- azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026
- systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026
- safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026
- explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026
- minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026
- insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 2026
