shakacode
diff --git a/‎docs/oss/building-features/node-renderer/debugging.md‎
Lines changed: 24 additions & 8 deletions b/‎docs/oss/building-features/node-renderer/debugging.md‎
Lines changed: 24 additions & 8 deletions
diff --git a/‎docs/oss/building-features/performance-tracks-and-profiling.md‎
Lines changed: 93 additions & 0 deletions b/‎docs/oss/building-features/performance-tracks-and-profiling.md‎
Lines changed: 93 additions & 0 deletions
@@ -3,7 +3,9 @@
 > **Pro Feature** — Available with [React on Rails Pro](../../../pro/react-on-rails-pro.md).
 > Free or very low cost for startups and small companies. [Upgrade or licensing details →](../../../pro/upgrading-to-pro.md#try-pro-risk-free)
 
-Because the renderer communicates over a port to the server, you can start a renderer instance locally in your application and debug it.
+Because the renderer communicates over a port to Rails, you can start a local renderer instance with Node's inspector and debug the server-rendered JavaScript directly.
+
+Use this page for breakpoints, renderer logs, and memory snapshots. For CPU flamegraphs, use [Profiling Server-Side Rendering Code](../../../pro/profiling-server-side-rendering-code.md). For React 19.2 Performance Tracks, hydration traces, and choosing the right profiling tool, use [React Performance Tracks and Profiling](../performance-tracks-and-profiling.md).
 
 ## Monorepo Workflow
 
@@ -14,11 +16,22 @@ It is a `pnpm` workspace app and already points at the local packages in this mo
 
 ### Quick start: debugging with the full stack running
 
-If you already have the dummy app running via `bin/dev` (which uses `Procfile.dev`), the node renderer is listening on port 3800 but without `--inspect`. To attach a debugger you first need to restart it with `--inspect` — either stop the renderer process and run `pnpm run node-renderer:debug`, or temporarily add `--inspect` to the `node-renderer:` entry in `Procfile.dev` and `overmind restart node-renderer`. Then:
+If you already have the dummy app running via `bin/dev` (which uses `Procfile.dev`), the node renderer is listening on port 3800 without `--inspect`. To attach a debugger, restart only the renderer with the inspector enabled:
+
+```bash
+cd react_on_rails_pro/spec/dummy
+overmind stop node-renderer
+pnpm run node-renderer:debug
+```
+
+Keep that terminal open while you debug. Then:
 
 1. Open `chrome://inspect` in Chrome and connect to the renderer process.
-2. Use overmind to isolate renderer logs: `overmind connect node-renderer` (Ctrl-B to detach).
-3. After a code change, restart just the renderer: `overmind restart node-renderer`.
+2. Watch renderer logs in that terminal. Keep `bin/dev` visible for Rails logs.
+3. Set breakpoints in the inspector and reload the page that triggers SSR.
+4. After a server-bundle or renderer change, press Ctrl-C and rerun `pnpm run node-renderer:debug`.
+
+If you prefer to keep the renderer under Overmind, temporarily add `--inspect` to the `node-renderer:` entry in `Procfile.dev`, then run `overmind restart node-renderer`.
 
 ### Isolated debugging: manual per-terminal startup
 
@@ -52,6 +65,13 @@ Use this when you need full control over the renderer process — different flag
    ```
 1. If you are debugging an external app instead of the monorepo dummy app, refresh the installed renderer package using your local package workflow (for example `yalc`, `npm pack`, or a workspace link) before rerunning the renderer.
 
+### Breakpoints vs. profiles
+
+- Use `--inspect` breakpoints when you need to inspect props, globals, module state, or the exact branch taken during SSR.
+- Use [the SSR profiling guide](../../../pro/profiling-server-side-rendering-code.md) when the code is correct but slow.
+- Use [React Performance Tracks and Profiling](../performance-tracks-and-profiling.md) when the slow path includes browser hydration, Suspense, RSC timing, or client interactions.
+- Use [Error Reporting and Tracing](./error-reporting-and-tracing.md) or [OpenTelemetry](../../../pro/node-renderer.md#observability-with-opentelemetry) for production request spans.
+
 ## Debugging Memory Leaks
 
 If worker memory grows over time, use heap snapshots to find the source.
@@ -94,10 +114,6 @@ When diagnosing memory leaks in a containerized environment, running the Node re
 
 See the [Memory Leaks guide](../../../pro/js-memory-leaks.md) for common patterns and fixes.
 
-## Debugging using the Node debugger
-
-1. See [this article](https://github.com/shakacode/react_on_rails/issues/1196) on setting up the debugger.
-
 ## Debugging Jest tests
 
 1. See [the Jest documentation](https://jestjs.io/docs/troubleshooting) for overall guidance.
 
@@ -0,0 +1,93 @@
+# React Performance Tracks and Profiling
+
+React on Rails apps have three broad performance questions that look similar but need different tool clusters:
+
+1. **What did the browser do?** Use Chrome DevTools Performance recordings with [React Performance Tracks](https://react.dev/reference/dev-tools/react-performance-tracks).
+2. **What did the React on Rails Pro Node Renderer do?** Use the Node inspector and the renderer tracing integrations.
+3. **What did real users experience?** Use field metrics such as [Web Vitals and Real User Monitoring](./web-vitals-and-rum.md).
+
+React Performance Tracks are most useful when you can reproduce a slow interaction locally. They show React scheduler work, component render and effect durations, and, for React Server Components in development builds, server request and Server Component timing. They do not replace production telemetry, but they make the local trace much easier to read than a JavaScript stack alone.
+
+## Choose the right profiling path
+
+| Symptom                                              | Start with                                                                                                                                                     | Why                                                                                                                  |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Slow click, navigation, or hydration in the browser  | Chrome DevTools Performance recording with React Performance Tracks                                                                                            | Shows React scheduler priority, component render cost, effects, network, layout, and paint on one timeline.          |
+| A specific component renders too often               | React Components track, React DevTools, and optional `<Profiler>` boundaries                                                                                   | Shows component render/effect duration and, in development builds, prop changes for selected entries.                |
+| Slow server rendering in the Pro Node Renderer       | [Profiling Server-Side Rendering Code](../../pro/profiling-server-side-rendering-code.md)                                                                      | Attaches Chrome DevTools to the Node process and records CPU work such as bundle upload, VM setup, and render calls. |
+| Renderer breakpoints or request-by-request debugging | [Node Renderer Debugging](./node-renderer/debugging.md)                                                                                                        | Uses `--inspect`, renderer logs, and focused restarts for breakpoint debugging.                                      |
+| Production SSR latency or error correlation          | [Error Reporting and Tracing](./node-renderer/error-reporting-and-tracing.md) and [OpenTelemetry](../../pro/node-renderer.md#observability-with-opentelemetry) | Captures spans and errors from live requests without attaching an inspector to production traffic.                   |
+| Memory growth in the renderer                        | [Memory Leaks](../../pro/js-memory-leaks.md)                                                                                                                   | Uses heap snapshots and worker restart strategy instead of CPU flamegraphs.                                          |
+
+## Record React Performance Tracks
+
+Use this workflow for browser-side interaction, hydration, Suspense, and RSC timing investigations.
+
+1. Run the app in development with React 19.2 or newer when your app supports that React line. For React on Rails Pro RSC apps, keep the React version supported by the current RSC guide and release notes; do not upgrade a generated RSC app only to capture Performance Tracks.
+2. Install and enable the React Developer Tools browser extension when you want the Components track to include the full component tree.
+3. Open Chrome DevTools, then open the **Performance** panel.
+4. Start recording, reload the page or perform the slow interaction, then stop recording.
+5. Inspect the React tracks alongside the normal browser tracks for network, JavaScript, layout, paint, and user timing.
+
+React enables Performance Tracks automatically in development builds. In profiling builds, the Scheduler track is enabled by default. The Components track is limited to subtrees wrapped in `<Profiler>` unless the React DevTools extension is enabled. React's Server Components and Server Requests tracks are development-build only.
+
+## Read the React tracks
+
+The **Scheduler** track explains the priority and phase of React work:
+
+- **Blocking** work usually comes from direct user interactions.
+- **Transition** work comes from non-blocking updates scheduled with `startTransition`.
+- **Suspense** work shows fallback and reveal timing.
+- **Idle** work runs only after higher-priority work is clear.
+
+Within those lanes, look for update, render, commit, and remaining-effect spans. A render followed by repeated updates or long effects often points to avoidable state changes, expensive effects, or missing memoization boundaries.
+
+The **Components** track shows component render and effect durations as flamegraphs. Use it to answer:
+
+- Which component subtree is expensive?
+- Did the cost happen during render, layout effects, or passive effects?
+- Did a selected component receive changed props that explain the render?
+
+The **Server** tracks are relevant when you use React Server Components in development. The Server Requests track visualizes async work that flows into Server Components, and the Server Components tracks show the component work and awaited Promises. Treat these as React-level RSC timing: they do not include every Rails controller, Fastify, network, or renderer worker cost.
+
+## Keep names readable
+
+Profiles are only useful when component and function names survive the build.
+
+- Prefer named functions and named component exports over anonymous inline components.
+- Set `displayName` on components wrapped by helpers such as `memo` or `forwardRef` when the wrapper hides the useful name.
+- Use a development build first. It gives the clearest component names and enables the full React development instrumentation.
+- For a production-like profiling build, alias `react-dom/client` to `react-dom/profiling` at build time as described in the [React Performance Tracks docs](https://react.dev/reference/dev-tools/react-performance-tracks#using-profiling-builds), and preserve function/class names in that temporary build if minification erases useful labels. For Terser-style minifiers, that means profiling-only `keep_fnames` and `keep_classnames` settings or the equivalent setting in your bundler/minifier. Do not turn those knobs on blindly for production, since they can increase bundle size and reduce minification.
+
+## Correlate browser and server work
+
+For a local SSR/RSC investigation, collect one browser trace and one renderer trace for the same scenario:
+
+1. Record the browser interaction with React Performance Tracks.
+2. Record the renderer process with the [SSR profiling workflow](../../pro/profiling-server-side-rendering-code.md).
+3. Compare timestamps, request logs, and component names. The browser trace shows hydration, interaction, Suspense, and paint timing. The renderer trace shows CPU spent before HTML or RSC payloads reach the browser.
+
+If your server-rendered code needs its own named spans in a renderer CPU profile, add temporary User Timing marks around the code under investigation:
+
+```js
+performance.mark('ror:ssr:ProductSummary:start');
+try {
+  // Render or data preparation work under investigation.
+} finally {
+  performance.mark('ror:ssr:ProductSummary:end');
+  performance.measure('ror:ssr:ProductSummary', 'ror:ssr:ProductSummary:start', 'ror:ssr:ProductSummary:end');
+}
+```
+
+In the Pro Node Renderer VM, `performance` is available when `supportModules: true`; otherwise inject it with `additionalContext`. See [Runtime Globals for SSR and RSC](./node-renderer/js-configuration.md#runtime-globals-for-ssr-and-rsc).
+
+## Use production telemetry for production questions
+
+Do not attach `--inspect` to production traffic as your primary profiling strategy. It slows the renderer and changes the workload you are trying to measure.
+
+Use production-safe instrumentation instead:
+
+- [Web Vitals and RUM](./web-vitals-and-rum.md) for user-visible browser outcomes such as LCP, INP, CLS, FCP, and TTFB.
+- [OpenTelemetry](../../pro/node-renderer.md#observability-with-opentelemetry) for SSR request spans from the Pro Node Renderer.
+- [Error Reporting and Tracing](./node-renderer/error-reporting-and-tracing.md) for Sentry, Honeybadger, and custom tracing integrations.
+- [Profiling Server-Side Rendering Code](../../pro/profiling-server-side-rendering-code.md) for short, local CPU profiling sessions when you can reproduce the slow path.