High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: report only measured browser-memory fields, dropping the derived heap pair and the four unpopulated counters (PIN-269)
Luigi Agostieea650d8b13d
diff --git a/dashboard/src/components/molecules/InstanceStats.tsx b/dashboard/src/components/molecules/InstanceStats.tsxindex 0bfc7e2f..cd7f7090 100644--- a/dashboard/src/components/molecules/InstanceStats.tsx+++ b/dashboard/src/components/molecules/InstanceStats.tsx@@ -81,11 +81,6 @@ function countUniqueDomains(tabs: InstanceTab[]): number {}export default function InstanceStats({ instance, metrics, tabs }: Props) {- const heapPct =- metrics && metrics.jsHeapTotalMB > 0- ? (metrics.jsHeapUsedMB / metrics.jsHeapTotalMB) * 100- : null;-const uniqueDomains = countUniqueDomains(tabs);return (@@ -103,27 +98,16 @@ export default function InstanceStats({ instance, metrics, tabs }: Props) {<StatGroup title="Browsing"><StatItem label="Tabs" value={fmt(tabs.length)} /><StatItem label="Domains" value={fmt(uniqueDomains)} />- {metrics && (- <>- <StatItem label="Documents" value={fmt(metrics.documents)} />- <StatItem label="Frames" value={fmt(metrics.frames)} />- </>- )}</StatGroup>{metrics && (<StatGroup title="Resources"><StatItem- label="Heap"- value={`${fmt(metrics.jsHeapUsedMB, 1)} MB`}- sub={- heapPct !== null- ? `${fmt(heapPct, 0)}% of ${fmt(metrics.jsHeapTotalMB, 1)} MB`- : undefined- }+ label="Memory"+ value={`${fmt(metrics.memoryMB, 1)} MB`}+ sub="RSS across the browser process tree"/>- <StatItem label="DOM Nodes" value={fmt(metrics.nodes)} />- <StatItem label="Listeners" value={fmt(metrics.listeners)} />+ <StatItem label="Renderers" value={fmt(metrics.renderers)} /></StatGroup>)}</div>diff --git a/dashboard/src/generated/types.ts b/dashboard/src/generated/types.tsindex 94b9da4b..0cf6f36b 100644--- a/dashboard/src/generated/types.ts+++ b/dashboard/src/generated/types.ts@@ -173,12 +173,8 @@ export interface InstanceTab {export interface InstanceMetrics {instanceId: string;profileName: string;- jsHeapUsedMB: number /* float64 */;- jsHeapTotalMB: number /* float64 */;- documents: number /* int64 */;- frames: number /* int64 */;- nodes: number /* int64 */;- listeners: number /* int64 */;+ memoryMB: number /* float64 */;+ renderers: number /* int */;}export interface LaunchInstanceRequest {profileId?: string; // profile ID (prof_XXXXXXXX) or existing profile namediff --git a/dashboard/src/pages/settings/DashboardSettingsSection.tsx b/dashboard/src/pages/settings/DashboardSettingsSection.tsxindex a08d2f25..aeaeb485 100644--- a/dashboard/src/pages/settings/DashboardSettingsSection.tsx+++ b/dashboard/src/pages/settings/DashboardSettingsSection.tsx@@ -94,7 +94,7 @@ export function DashboardSettingsSection({</SettingRow><SettingRowlabel="Memory metrics"- description="Enable per-tab heap collection in the dashboard. Useful for debugging, but heavier."+ description="Collect per-instance browser memory (RSS across the Chrome process tree) in the dashboard. Useful for debugging, but heavier."><label className="flex items-center justify-end gap-3 text-sm text-text-secondary"><inputdiff --git a/dashboard/src/stores/slices/monitoringSlice.ts b/dashboard/src/stores/slices/monitoringSlice.tsindex 19b5f32e..9300dd1c 100644--- a/dashboard/src/stores/slices/monitoringSlice.ts+++ b/dashboard/src/stores/slices/monitoringSlice.ts@@ -10,7 +10,7 @@ export interface TabDataPoint {export interface MemoryDataPoint {timestamp: number;- [instanceId: string]: number; // jsHeapUsedMB+ [instanceId: string]: number; // memoryMB}export interface ServerDataPoint {@@ -26,7 +26,7 @@ export interface MonitoringSlice {memoryChartData: MemoryDataPoint[];serverChartData: ServerDataPoint[];currentTabs: Record<string, InstanceTab[]>;- currentMemory: Record<string, number>; // instanceId -> jsHeapUsedMB+ currentMemory: Record<string, number>; // instanceId -> memoryMBcurrentMetrics: Record<string, InstanceMetrics>; // instanceId -> full metricsaddChartDataPoint: (point: TabDataPoint) => void;addMemoryDataPoint: (point: MemoryDataPoint) => void;@@ -104,8 +104,8 @@ export const createMonitoringSlice: StateCreator<if (includeMemory) {const metrics = metricsByInstance[instance.id];if (metrics) {- memDataPoint[instance.id] = metrics.jsHeapUsedMB;- currentMemory[instance.id] = metrics.jsHeapUsedMB;+ memDataPoint[instance.id] = metrics.memoryMB;+ currentMemory[instance.id] = metrics.memoryMB;currentMetrics[instance.id] = metrics;}}diff --git a/dashboard/src/stores/useAppStore.test.ts b/dashboard/src/stores/useAppStore.test.tsindex 4ba06baa..746b94ce 100644--- a/dashboard/src/stores/useAppStore.test.ts+++ b/dashboard/src/stores/useAppStore.test.ts@@ -376,9 +376,9 @@ describe("useAppStore", () => {{ id: "t4", instanceId: "C" },],metrics: [- { instanceId: "A", jsHeapUsedMB: 10 },- { instanceId: "A", jsHeapUsedMB: 99 }, // duplicate: first wins- { instanceId: "B", jsHeapUsedMB: 20 },+ { instanceId: "A", memoryMB: 10 },+ { instanceId: "A", memoryMB: 99 }, // duplicate: first wins+ { instanceId: "B", memoryMB: 20 },],serverMetrics: {goHeapAllocMB: 42,@@ -402,8 +402,8 @@ describe("useAppStore", () => {// First metrics entry wins for the duplicate (10, not 99).expect(s.currentMemory).toEqual({ A: 10, B: 20 });expect(s.currentMetrics).toEqual({- A: { instanceId: "A", jsHeapUsedMB: 10 },- B: { instanceId: "B", jsHeapUsedMB: 20 },+ A: { instanceId: "A", memoryMB: 10 },+ B: { instanceId: "B", memoryMB: 20 },});const tabData = s.tabsChartData;diff --git a/docs/guides/memory-monitoring.md b/docs/guides/memory-monitoring.mdindex 73bdb232..4a5d0b67 100644--- a/docs/guides/memory-monitoring.md+++ b/docs/guides/memory-monitoring.md@@ -18,14 +18,12 @@ This gives you real OS-level memory usage for that instance's Chrome process tre| Field | Meaning || --- | --- || `memoryMB` | Real RSS memory across the browser process tree |-| `jsHeapUsedMB` | Estimated value derived from `memoryMB` |-| `jsHeapTotalMB` | Estimated value derived from `memoryMB` || `renderers` | Number of renderer processes in the browser process tree |-| `documents`, `frames`, `nodes`, `listeners` | Legacy compatibility fields; currently not populated with live DOM counts |++Both fields are measured. Neither is derived from the other, and PinchTab reports no JavaScript-heap or DOM-count figures: there is no CDP collection behind these endpoints.Important limitation:-- `jsHeapUsedMB` and `jsHeapTotalMB` are estimates, not true per-tab DevTools heap measurements- `GET /tabs/{id}/metrics` returns the owning browser instance's aggregate memory, not isolated per-tab memory## Instance Metrics@@ -47,8 +45,6 @@ Example shape:},"memory": {"memoryMB": 850.5,- "jsHeapUsedMB": 340.2,- "jsHeapTotalMB": 425.25,"renderers": 11}}@@ -65,13 +61,7 @@ Example shape:```json{"memoryMB": 850.5,- "jsHeapUsedMB": 340.2,- "jsHeapTotalMB": 425.25,- "renderers": 11,- "documents": 0,- "frames": 0,- "nodes": 0,- "listeners": 0+ "renderers": 11}```@@ -85,7 +75,7 @@ In orchestrator mode:curl http://localhost:9867/instances/metrics```-This returns one metrics object per running instance, which is the best API for comparing memory across a fleet.+This returns one metrics object per running instance — `instanceId`, `profileName`, `memoryMB` and `renderers` — which is the best API for comparing memory across a fleet.## Dashboard Monitoringdiff --git a/internal/api/types/types.go b/internal/api/types/types.goindex 295d14ee..32475c58 100644--- a/internal/api/types/types.go+++ b/internal/api/types/types.go@@ -185,14 +185,10 @@ type InstanceTab struct {}type InstanceMetrics struct {- InstanceID string `json:"instanceId"`- ProfileName string `json:"profileName"`- JSHeapUsedMB float64 `json:"jsHeapUsedMB"`- JSHeapTotalMB float64 `json:"jsHeapTotalMB"`- Documents int64 `json:"documents"`- Frames int64 `json:"frames"`- Nodes int64 `json:"nodes"`- Listeners int64 `json:"listeners"`+ InstanceID string `json:"instanceId"`+ ProfileName string `json:"profileName"`+ MemoryMB float64 `json:"memoryMB"`+ Renderers int `json:"renderers"`}type LaunchInstanceRequest struct {diff --git a/internal/bridge/observe/metrics.go b/internal/bridge/observe/metrics.goindex 4b38007f..a3ce120f 100644--- a/internal/bridge/observe/metrics.go+++ b/internal/bridge/observe/metrics.go@@ -8,19 +8,16 @@ import ("github.com/shirou/gopsutil/v4/process")-// MemoryMetrics holds Chrome memory statistics.+// MemoryMetrics holds what PinchTab measures: RSS across the browser process+// tree and the renderer count. Every field is measured, never derived from+// another field in the same payload.type MemoryMetrics struct {- MemoryMB float64 `json:"memoryMB"`-- JSHeapUsedMB float64 `json:"jsHeapUsedMB"`- JSHeapTotalMB float64 `json:"jsHeapTotalMB"`-- Renderers int `json:"renderers"`+ MemoryMB float64 `json:"memoryMB"`+ Renderers int `json:"renderers"`+}- Documents int64 `json:"documents"`- Frames int64 `json:"frames"`- Nodes int64 `json:"nodes"`- Listeners int64 `json:"listeners"`+func newMemoryMetrics(totalBytes uint64, renderers int) *MemoryMetrics {+ return &MemoryMetrics{MemoryMB: float64(totalBytes) / (1024 * 1024), Renderers: renderers}}// GetAggregatedMemoryMetrics returns OS-level memory usage across the browser process tree.@@ -49,8 +46,7 @@ func GetAggregatedMemoryMetrics(browserCtx context.Context) (*MemoryMetrics, errchildren, err := p.Children()if err != nil {mem, _ := getProcessMemory(mainPID)- result.MemoryMB = float64(mem) / (1024 * 1024)- return result, nil+ return newMemoryMetrics(mem, 0), nil}var totalMem uint64@@ -68,12 +64,7 @@ func GetAggregatedMemoryMetrics(browserCtx context.Context) (*MemoryMetrics, errtotalMem += childMem}- result.MemoryMB = float64(totalMem) / (1024 * 1024)- result.Renderers = rendererCount- result.JSHeapUsedMB = result.MemoryMB * 0.4- result.JSHeapTotalMB = result.MemoryMB * 0.5-- return result, nil+ return newMemoryMetrics(totalMem, rendererCount), nil}func getProcessMemory(pid int32) (uint64, error) {diff --git a/internal/bridge/observe/metrics_test.go b/internal/bridge/observe/metrics_test.gonew file mode 100644index 00000000..ef6633b9--- /dev/null+++ b/internal/bridge/observe/metrics_test.go@@ -0,0 +1,69 @@+package observe++import (+ "encoding/json"+ "fmt"+ "math"+ "reflect"+ "testing"+)++func numericFields(t *testing.T, m *MemoryMetrics) map[string]float64 {+ t.Helper()++ raw, err := json.Marshal(m)+ if err != nil {+ t.Fatalf("marshal MemoryMetrics: %v", err)+ }+ var decoded map[string]any+ if err := json.Unmarshal(raw, &decoded); err != nil {+ t.Fatalf("unmarshal MemoryMetrics: %v", err)+ }++ values := map[string]float64{}+ for name, value := range decoded {+ number, ok := value.(float64)+ if !ok {+ t.Fatalf("field %q is %T, not a number; this walk would silently skip it", name, value)+ }+ values[name] = number+ }+ if len(values) < reflect.TypeOf(MemoryMetrics{}).NumField() {+ t.Fatalf("walked %d serialized fields for %d struct fields; a field this guard cannot see is a field it cannot police",+ len(values), reflect.TypeOf(MemoryMetrics{}).NumField())+ }+ return values+}++// The property the derived jsHeap fields violated: nothing a caller reads may be+// arithmetic on something else in the same payload. Two samples are the minimum+// that can say so — any single pair of numbers has a ratio.+func TestNoReportedFieldHoldsAConstantRatioToAnotherAcrossTwoSamples(t *testing.T) {+ const mb = 1024 * 1024+ low := numericFields(t, newMemoryMetrics(100*mb, 3))+ high := numericFields(t, newMemoryMetrics(250*mb, 4))++ for name := range low {+ for other := range low {+ if name == other || low[other] == 0 || high[other] == 0 {+ continue+ }+ lowRatio := low[name] / low[other]+ highRatio := high[name] / high[other]+ if math.Abs(lowRatio-highRatio) < 1e-9 {+ t.Errorf("%s/%s is %v in both samples; %s is derived from %s rather than measured, and a gauge built on the pair cannot move",+ name, other, lowRatio, name, other)+ }+ }+ }+}++func TestMemoryMetricsReportsMeasuredRSSAndRenderers(t *testing.T) {+ const mb = 1024 * 1024+ got := numericFields(t, newMemoryMetrics(250*mb, 4))++ want := map[string]float64{"memoryMB": 250, "renderers": 4}+ if fmt.Sprint(got) != fmt.Sprint(want) {+ t.Fatalf("MemoryMetrics = %v, want %v", got, want)+ }+}diff --git a/internal/handlers/handlers_test.go b/internal/handlers/handlers_test.goindex 6c81066c..f863208c 100644--- a/internal/handlers/handlers_test.go+++ b/internal/handlers/handlers_test.go@@ -174,15 +174,15 @@ func (m *mockBridge) Text(_ context.Context, _ string, _ bridge.ContentParams) (func (m *mockBridge) TabLockInfo(tabID string) *bridge.LockInfo { return nil }func (m *mockBridge) GetMemoryMetrics(tabID string) (*bridge.MemoryMetrics, error) {- return &bridge.MemoryMetrics{JSHeapUsedMB: 10}, nil+ return &bridge.MemoryMetrics{MemoryMB: 10, Renderers: 1}, nil}func (m *mockBridge) GetBrowserMemoryMetrics() (*bridge.MemoryMetrics, error) {- return &bridge.MemoryMetrics{JSHeapUsedMB: 50}, nil+ return &bridge.MemoryMetrics{MemoryMB: 50, Renderers: 2}, nil}func (m *mockBridge) GetAggregatedMemoryMetrics() (*bridge.MemoryMetrics, error) {- return &bridge.MemoryMetrics{JSHeapUsedMB: 50, Nodes: 500}, nil+ return &bridge.MemoryMetrics{MemoryMB: 50, Renderers: 3}, nil}func (m *mockBridge) GetCrashLogs() []string {diff --git a/internal/handlers/health_tabs_test.go b/internal/handlers/health_tabs_test.goindex 3c4a44a6..1faaba3c 100644--- a/internal/handlers/health_tabs_test.go+++ b/internal/handlers/health_tabs_test.go@@ -430,15 +430,15 @@ func (m *MockBridge) StealthStatus() *stealth.Status {}func (m *MockBridge) GetMemoryMetrics(tabID string) (*bridge.MemoryMetrics, error) {- return &bridge.MemoryMetrics{JSHeapUsedMB: 10, JSHeapTotalMB: 20}, nil+ return &bridge.MemoryMetrics{MemoryMB: 10, Renderers: 1}, nil}func (m *MockBridge) GetBrowserMemoryMetrics() (*bridge.MemoryMetrics, error) {- return &bridge.MemoryMetrics{JSHeapUsedMB: 50, JSHeapTotalMB: 100}, nil+ return &bridge.MemoryMetrics{MemoryMB: 50, Renderers: 2}, nil}func (m *MockBridge) GetAggregatedMemoryMetrics() (*bridge.MemoryMetrics, error) {- return &bridge.MemoryMetrics{JSHeapUsedMB: 50, JSHeapTotalMB: 100, Nodes: 500}, nil+ return &bridge.MemoryMetrics{MemoryMB: 50, Renderers: 3}, nil}func (m *MockBridge) GetCrashLogs() []string {diff --git a/internal/orchestrator/health_test.go b/internal/orchestrator/health_test.goindex 0bdb9b55..31cb2477 100644--- a/internal/orchestrator/health_test.go+++ b/internal/orchestrator/health_test.go@@ -360,7 +360,7 @@ func TestFetchMetrics_TagsBridgeRequestAsOrchestrator(t *testing.T) {source = req.Header.Get("X-PinchTab-Source")return &http.Response{StatusCode: http.StatusOK,- Body: io.NopCloser(strings.NewReader(`{"memory":{"jsHeapUsedMB":1}}`)),+ Body: io.NopCloser(strings.NewReader(`{"memory":{"memoryMB":1}}`)),Header: make(http.Header),}, nil}),diff --git a/internal/orchestrator/health_transport.go b/internal/orchestrator/health_transport.goindex a6596f61..cd8a7c55 100644--- a/internal/orchestrator/health_transport.go+++ b/internal/orchestrator/health_transport.go@@ -23,12 +23,8 @@ type remoteMetrics struct {}type memoryMetrics struct {- JSHeapUsedMB float64 `json:"jsHeapUsedMB"`- JSHeapTotalMB float64 `json:"jsHeapTotalMB"`- Documents int64 `json:"documents"`- Frames int64 `json:"frames"`- Nodes int64 `json:"nodes"`- Listeners int64 `json:"listeners"`+ MemoryMB float64 `json:"memoryMB"`+ Renderers int `json:"renderers"`}func (o *Orchestrator) fetchTabs(inst *InstanceInternal) ([]remoteTab, error) {diff --git a/internal/orchestrator/instance_query.go b/internal/orchestrator/instance_query.goindex 475f2ee9..93be0831 100644--- a/internal/orchestrator/instance_query.go+++ b/internal/orchestrator/instance_query.go@@ -267,14 +267,10 @@ func (o *Orchestrator) AllMetrics() []types.InstanceMetrics {continue}all = append(all, types.InstanceMetrics{- InstanceID: inst.ID,- ProfileName: inst.ProfileName,- JSHeapUsedMB: mem.JSHeapUsedMB,- JSHeapTotalMB: mem.JSHeapTotalMB,- Documents: mem.Documents,- Frames: mem.Frames,- Nodes: mem.Nodes,- Listeners: mem.Listeners,+ InstanceID: inst.ID,+ ProfileName: inst.ProfileName,+ MemoryMB: mem.MemoryMB,+ Renderers: mem.Renderers,})}return all