Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix(metrics): one memory method on BridgeAPI, taking no tab id it ignores, and docs that name the instance scope (PIN-296)

Luigi Agosti2db9c83dc48d
diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.md
index f94bbc9e..4944228f 100644
--- a/docs/guides/multi-instance.md
+++ b/docs/guides/multi-instance.md
@@ -68,6 +68,10 @@ curl "http://localhost:9867/tabs/<tabId>/text"
curl "http://localhost:9867/tabs/<tabId>/metrics"
```
+`/tabs/<tabId>/metrics` answers with the owning instance's aggregate memory, not the
+tab's own — the tab id selects which instance to ask. See
+[Memory monitoring](memory-monitoring.md).
+
## Reuse A Persistent Profile
List existing profiles first:
diff --git a/docs/reference/metrics.md b/docs/reference/metrics.md
index 1dcbe6e3..2edc1557 100644
--- a/docs/reference/metrics.md
+++ b/docs/reference/metrics.md
@@ -43,7 +43,12 @@ failing. Read each layer at its own endpoint instead:
| `GET /metrics` | front door (server mode) / the bridge itself (bridge mode) | that process's own counters |
| `GET /instances/{id}/metrics` | proxied to that instance | that instance's counters |
| `GET /instances/metrics` | front door | per-instance **browser memory**, not request counters |
-| `GET /tabs/{id}/metrics` | proxied to the owning instance | one tab's browser measurements |
+| `GET /tabs/{id}/metrics` | proxied to the owning instance | that instance's **browser memory** — the whole process tree, not the tab |
+
+The tab id in the last row selects the instance to ask, never the measurement. There
+is no per-tab reading behind it: two tabs of one instance answer identically, and the
+figure is the same one that instance reports for itself. See
+[Memory monitoring](../guides/memory-monitoring.md).
`failures.recent` repeats `layer` on each event as well as on the block, so an
event pasted into a bug report still says where it came from.
diff --git a/docs/reference/tabs.md b/docs/reference/tabs.md
index 53b1be72..0b46a7d0 100644
--- a/docs/reference/tabs.md
+++ b/docs/reference/tabs.md
@@ -274,7 +274,9 @@ Reading, writing, and clearing cookies requires `security.allowCookies=true`.
curl http://localhost:9867/tabs/<tabId>/metrics
```
-This reports memory metrics for the tab through the bridge, not a full per-tab performance profile.
+This reports the owning browser instance's aggregate memory — the whole process tree —
+not an isolated per-tab reading: the tab id picks the instance to ask. Two tabs of one
+instance return the same figures. See [Memory monitoring](../guides/memory-monitoring.md).
## Lock And Unlock
diff --git a/internal/bridge/api.go b/internal/bridge/api.go
index d29267d7..e0cbf6ab 100644
--- a/internal/bridge/api.go
+++ b/internal/bridge/api.go
@@ -61,8 +61,9 @@ type BridgeAPI interface {
RunningBrowser() (string, bool)
StealthStatus() *stealth.Status
- GetMemoryMetrics(tabID string) (*MemoryMetrics, error)
- GetBrowserMemoryMetrics() (*MemoryMetrics, error)
+ // GetAggregatedMemoryMetrics measures the whole browser process tree. There is
+ // no per-tab reading behind it, so it takes no tab identifier: /tabs/{id}/metrics
+ // uses the id to select the owning instance, never the measurement.
GetAggregatedMemoryMetrics() (*MemoryMetrics, error)
GetCrashLogs() []string
diff --git a/internal/bridge/observe_facade.go b/internal/bridge/observe_facade.go
index 6685a9ba..d397db94 100644
--- a/internal/bridge/observe_facade.go
+++ b/internal/bridge/observe_facade.go
@@ -128,14 +128,6 @@ func GetResponseBody(ctx context.Context, requestID string) (string, bool, error
return bridgeobserve.GetResponseBody(ctx, requestID)
}
-func (b *Bridge) GetMemoryMetrics(tabID string) (*MemoryMetrics, error) {
- return b.GetAggregatedMemoryMetrics()
-}
-
-func (b *Bridge) GetBrowserMemoryMetrics() (*MemoryMetrics, error) {
- return b.GetAggregatedMemoryMetrics()
-}
-
func (b *Bridge) GetAggregatedMemoryMetrics() (*MemoryMetrics, error) {
return bridgeobserve.GetAggregatedMemoryMetrics(b.BrowserCtx)
}
diff --git a/internal/handlers/find_test.go b/internal/handlers/find_test.go
index 2a05f3c2..3b46a61c 100644
--- a/internal/handlers/find_test.go
+++ b/internal/handlers/find_test.go
@@ -52,12 +52,6 @@ func (m *findMockBridge) NetworkMonitor() *bridge.NetworkMonitor { ret
func (m *findMockBridge) ExecuteAction(ctx context.Context, kind string, req bridge.ActionRequest) (map[string]any, error) {
return nil, nil
}
-func (m *findMockBridge) GetMemoryMetrics(tabID string) (*bridge.MemoryMetrics, error) {
- return &bridge.MemoryMetrics{}, nil
-}
-func (m *findMockBridge) GetBrowserMemoryMetrics() (*bridge.MemoryMetrics, error) {
- return &bridge.MemoryMetrics{}, nil
-}
func (m *findMockBridge) GetAggregatedMemoryMetrics() (*bridge.MemoryMetrics, error) {
return &bridge.MemoryMetrics{}, nil
}
diff --git a/internal/handlers/handlers_test.go b/internal/handlers/handlers_test.go
index f863208c..caaa585f 100644
--- a/internal/handlers/handlers_test.go
+++ b/internal/handlers/handlers_test.go
@@ -173,14 +173,6 @@ 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{MemoryMB: 10, Renderers: 1}, nil
-}
-
-func (m *mockBridge) GetBrowserMemoryMetrics() (*bridge.MemoryMetrics, error) {
- return &bridge.MemoryMetrics{MemoryMB: 50, Renderers: 2}, nil
-}
-
func (m *mockBridge) GetAggregatedMemoryMetrics() (*bridge.MemoryMetrics, error) {
return &bridge.MemoryMetrics{MemoryMB: 50, Renderers: 3}, nil
}
diff --git a/internal/handlers/health_tabs.go b/internal/handlers/health_tabs.go
index 9515edc8..832c3989 100644
--- a/internal/handlers/health_tabs.go
+++ b/internal/handlers/health_tabs.go
@@ -128,7 +128,7 @@ func (h *Handlers) HandleTabMetrics(w http.ResponseWriter, r *http.Request) {
return
}
- mem, err := h.Bridge.GetMemoryMetrics(tabID)
+ mem, err := h.Bridge.GetAggregatedMemoryMetrics()
if err != nil {
httpx.Error(w, 500, fmt.Errorf("failed to get metrics: %w", err))
return
diff --git a/internal/handlers/health_tabs_test.go b/internal/handlers/health_tabs_test.go
index 1faaba3c..478e2f49 100644
--- a/internal/handlers/health_tabs_test.go
+++ b/internal/handlers/health_tabs_test.go
@@ -429,14 +429,6 @@ func (m *MockBridge) StealthStatus() *stealth.Status {
}
}
-func (m *MockBridge) GetMemoryMetrics(tabID string) (*bridge.MemoryMetrics, error) {
- return &bridge.MemoryMetrics{MemoryMB: 10, Renderers: 1}, nil
-}
-
-func (m *MockBridge) GetBrowserMemoryMetrics() (*bridge.MemoryMetrics, error) {
- return &bridge.MemoryMetrics{MemoryMB: 50, Renderers: 2}, nil
-}
-
func (m *MockBridge) GetAggregatedMemoryMetrics() (*bridge.MemoryMetrics, error) {
return &bridge.MemoryMetrics{MemoryMB: 50, Renderers: 3}, nil
}
@@ -711,3 +703,50 @@ func TestHandleHealth_IncludesFailureAndCrashDiagnostics(t *testing.T) {
t.Fatal("expected crashes diagnostics in /health response")
}
}
+
+// GET /tabs/{id}/metrics reports the owning INSTANCE's process-tree memory. The tab
+// id selects the instance and the 404 for an unknown tab, never the measurement, so
+// two live tabs of one instance must answer identically — that is the documented
+// behaviour (docs/reference/metrics.md, docs/guides/memory-monitoring.md), not a bug.
+//
+// The day a genuinely per-target reading exists, this is the test that has to change,
+// and changing it is the decision to publish a narrower scope under this path.
+func TestTabMetricsReportTheInstanceAggregateForEveryTabOfOneInstance(t *testing.T) {
+ h := New(&MockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)
+ mux := http.NewServeMux()
+ h.RegisterRoutes(mux, nil)
+
+ read := func(path string) map[string]any {
+ t.Helper()
+ req := httptest.NewRequest("GET", path, nil)
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+ if w.Code != http.StatusOK {
+ t.Fatalf("GET %s = %d: %s", path, w.Code, w.Body.String())
+ }
+ var body map[string]any
+ if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {
+ t.Fatalf("decode %s: %v (body %s)", path, err, w.Body.String())
+ }
+ return body
+ }
+
+ first := read("/tabs/tab-one/metrics")
+ second := read("/tabs/tab-two/metrics")
+ if fmt.Sprint(first) != fmt.Sprint(second) {
+ t.Errorf("two tabs of one instance reported different memory (%v vs %v); this endpoint measures the browser process tree, so a per-tab difference would mean the scope changed",
+ first, second)
+ }
+
+ // The scope is checkable rather than merely asserted: the same reading is what
+ // this instance publishes for itself at /metrics, which is the layer the
+ // reference table names.
+ instance, ok := read("/metrics")["memory"].(map[string]any)
+ if !ok {
+ t.Fatalf("the instance /metrics carried no memory block; the comparison below would be vacuous")
+ }
+ if fmt.Sprint(first) != fmt.Sprint(instance) {
+ t.Errorf("the tab endpoint reported %v while the instance reports %v; the tab path must serve the instance aggregate, not a second source",
+ first, instance)
+ }
+}