native-profiler-start
Begin native CPU, hang, and memory profiling on a booted iOS or Android device. Automatically detects the running app process. Returns recording status and trace file.
Instructions
Start native profiling on a booted device. iOS: Instruments via xctrace (CPU, hangs, memory). Android: Perfetto (CPU, jank, RSS-growth weak signal). Auto-detects the running app process unless app_process is explicitly provided. After starting, let the user interact with the app, then call native-profiler-stop. Use when you want to capture native CPU, hang, and memory data for a running app. Returns { status, pid, traceFile } confirming the recording has started. Fails if no app is running on the device, or the profiler cannot attach to the process.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | Yes | Target device id from `list-devices` (iOS UDID or Android serial). | |
| app_process | No | iOS: the CFBundleExecutable or display name of the app to profile. Android: the app's package name. If omitted, auto-detects the currently running foreground app. Only provide this if auto-detection picks the wrong app. | |
| template_path | No | iOS-only: path to an Instruments .tracetemplate file (defaults to bundled Argent template). Ignored on Android. | |
| malloc_stack_logging | No | iOS-only. When true, cold-launches the app under the profiler with Malloc Stack Logging enabled so memory leaks carry an allocation backtrace (responsible frame + library). Without it, leaks are still detected but unattributable — Instruments reports '<Call stack limit reached>'. Trade-offs: this RESTARTS the app (current state is lost), adds memory/CPU overhead, and makes the app noticeably slow to launch (every startup allocation records a backtrace), so leave it off for pure CPU/hang profiling. Requires a non-degraded Xcode: on Xcode 26.4 and later the cold-launch path is broken, so the call is rejected up front (re-run without the flag, or set ARGENT_IOS_CAPTURE=device to override if the device path works on your host). ARGENT_IOS_CAPTURE=all-processes — e.g. exported globally for the normal capture path — also rejects this flag up front, since that fallback cannot cold-launch; unset it (or set it to device) first. Ignored on Android. |