Skip to content

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.tsx
index 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.ts
index 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 name
diff --git a/dashboard/src/pages/settings/DashboardSettingsSection.tsx b/dashboard/src/pages/settings/DashboardSettingsSection.tsx
index 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>
<SettingRow
label="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">
<input
diff --git a/dashboard/src/stores/slices/monitoringSlice.ts b/dashboard/src/stores/slices/monitoringSlice.ts
index 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 -> memoryMB
currentMetrics: Record<string, InstanceMetrics>; // instanceId -> full metrics
addChartDataPoint: (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.ts
index 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.md
index 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 Monitoring
diff --git a/internal/api/types/types.go b/internal/api/types/types.go
index 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.go
index 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, err
children, 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, err
totalMem += 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.go
new file mode 100644
index 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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