사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/software-mansion/argent --skill argent-native-profiler시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
1. Tools and platforms
native-profiler-start→native-profiler-stop→native-profiler-analyze: record, export, and report.profiler-stack-query: drill into the analyzed data (hang stacks, function callers, thread breakdown, leaks).profiler-load: reload an earlier session from disk.
iOS (Instruments via xctrace): simulator only; a physical iPhone is not supported. Needs full Xcode (xcrun xctrace version). Reports CPU hotspots, UI hangs and memory leaks.
Android (Perfetto): emulator or physical device. Reports CPU hotspots and UI hangs (with jank reasons and the main thread's blocking function), plus an RSS-growth signal for memory pressure: treat it as a hint to confirm, not a confirmed leak. The app must be debuggable or declare <profileable android:shell="true"/> in its manifest, or no perf_sample callstacks are captured.
For Mac apps (platform: "macos"), use Instruments with full Xcode. If start returns NATIVE_PROFILER_APP_NOT_DEBUGGABLE, use a development-signed build. In a background session such as SSH, template_path: "Time Profiler" also works for CPU and hangs on a signed build without the debugging entitlement. Do not sign files or add entitlements.
If native-profiler-start returns NATIVE_PROFILER_APP_HAS_WEBKIT_HEAP or NATIVE_PROFILER_APP_HEAP_CHECK_FAILED on a Mac app, choose the retry based on what you need to measure.
- For CPU and hangs, use
template_path: "Time Profiler"to keep the app running in its current state. - For leaks, use the bundled template with
malloc_stack_logging: true, even for allocations made during the recording. Save any state you need before retrying because this restarts the app.
While logging is off, avoid Leaks, Allocations, and other templates that use the Allocations instrument on these apps. They can freeze the app.
argent-react-native-profiler starts native profiling alongside React profiling by default; this skill's workflow and investigation patterns apply in both cases.
2. Workflow
Complete all steps in order; do not break mid-flow.
- Start. Launch the app through Argent if needed, then call
native-profiler-start. On iOS and Android, useapp_processif auto-detection is ambiguous or selects the wrong app. On a Mac, the device ID identifies the app. Then let the user interact, or followargent-device-interacton mobile andargent-macos-app-interacton Mac. During recording, usescreenshotordescribewhen needed because interaction tools omit the automatic screenshot and tree. Actions still wait for the screen to settle. On Android emulators, screenshots capture one frame in about 100 ms. On physical Android devices, they briefly wake screen capture and take about 150–200 ms, so use them sparingly. - Stop. Keep the app running through
native-profiler-stop. For Instruments, readwarningandexportDiagnosticsbefore interpreting the report. If the app ended, Instruments stalled, or exports were skipped, repeat the recording when you need the missing data. - Analyze.
native-profiler-analyze. Findings are 🔴 RED (act on it) or 🟡 YELLOW (worth investigating, may be acceptable). - Present and ask. Summarize the key findings, then ask the user whether to investigate further, implement fixes, or stop. Do not move on silently.
- Drill down with
profiler-stack-query(patterns below). - Fix and re-profile the same scenario; compare with the earlier session via
profiler-load(list, thenload_nativewith itssession_idand thedevice_id). Report honestly whether the target metric improved, regressed, or stayed flat; if there is no net benefit or something else regressed, say so and reconsider. For reproducible before/after runs, record the interaction as an e2e test (argent-create-e2eskill) before the first run and replay it withe2e-execute.
Investigation patterns
- Hang → mode
hang_stacksfor the native call chain →function_callersfor the suspected function → read the native source. If a Mac hang overlaps a leak-check pause, repeat the scenario withtemplate_path: "Time Profiler"to measure the hang without leak checks. - CPU hotspot →
thread_breakdownfor the per-thread split →function_callersfor the dominant function. - Memory leak (iOS simulator or Mac app). Keep recording about 25 seconds after the suspected leak so Instruments has time to finish a check. If the report warns that the capture was too short, repeat the recording before drawing conclusions about leaks. Use
leak_stackswithobject_typeto find allocation stacks. For missing stacks such as<Call stack limit reached>, save any needed app state and usemalloc_stack_logging: trueon a separate leak pass. On Mac, reserve it for allocations that predate recording and userestart-appto clear the overhead before measuring CPU or hangs.
3. Caveats
- Simulator and emulator timings reflect the host machine, not device hardware. Compare runs against each other rather than trusting absolute numbers; a physical Android device gives real-hardware numbers.
- Profiler overhead: if
JSLexer,JSONEmitteror Hermes internals dominate the JS thread, that is instrumentation cost, not app work. Discount those entries. - Run-to-run variance: treat only consistent, directional changes (across 2+ runs, or a >15% delta) as signal.
- Live data: if the app fetches live API data, different responses change the workload independently of code changes. Note when data-dependent screens vary.