Improve memory debugging docs with simpler heap snapshot approach (#3072)

## Summary

- Document `NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2"` as the
recommended approach for capturing heap snapshots — a built-in Node flag
that requires no code changes, versus the existing custom
`process.on('SIGUSR2', ...)` handler approach
- Add a step-by-step production container workflow for capturing
snapshots from running deployments and copying them locally for analysis
- Mention running the renderer as a separate workload for easier memory
isolation during diagnosis

Based on community discussion about practical memory debugging
approaches in production.

## Changed files

- `docs/pro/js-memory-leaks.md` — Split heap snapshot section into
recommended (built-in flag) and detailed (custom handler) options; add
production container workflow
- `docs/oss/building-features/node-renderer/debugging.md` — Rewrite
memory leaks section with simpler quick-start approach and isolation tip
- `docs/pro/troubleshooting.md` — Add heap snapshot flag as first
investigation step

## Test plan

- [x] All links pass lychee checks (verified by pre-commit and pre-push
hooks)
- [x] Prettier formatting passes
- [ ] Review rendered markdown for clarity

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: documentation-only updates that don’t change runtime
behavior, but could mislead users if commands/flags are incorrect.
> 
> **Overview**
> **Improves memory-leak debugging guidance for the Node Renderer** by
recommending Node’s built-in
`NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2"` workflow to capture
`.heapsnapshot` files without adding custom code.
> 
> Adds clearer instructions for capturing and comparing snapshots in
Chrome DevTools, documents a production container workflow (append to
existing `NODE_OPTIONS`, find worker PIDs, signal multiple workers, copy
snapshots out), and updates troubleshooting to point to this approach
first; also notes that running the renderer as a separate workload can
simplify isolation during diagnosis.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
1f1c725. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: justin808

docs/oss/building-features/node-renderer/debugging.md

@@ -54,17 +54,43 @@ Use this when you need full control over the renderer process — different flag
 
 ## Debugging Memory Leaks
 
-If worker memory grows over time, use heap snapshots to find the source:
+If worker memory grows over time, use heap snapshots to find the source.
 
-1. Start the renderer with `--expose-gc` to enable forced GC before snapshots:
-   ```bash
-   cd react_on_rails_pro/spec/dummy
-   # Adjust the port if your Rails app points at a different renderer URL.
-   RENDERER_PORT=3800 node --expose-gc client/node-renderer.js
-   ```
-2. Take heap snapshots at different times using `v8.writeHeapSnapshot()` (triggered via `SIGUSR2` signal or a custom endpoint).
-3. Load both snapshots in Chrome DevTools (Memory tab → Load) and use the **Comparison** view to see which objects accumulated between snapshots.
-4. Look for growing `string`, `Object`, and `Array` counts — these typically point to module-level caches.
+### Quick approach: `--heapsnapshot-signal` (no code changes)
+
+Use Node's built-in flag to write heap snapshots on demand:
+
+```bash
+cd react_on_rails_pro/spec/dummy
+# Adjust the port if your Rails app points at a different renderer URL.
+NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" RENDERER_PORT=3800 node client/node-renderer.js
+```
+
+Then capture snapshots at different times:
+
+```bash
+kill -USR2 <worker-pid>   # writes a .heapsnapshot file to the working directory
+```
+
+This also works in production containers — set `NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2"` as an environment variable, send the signal at different times, then copy the `.heapsnapshot` files to your local machine for analysis.
+
+### Detailed approach: with forced GC
+
+For more precise results, start the renderer with `--expose-gc` and a custom signal handler that forces garbage collection before each snapshot. See the [Memory Leaks guide](../../../pro/js-memory-leaks.md#2-take-v8-heap-snapshots) for the code.
+
+### Analyzing snapshots
+
+1. Load both `.heapsnapshot` files in Chrome DevTools (Memory tab → Load).
+2. Use the **Comparison** view to see which objects accumulated between snapshots.
+3. Look for growing `string`, `Object`, and `Array` counts — these typically point to module-level caches.
+
+### Isolating memory issues with a separate renderer workload
+
+When diagnosing memory leaks in a containerized environment, running the Node renderer as a separate workload (instead of a sidecar) makes it easier to:
+
+- Monitor Node memory independently from Rails
+- Capture heap snapshots without affecting the Rails process
+- Restart or scale the renderer without restarting Rails
 
 See the [Memory Leaks guide](../../../pro/js-memory-leaks.md) for common patterns and fixes.
 

docs/pro/js-memory-leaks.md

@@ -136,20 +136,50 @@ done
 
 ### 2. Take V8 heap snapshots
 
-Use `v8.writeHeapSnapshot()` to capture heap state before and after load, then compare in Chrome DevTools:
+#### Option A: Built-in `--heapsnapshot-signal` (recommended)
+
+Node provides a built-in flag that writes heap snapshots on a signal — no custom code required:
+
+```bash
+NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2" node node-renderer.js
+```
+
+Then send `kill -USR2 <worker-pid>` at different times to capture snapshots. Each signal writes a `.heapsnapshot` file to the working directory.
+
+This is the simplest approach, especially for production containers where you don't want to modify application code.
+
+#### Option B: Custom signal handler
+
+> **Note:** If you are already using Option A (`--heapsnapshot-signal=SIGUSR2`), do not also register a `process.on('SIGUSR2', ...)` handler — both will fire on every signal, producing duplicate snapshots. Remove one before using the other.
+
+If you need more control (e.g., forced GC before the snapshot, custom filenames, or writing to a specific directory), add a custom handler:
 
 ```javascript
-// In your renderer config, add a way to trigger snapshots:
 const v8 = require('v8');
 
 process.on('SIGUSR2', () => {
-  if (global.gc) global.gc(); // force GC first
+  if (global.gc) global.gc(); // force GC first (requires --expose-gc)
   const filename = v8.writeHeapSnapshot();
   console.log(`Heap snapshot written to ${filename}`);
 });
 ```
 
-Then send `kill -USR2 <worker-pid>` at different times and compare the snapshots in Chrome DevTools (Memory tab → Load).
+Then send `kill -USR2 <worker-pid>` at different times.
+
+#### Comparing snapshots
+
+Load both `.heapsnapshot` files in Chrome DevTools (Memory tab → Load) and use the **Comparison** view to see which objects accumulated between snapshots.
+
+#### Production container workflow
+
+To diagnose leaks in a running container:
+
+1. Set `NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2"` in the container environment. If `NODE_OPTIONS` is already set (e.g., `--max-old-space-size=1536`), append the flag: `NODE_OPTIONS="--max-old-space-size=1536 --heapsnapshot-signal=SIGUSR2"`.
+2. Identify the worker PIDs: `ps aux | grep node` inside the container. In a multi-worker setup you'll see one PID per worker — signal each one separately to get a snapshot from each process.
+3. Capture a baseline snapshot: `kill -USR2 <worker-pid>`.
+4. Wait for traffic to accumulate (e.g., 10–30 minutes), then capture another: `kill -USR2 <worker-pid>`.
+5. Copy the `.heapsnapshot` files from the container to your local machine (e.g., `kubectl cp`, `docker cp`, or `cpln workload exec`).
+6. Compare the two snapshots in Chrome DevTools to identify what grew between them.
 
 ### 3. Use `--inspect` for live profiling
 

docs/pro/troubleshooting.md

@@ -35,7 +35,8 @@ For issues related to upgrading from GitHub Packages to public distribution, see
 
 **Investigation**:
 
-- Profile memory using `node --inspect` and heap snapshots (see [Profiling guide](./profiling-server-side-rendering-code.md))
+- Capture heap snapshots with `NODE_OPTIONS="--heapsnapshot-signal=SIGUSR2"` — send `kill -USR2 <worker-pid>` at different times and compare in Chrome DevTools (see [Debugging guide](../oss/building-features/node-renderer/debugging.md#debugging-memory-leaks))
+- Profile memory using `node --inspect` and Chrome DevTools (see [Profiling guide](./profiling-server-side-rendering-code.md))
 - Search your server bundle code for module-level `Map`, `Set`, `{}` caches, and `_.memoize` calls — these are the most common leak sources
 - Use `config.ssr_pre_hook_js` to run cleanup code before each render (e.g., clearing global state)
 - See the [Memory Leaks guide](./js-memory-leaks.md) for detailed patterns, an audit checklist, and fixes