Skip to content

Commit 278c0e8

Browse files
committed
docs: move CDP workflow to debugging guide
1 parent 4dfcf4d commit 278c0e8

3 files changed

Lines changed: 39 additions & 23 deletions

File tree

‎src/__tests__/cli-agent-cdp.test.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,21 @@ test('cdp wrapper pins agent-cdp package version', () => {
4040

4141
test('cdp docs hide the implementation package name', () => {
4242
assert.doesNotMatch(fs.readFileSync('website/docs/docs/commands.md', 'utf8'), /agent-cdp/);
43+
assert.doesNotMatch(
44+
fs.readFileSync('website/docs/docs/debugging-profiling.md', 'utf8'),
45+
/agent-cdp/,
46+
);
47+
});
48+
49+
test('cdp workflow docs live in debugging and profiling guide', () => {
50+
assert.doesNotMatch(
51+
fs.readFileSync('website/docs/docs/commands.md', 'utf8'),
52+
/React Native JS memory through CDP/,
53+
);
54+
assert.match(
55+
fs.readFileSync('website/docs/docs/debugging-profiling.md', 'utf8'),
56+
/React Native JS memory through CDP/,
57+
);
4358
});
4459

4560
test('cdp wrapper streams through npm exec and returns downstream exit code', async () => {

‎website/docs/docs/commands.md‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -680,28 +680,6 @@ agent-device perf trace stop --kind perfetto --out app.perfetto-trace
680680
- Interpretation note: this startup metric is command round-trip timing and does not represent true first frame / first interactive app instrumentation.
681681
- CPU data is a lightweight process snapshot, so an idle app may legitimately read as `0`.
682682

683-
## React Native JS memory through CDP
684-
685-
```bash
686-
agent-device cdp target list --url http://127.0.0.1:8081
687-
agent-device cdp target select <target-id>
688-
agent-device cdp memory usage sample --label baseline --gc
689-
agent-device cdp memory snapshot capture --name baseline --gc
690-
agent-device cdp memory snapshot diff --base ms_1 --compare ms_2 --limit 10
691-
agent-device cdp memory snapshot leak-triplet --baseline ms_1 --action ms_2 --cleanup ms_3 --limit 10
692-
agent-device cdp memory snapshot retainers --snapshot ms_3 --id <node-id> --depth 8 --limit 10
693-
```
694-
695-
- `cdp` dynamically runs a pinned CDP helper through npm; the first run may download the pinned package, and later runs can reuse the npm cache.
696-
- Every argument after `cdp` is passed to the CDP helper. Put `agent-device` global flags before `cdp` when you need the outer CLI to consume them.
697-
- Use it when a React Native or Expo app exposes a Metro CDP target and the task needs JavaScript heap usage, heap snapshots, allocation hotspots, retained-object diffs, retaining paths, or a small runtime eval to confirm JS state.
698-
- Start with `memory usage sample --gc` for a quick JS heap growth signal. Use snapshot diff and `leak-triplet` for proof that objects stayed retained after cleanup.
699-
- Until `cdp` has a compact leak report command, synthesize one from `memory usage diff`, `memory snapshot diff`, `memory snapshot leak-triplet`, and `memory snapshot retainers`.
700-
- Keep raw heap snapshots and allocation exports as artifacts. Default answers should summarize heap deltas, top retained classes/shapes, leak-triplet rows that stayed high after cleanup, and shortest useful retaining paths.
701-
- React Native/Hermes supports only part of browser CDP. If a method is unsupported, keep the selected target and fall back to heap usage samples plus heap snapshots.
702-
- Avoid `cdp profile cpu`, `trace`, `network`, and `console` by default because `agent-device` already has `perf cpu`, `trace`, `network`, `logs`, and `react-devtools` guidance for those areas.
703-
- Use `perf memory sample` and `perf memory snapshot` for native/process memory. Use `cdp` only for JavaScript heap evidence.
704-
705683
## React Native component internals
706684

707685
```bash

‎website/docs/docs/debugging-profiling.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,29 @@ React Native warning/error overlays belong to the app run. Treat them as finding
3939

4040
Use `alert wait`, `alert accept`, and `alert dismiss` for Android runtime permission prompts, Android native alerts, and iOS platform/app-owned modal dialogs. Do not use `settings permission` to answer a dialog already on screen. Reserve `settings permission` for setup or resetting permission state before a flow.
4141

42+
## React Native JS memory through CDP
43+
44+
Use `cdp` when a React Native or Expo app exposes a Metro CDP target and the task needs JavaScript heap usage, heap snapshots, allocation hotspots, retained-object diffs, retaining paths, or a small runtime eval to confirm JS state.
45+
46+
```bash
47+
agent-device cdp target list --url http://127.0.0.1:8081
48+
agent-device cdp target select <target-id>
49+
agent-device cdp memory usage sample --label baseline --gc
50+
agent-device cdp memory snapshot capture --name baseline --gc
51+
agent-device cdp memory snapshot diff --base ms_1 --compare ms_2 --limit 10
52+
agent-device cdp memory snapshot leak-triplet --baseline ms_1 --action ms_2 --cleanup ms_3 --limit 10
53+
agent-device cdp memory snapshot retainers --snapshot ms_3 --id <node-id> --depth 8 --limit 10
54+
```
55+
56+
- `cdp` dynamically runs a pinned CDP helper through npm; the first run may download the pinned package, and later runs can reuse the npm cache.
57+
- Every argument after `cdp` is passed to the CDP helper. Put `agent-device` global flags before `cdp` when you need the outer CLI to consume them.
58+
- Start with `memory usage sample --gc` for a quick JS heap growth signal. Use snapshot diff and `leak-triplet` for proof that objects stayed retained after cleanup.
59+
- Until `cdp` has a compact leak report command, synthesize one from `memory usage diff`, `memory snapshot diff`, `memory snapshot leak-triplet`, and `memory snapshot retainers`.
60+
- Keep raw heap snapshots and allocation exports as artifacts. Default answers should summarize heap deltas, top retained classes/shapes, leak-triplet rows that stayed high after cleanup, and shortest useful retaining paths.
61+
- React Native/Hermes supports only part of browser CDP. If a method is unsupported, keep the selected target and fall back to heap usage samples plus heap snapshots.
62+
- Avoid `cdp profile cpu`, `trace`, `network`, and `console` by default because `agent-device` already has `perf cpu`, `trace`, `network`, `logs`, and `react-devtools` guidance for those areas.
63+
- Use `perf memory sample` and `perf memory snapshot` for native/process memory. Use `cdp` only for JavaScript heap evidence.
64+
4265
## Fast path
4366
4467
```bash
@@ -139,7 +162,7 @@ agent-device perf trace stop --kind perfetto --out app.perfetto-trace
139162
- `perf memory sample` returns a compact memory-only payload, preserving the memory metric source used by `perf metrics`. Prefer it over raw `dumpsys`/`leaks` output for first-pass agent diagnosis because it keeps arrays bounded, reports top offenders compactly, and omits unrelated startup/CPU/frame data.
140163
- Example sample shape: `{"metrics":{"memory":{"available":true,"totalPssKb":562958,"totalRssKb":570304,"topConsumers":[{"name":"Dalvik Heap","pssKb":213456}]}}}`.
141164
- `perf memory snapshot` escalates to file artifacts. Android supports Java HPROF capture for active app processes when the build/device allows heap dumping. iOS simulator and macOS app sessions support memgraph capture through host-visible process tooling; physical iOS device memgraph capture reports unavailable with a hint instead of pretending support.
142-
- For React Native JavaScript heap leaks, use `agent-device cdp` against the Metro CDP target instead of native/process memory samples. Start with `memory usage sample --gc`, then confirm retained objects with `memory snapshot diff`, `memory snapshot leak-triplet`, and `memory snapshot retainers`.
165+
- For React Native JavaScript heap leaks, use `agent-device cdp` against the Metro CDP target instead of native/process memory samples; see the CDP section above.
143166
- Heap and memgraph artifacts are returned as paths plus compact metadata. Example default output: `Memory artifact (android-hprof): /tmp/app.hprof (42MB)`. They are not printed or embedded in JSON by default. heapprofd/native allocation tracing is deferred until Perfetto plumbing is available.
144167
- `perf cpu profile ... --kind xctrace` and `perf trace ... --kind xctrace` collect Apple native `.trace` artifacts for iOS/macOS app sessions and return only artifact paths plus compact metadata.
145168
- Android native profiling uses `perf cpu profile ... --kind simpleperf`; Android native trace capture uses `perf trace ... --kind perfetto`. These commands require an active Android app session and return artifact paths/summaries instead of dumping profile or trace contents.

0 commit comments

Comments
 (0)