# Argent Native Profiler

> Perfilado nativo para detectar cuellos de botella de CPU, bloqueos de UI y problemas de memoria. En iOS usa xctrace y en Android usa Perfetto. Úsalo para diagnosticar problemas de rendimiento a nivel nativo.

Fuente: https://skillsagentes.com/skills/software-mansion/argent/argent-native-profiler
Markdown: https://skillsagentes.com/skills/software-mansion/argent/argent-native-profiler.md

Repositorio: https://github.com/software-mansion/argent
Autor: software-mansion
Licencia: Apache-2.0
Actualizado: el mes pasado
Coste de contexto: 38 tok instalada, 2k tok al activarse, 2k tok con todos los archivos del bundle
Bundle: 1 archivo, 8 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add software-mansion/argent --skill argent-native-profiler --agent claude-code
# Cursor
npx -y skills add software-mansion/argent --skill argent-native-profiler --agent cursor
# Codex
npx -y skills add software-mansion/argent --skill argent-native-profiler --agent codex
# Gemini CLI
npx -y skills add software-mansion/argent --skill argent-native-profiler --agent gemini
# Windsurf
npx -y skills add software-mansion/argent --skill argent-native-profiler --agent windsurf
# Cline
npx -y skills add software-mansion/argent --skill argent-native-profiler --agent cline
```

## Qué hace

- Graba una sesión de perfilado en el dispositivo (xctrace en iOS, Perfetto en Android) y exporta los datos a XML
- Analiza el trace y devuelve un informe estructurado de cuellos de botella, clasificados por severidad (RED/YELLOW)
- Permite investigar en detalle: pilas de bloqueos, funciones que más llaman, desglose por hilo o fugas de memoria
- Recarga sesiones de trace anteriores desde disco para volver a investigarlas
- En iOS puede activar malloc stack logging para atribuir fugas de memoria a una pila de asignación real

## Cuándo usarla

- Hay que diagnosticar problemas de rendimiento a nivel nativo: cuellos de botella de CPU, bloqueos de UI o fugas de memoria

## Qué la activa

- "Perfila la app para encontrar por qué se congela la UI"
- "Busca fugas de memoria en la app en iOS"
- "Analiza los cuellos de botella de CPU en Android"

## Antes de instalar

- En iOS necesita las herramientas de línea de comandos de Xcode (xctrace) en el PATH; en Android la app debe ser debuggable o incluir profileable android:shell="true" en el manifiesto.

## Archivos

- SKILL.md — 8 KB

## SKILL.md

Reproducido tal cual desde software-mansion/argent bajo Apache-2.0. Esta sección es el documento original y está en inglés.

## 1. Tools

- `native-profiler-start` — start profiling on a booted device. iOS: xctrace recording for CPU, hangs, and leaks.
- `native-profiler-stop` — stop the profiler and export trace data to timestamped XML files.
- `native-profiler-analyze` — parse exported trace data and return a structured bottleneck payload.
- `profiler-stack-query` — drill into parsed data: hang stacks, function callers, thread breakdown, leak details.
- `profiler-load` — list and reload previous trace sessions from disk for re-investigation.

---

## 2. Platform Support

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

---

## 3. Investigation Patterns

After `native-profiler-analyze` surfaces findings, use `profiler-stack-query` to drill into root causes:

- **Hang detected** → `profiler-stack-query` mode=`hang_stacks` for full native call chains → mode=`function_callers` for the suspected function → read native source.
- **CPU hotspot** → `profiler-stack-query` mode=`thread_breakdown` for per-thread distribution → mode=`function_callers` for the dominant function.
- **Memory leak** → `profiler-stack-query` mode=`leak_stacks` filtered by `object_type` for responsible frames and libraries.
  - 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.

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.

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

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

---

## 4. Workflow

**Complete all steps in order — do not break mid-flow.**

### Step 0: Ensure the target app is running

The `native-profiler-start` tool **auto-detects** the running app on the device.
You do not need to derive `app_process` manually — just make sure the app is launched.

1. If the app is already running on the device, skip to Step 1 (do not pass `app_process`).
2. If the app is not running, use `launch-app` with the correct bundle ID first.
3. Only pass `app_process` explicitly if the tool reports multiple running user apps and you need to disambiguate.

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

### Step 1: Start recording

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.
Let the user interact with the app or drive interaction via simulator tools (see `argent-device-interact` skill).

### Step 2: Stop and export

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.

### Step 3: Analyze

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.

### Step 4: Present findings and ask about next steps

Present a concise summary of the key findings. Then follow the "After analysis" guideline — ask whether to investigate further with query tools, implement fixes, or stop.

### Step 5: Drill-down investigation

Use `profiler-stack-query` to investigate specific findings. See §3 Investigation Patterns for chaining guidance.

### Step 6: Reload previous sessions

To revisit a previous trace:

1. Call `profiler-load` mode=`list` to see available sessions.
2. Call `profiler-load` mode=`load_native` session_id=`<timestamp>` device_id=`<UDID>` to re-parse the XML files.
3. Use `profiler-stack-query` to investigate the reloaded data.

---

## 5. Understanding Results

Bottlenecks are categorized by severity:

- **RED**: CPU functions taking >15% of total time, all UI hangs, and **attributed** memory leaks (those with a resolved responsible frame). These require immediate attention.
- **YELLOW**: CPU functions taking 3-15% of total time, and **unattributed** memory leaks (`<Call stack limit reached>`, no library — see the memory-leaks caveat below). Worth investigating but may be acceptable.

Each bottleneck type indicates a different class of problem:

- **CPU hotspots**: Native functions consuming excessive CPU time. Look for tight loops, expensive computations, or redundant work.
- **UI hangs**: Main thread blocked long enough to cause visible jank or unresponsiveness. Often caused by synchronous I/O, heavy layout passes, or lock contention.
- **Memory leaks**: Objects allocated but never freed. Common causes include retain cycles, unclosed resources, or forgotten observers. Argent records via `xctrace --attach`, which has no malloc-stack history, so on the simulator most leaks come back **unattributed** (`<Call stack limit reached>`, no library) and are dominated by benign system allocations — these are reported as a low-confidence YELLOW summary, not confirmed RED leaks. For attributed stacks, capture with malloc stack logging enabled at launch.

---

## 6. Important Caveats

- **Simulator vs device**: Simulator profiling reflects host Mac performance, not real device hardware. Use device profiling for accurate CPU timings and memory behavior.
- **xctrace availability (iOS)**: Requires Xcode command-line tools installed. Verify with `xcrun xctrace version`.
- **Profiler overhead**: xctrace instrumentation adds CPU load. If `JSLexer`, `JSONEmitter`, or Hermes runtime internals dominate the JS thread in CPU hotspot results, those reflect profiler overhead — not app work. Discount those entries when evaluating findings.
- **Run-to-run variance**: Small fluctuations in CPU percentages between runs are normal. Treat only consistent directional changes (across 2+ runs or >15% delta) as actionable signal.
- **Live data variability**: If the app fetches live API data, different responses between runs change rendering workload independently of code changes. Note when data-dependent screens show variance.

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [software-mansion](https://skillsagentes.com/creators/software-mansion.md) — 0 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Argent Create Flow](https://skillsagentes.com/skills/software-mansion/argent/argent-create-flow.md): Crea, graba, edita, repite o repara flujos YAML reutilizables de Argent. Úsalo para grabar/repetir un recorrido de dispositivo, montar perfiles o comparaciones A/B, o antes de repetir tres o más interacciones.
- [Argent Device Interact](https://skillsagentes.com/skills/software-mansion/argent/argent-device-interact.md): Interactúa con un simulador iOS, un emulador Android o una app Chromium (CDP) con las herramientas MCP de argent: toques, gestos, scroll, texto, botones físicos, lanzar apps, abrir URLs, capturas y esperas de elementos.
- [Argent Test Ui Flow](https://skillsagentes.com/skills/software-mansion/argent/argent-test-ui-flow.md): Prueba de forma autónoma la interfaz de una app (iOS o Android) con bucles de interactuar-capturar-verificar usando las herramientas MCP de argent, para flujos de UI, login, navegación o pruebas end-to-end.
- [Argent Metro Debugger](https://skillsagentes.com/skills/software-mansion/argent/argent-metro-debugger.md): Depura un runtime JS vía CDP con las herramientas de debugger de argent. La vía principal es React Native por Metro (iOS/Android/Vega); un subconjunto también controla el renderer de una app Chromium (CDP).
- [Argent Qa Flows](https://skillsagentes.com/skills/software-mansion/argent/argent-qa-flows.md): Crea tests E2E de regresión QA reproducibles como flujos Argent a partir de casos de prueba, tickets o criterios de aceptación, con configuración determinista y dos pasadas consecutivas exitosas. Cubre iOS, Android, Chromium y Vega.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)