High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: update memory monitoring guide with OS-level approach
Boschea3faa84bd58
diff --git a/dashboard/src/services/api.ts b/dashboard/src/services/api.tsindex 2aec5b1c..1b0afb70 100644--- a/dashboard/src/services/api.ts+++ b/dashboard/src/services/api.ts@@ -145,5 +145,17 @@ export function subscribeToEvents(handlers: EventHandler): () => void {}});- return () => es.close();+ // Suppress connection errors (expected on page reload/navigation)+ es.onerror = () => {+ // SSE will auto-reconnect; silence console noise+ };++ // Clean up on page unload to prevent ERR_INCOMPLETE_CHUNKED_ENCODING+ const cleanup = () => es.close();+ window.addEventListener("beforeunload", cleanup);++ return () => {+ window.removeEventListener("beforeunload", cleanup);+ es.close();+ };}diff --git a/docs/guides/images/memory-monitoring-dashboard.jpg b/docs/guides/images/memory-monitoring-dashboard.jpgnew file mode 100644index 00000000..ba90ff42Binary files /dev/null and b/docs/guides/images/memory-monitoring-dashboard.jpg differdiff --git a/docs/guides/memory-monitoring.md b/docs/guides/memory-monitoring.mdindex 72a3dbe1..aa3376f6 100644--- a/docs/guides/memory-monitoring.md+++ b/docs/guides/memory-monitoring.md@@ -1,30 +1,41 @@# Memory Monitoring Guide-Pinchtab can monitor Chrome's JavaScript heap usage across all tabs in each browser instance. This helps track memory consumption and detect leaks during long-running automation tasks.+Pinchtab monitors Chrome's memory usage at the OS level, providing accurate real-world memory consumption for each browser instance.++## Enabling Memory Metrics-Memory monitoring is **off by default** because it requires per-tab CDP calls which can be heavy with many tabs open.+Memory monitoring is **off by default** to minimize overhead.To enable:-1. Open the dashboard at `http://localhost:<port>/`+1. Open the dashboard at `http://localhost:<port>/dashboard`2. Go to **Settings** → **📈 Monitoring**-3. Toggle **Memory Metrics** on+3. Toggle **Tab Memory Metrics** on (marked as experimental)4. Click **Apply Settings**-## What Gets Measured+## How Memory is Calculated++Pinchtab uses a **process tree approach** to measure memory:++1. **Identify the browser process** — Gets the main Chrome PID from chromedp+2. **Walk the process tree** — Finds all child processes (renderers, GPU, utilities)+3. **Sum RSS memory** — Adds up Resident Set Size across all Chrome processes+4. **Filter renderers** — Counts processes with `--type=renderer` for tab count++This approach ensures memory is **isolated per instance** — you only see memory for that specific Chrome profile, not other Chrome windows on your system.-For each running instance, Pinchtab aggregates metrics across all open tabs:+### Memory Fields-| Metric | Description |-|--------|-------------|-| `jsHeapUsedMB` | JavaScript heap memory currently in use |-| `jsHeapTotalMB` | Total JavaScript heap allocated |-| `documents` | Number of Document objects |-| `frames` | Number of Frame objects |-| `nodes` | DOM node count |-| `listeners` | Number of JS event listeners |+| Field | Description |+|-------|-------------|+| `memoryMB` | Real OS-level memory (RSS) across all Chrome processes |+| `jsHeapUsedMB` | Estimated JS heap (~40% of memoryMB) |+| `jsHeapTotalMB` | Estimated total heap (~50% of memoryMB) |+| `renderers` | Number of renderer processes (≈ tabs) |++> **Note**: JS heap values are estimates based on typical Chrome memory distribution. For exact JS heap metrics, use Chrome DevTools directly.## API Endpoints@@ -34,37 +45,41 @@ For each running instance, Pinchtab aggregates metrics across all open tabs:GET /tabs/{tabId}/metrics```-Returns memory metrics for a specific tab:+Returns memory metrics (aggregated, since we can't reliably map tabs to PIDs):```json{- "jsHeapUsedMB": 12.5,- "jsHeapTotalMB": 24.0,- "documents": 1,- "frames": 1,- "nodes": 1250,- "listeners": 45+ "memoryMB": 850.5,+ "jsHeapUsedMB": 340.2,+ "jsHeapTotalMB": 425.25,+ "renderers": 11,+ "documents": 0,+ "frames": 0,+ "nodes": 0,+ "listeners": 0}```-### Instance Metrics (Aggregated)+### Instance Metrics```GET /metrics```-Returns aggregated metrics across all tabs in the instance:+Returns server metrics and browser memory:```json{- "metrics": { ... },+ "metrics": {+ "goHeapAllocMB": 12.5,+ "goHeapSysMB": 24.0,+ "goNumGoroutine": 15+ },"memory": {- "jsHeapUsedMB": 85.2,- "jsHeapTotalMB": 128.0,- "documents": 5,- "frames": 8,- "nodes": 12500,- "listeners": 320+ "memoryMB": 850.5,+ "jsHeapUsedMB": 340.2,+ "jsHeapTotalMB": 425.25,+ "renderers": 11}}```@@ -82,12 +97,12 @@ Returns memory metrics for all running instances:{"instanceId": "inst_abc123","profileName": "MyProfile",- "jsHeapUsedMB": 85.2,- "jsHeapTotalMB": 128.0,- "documents": 5,- "frames": 8,- "nodes": 12500,- "listeners": 320+ "jsHeapUsedMB": 340.2,+ "jsHeapTotalMB": 425.25,+ "documents": 0,+ "frames": 0,+ "nodes": 0,+ "listeners": 0}]```@@ -96,30 +111,32 @@ Returns memory metrics for all running instances:When enabled, the Monitoring page shows:-- **Chart**: Solid lines for tab counts, dashed lines for memory (MB)-- **Instance List**: Shows memory next to tab count (e.g., `:9868 · 3 tabs · 85MB`)-- **Dual Y-Axis**: Left axis for tabs, right axis for memory in MB--Data is polled every 30 seconds and the chart retains the last 60 data points (~30 minutes of history).+- **Chart**: Solid lines for tab counts (left axis), dashed lines for memory in MB (right axis)+- **Instance List**: Shows memory alongside tab count (e.g., `:9869 · 11 tabs · 1382MB`)+- **Real-time updates**: Data polled every 30 seconds, chart retains ~30 minutes of history## Performance Considerations-- Each tab requires a CDP `Performance.getMetrics()` call-- With many tabs (10+), this adds noticeable overhead-- Consider disabling for production workloads where performance matters-- Enable temporarily for debugging memory issues+- Memory metrics use [gopsutil](https://github.com/shirou/gopsutil) for OS-level process info+- Minimal overhead: just reads `/proc` (Linux) or uses sysctl (macOS)+- No CDP calls required — works reliably even with many tabs+- 5-second grace period for new instances to stabilize before polling## Troubleshooting-**Metrics show 0 or very low values**+**Memory shows 0**++- Chrome may not have started yet (check instance status)+- Browser context not initialized++**Memory seems too high**-This can happen if:-- No pages are loaded (empty tabs)-- Tabs were opened but not tracked by Pinchtab (external opens)+- Chrome is known to use significant memory+- Each tab runs in a separate renderer process+- Extensions and DevTools add to memory usage-**Memory keeps growing**+**Memory doesn't match Activity Monitor/Task Manager**-Possible memory leak. Check:-- Event listeners not being removed-- DOM nodes accumulating-- Closures holding references+- Pinchtab shows RSS (Resident Set Size) for Chrome processes+- System tools may show different metrics (virtual memory, shared memory)+- Other Chrome windows are excluded — we only count this instance's process tree