Skip to content

Commit cf42174

Browse files
erkamyamanclaude
authored andcommitted
perf(overlay): send one page heartbeat instead of idle resends
An idle tab sent about 107 frames and 129 KB a minute, because every collector kept its page alive on the server by resending its full report or pinging every 5 to 8 seconds. The overlay now sends one small page-heartbeat every 10 seconds, which keeps the page alive in every store and replaces the page-interest poll. Collectors send only when their data changes, and resend everything when the server no longer knows the page. An idle tab now sends 6 frames and about 1 KB a minute. Refs #424
1 parent 8278a74 commit cf42174

23 files changed

Lines changed: 749 additions & 35 deletions

‎.claude/skills/devtools-inspector/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,12 @@ Read `docs/contributing/coding-standards.md` ("Reading data from the page") befo
2626
- `serialize.ts`: safe, size-limited serialization.
2727
- `router.ts` `providerOf()`: find a service through the injector resolution path.
2828
- Never write attributes into the app's DOM. Never run app code (validators, guards) on a timer unless the user turned recording on.
29-
- Pushes: send on change, skip unchanged payloads (compare with the last JSON), re-send every few cycles so the server doesn't expire the page, and avoid full DOM scans on a timer (cache, rescan after a `MutationObserver` signal).
29+
- Pushes: send on change, skip unchanged payloads (compare with the last JSON), and let the page heartbeat keep the page alive: re-send an unchanged report only when `keepaliveDue`/`keepaliveAfter` says so (the server lost the page), and avoid full DOM scans on a timer (cache, rescan after a `MutationObserver` signal).
3030
- Every report carries `pageId` from `claimPageId()`. Call `forget-<area>-page` from `leave()`.
3131

3232
## Server side (`devframe.ts`, `rpc/`)
3333

34-
- Keep a `Map<pageId, report>` with `reportedAt`, drop pages older than 15 seconds in the shared expiry interval, and write the combined value into the shared state.
34+
- Keep a `Map<pageId, report>` with `reportedAt`, drop pages older than `ttl(pageId)` (from `visibility.ttl()`, so a page with a current heartbeat never expires) in the shared expiry interval, and write the combined value into the shared state.
3535
- Page actions that the panel triggers (restore, highlight, run) go panel -> `request-<area>-action` -> broadcast `<area>-action` to the page -> `<area>-action-result`, keyed by `requestId`, with a timeout.
3636
- Source scans in `rpc/` enrich or stand in for live data. They must return a `kind` for anything the Dashboard counts.
3737

‎apps/docs/src/content/getting-started/configuration.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ Values outside the bounds are clamped to the nearest one.
192192

193193
When a timeline reaches its limit, the oldest entries are dropped. The timeline then shows a note above the list, such as "Showing the latest 200 HTTP calls. 12 older entries were dropped." with the limit to raise. This applies to the **SSR & HTTP** timeline, the router navigation timeline, the forms timeline, the NgRx change log, the change detection recording and the Capacitor plugin calls. The `explain-navigation`, `form-history` and `change-detection` agent tools add the same note, and the `pangular:ngrx-store` resource reports a `dropped` count per page.
194194

195-
On Angular 20 and later, the page reports about 250 ms after Angular runs change detection, plus a heartbeat every 4 seconds. `refreshMs` doesn't change that. The page polls every `refreshMs` instead when it can't follow change detection, such as until the app bootstraps. The Analog inspector also reads the page every `refreshMs`. At any value, the page sends its data at least every 8 seconds, even when nothing changed, so the server never drops a page that is still open.
195+
On Angular 20 and later, the page reports about 250 ms after Angular runs change detection, plus a heartbeat every 4 seconds. `refreshMs` doesn't change that. The page polls every `refreshMs` instead when it can't follow change detection, such as until the app bootstraps. The Analog inspector also reads the page every `refreshMs`. At any value, the page sends a small heartbeat every 10 seconds instead of data that didn't change, so the server never drops a page that is still open. If the server lost the page (it restarted, or the page went quiet for more than 15 seconds), the page sends all of its data again.
196196

197197
### Performance
198198

@@ -201,7 +201,7 @@ The component tree, injectors, change detection recording and forms cost the mos
201201
- After one full report, the page sends only what changed. If the server lost track (a restart, a lost message), it asks for the whole report again.
202202
- The page sends each of them at most once a second, also while you type in a form. Changes in between go out together in the next report, so the forms timeline keeps every event. A form action from the panel or an agent is sent at once.
203203
- The component tree is read again only when elements were added or removed, or every 4 seconds.
204-
- The page sends them only while someone watches: a panel is open (the popup, the hub or the Chrome extension), or an agent called a tool in the last `limits.idleAfterMs`. An idle page only says it is still open. The forms timeline keeps recording meanwhile, and so do the errors and console calls of the [Errors](../inspectors/errors.md) tab, which the page sends on the same terms. When a panel opens or an agent calls a tool, the page sends what changed meanwhile, and the agent's call waits up to 1.5 seconds for it. An agent call made during that wait waits for the same reports. A tab that closed or stopped reporting is not waited for.
204+
- The page sends them only while someone watches: a panel is open (the popup, the hub or the Chrome extension), or an agent called a tool in the last `limits.idleAfterMs`. An idle page only sends its heartbeat. The forms timeline keeps recording meanwhile, and so do the errors and console calls of the [Errors](../inspectors/errors.md) tab, which the page sends on the same terms. When a panel opens or an agent calls a tool, the page sends what changed meanwhile, and the agent's call waits up to 1.5 seconds for it. An agent call made during that wait waits for the same reports. A tab that closed or stopped reporting is not waited for.
205205

206206
In the panel, the component tree, the HTTP call table, and the NgRx change log and events render only the rows near view when they have more than 300. Rows out of view are not in the page, so the browser's find doesn't see them. Use the tab's search field to search every row.
207207

‎apps/docs/src/content/getting-started/overlay.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -285,7 +285,7 @@ While you pick an element on the page, the box follows the pointer and clears wh
285285
No. The overlay adds the floating button itself. See <a href="./popup-and-hub.md">Popup and hub</a>.
286286
</ngmd-accordion-item>
287287
<ngmd-accordion-item title="Does it slow down my app?">
288-
It reads the page after change detection, at most once every 250 ms, plus a heartbeat every 4 seconds. It sends an inspector's data only when it changed. The HTTP inspector sends only the calls made since its last report. When the data of the components, signals, injectors, router or HTTP inspector stays the same for 5 to 8 seconds, the page sends a short ping instead, so the server keeps the page. With the dynamic import above, it never loads in production builds.
288+
It reads the page after change detection, at most once every 250 ms, plus a heartbeat every 4 seconds. It sends an inspector's data only when it changed. The HTTP inspector sends only the calls made since its last report. While nothing changes, the page sends only a small heartbeat every 10 seconds, which keeps all of its data on the server. With the dynamic import above, it never loads in production builds.
289289
</ngmd-accordion-item>
290290
<ngmd-accordion-item title="Which values leave the page?">
291291
Live values are sent to the devtools server. Secret-looking values are redacted first. See <a href="../security.md">Access and redaction</a>.

‎apps/docs/src/content/guides/write-a-plugin.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -301,14 +301,14 @@ A `read` tool that calls `runPageAction` gets a refusal instead. Every answer st
301301

302302
## What the devtools take care of
303303

304-
| Concern | How |
305-
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
306-
| Redaction | The page and the server run every view through `serialize()`, so `redaction.secretNames`, JWTs and bearer tokens are masked. |
307-
| Pages | Each report carries the page id. The server keeps one entry per page, drops it 15 seconds after the last report, and forgets it when the tab closes. |
308-
| Cost | `collect` runs while someone watches, at most once a second for page updates and `refresh()`. It also runs right away for the first report, even while nobody watches, and when someone starts watching. While someone watches, a finished page action or a plugin registering runs it right away too. An unchanged report is skipped, and a keepalive keeps an idle page listed. |
309-
| Size | Up to 20 sections, 12 columns, 200 rows or items per section, and 2,000 characters per text. Unknown section kinds are dropped. |
310-
| Failures | A plugin that throws shows as **Failed** with its message. The other plugins keep running. |
311-
| Switches | `inspectors.plugins` and `plugins.<id>` turn plugins off. See [Plugins](../getting-started/configuration.md#plugins). |
304+
| Concern | How |
305+
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
306+
| Redaction | The page and the server run every view through `serialize()`, so `redaction.secretNames`, JWTs and bearer tokens are masked. |
307+
| Pages | Each report carries the page id. The server keeps one entry per page, drops it 15 seconds after the page's last report or heartbeat, and forgets it when the tab closes. |
308+
| Cost | `collect` runs while someone watches, at most once a second for page updates and `refresh()`. It also runs right away for the first report, even while nobody watches, and when someone starts watching. While someone watches, a finished page action or a plugin registering runs it right away too. An unchanged report is skipped, and the page heartbeat keeps an idle page listed. |
309+
| Size | Up to 20 sections, 12 columns, 200 rows or items per section, and 2,000 characters per text. Unknown section kinds are dropped. |
310+
| Failures | A plugin that throws shows as **Failed** with its message. The other plugins keep running. |
311+
| Switches | `inspectors.plugins` and `plugins.<id>` turn plugins off. See [Plugins](../getting-started/configuration.md#plugins). |
312312

313313
Agents read plugin views with [`list-plugins` and `inspect-plugin`](../agents/tools.md#plugins).
314314

‎apps/docs/src/content/inspectors/components.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -291,7 +291,7 @@ A notice at the top says why you see the source list: no page is connected, or t
291291

292292
<ngmd-card-grid columns="2">
293293
<ngmd-card icon="zap" title="Live page">
294-
The overlay walks the page with Angular's debug API after change detection. It doesn't resend an unchanged tree. After 8 seconds without a change, it sends a short ping so the server keeps the page.
294+
The overlay walks the page with Angular's debug API after change detection. It doesn't resend an unchanged tree. A small heartbeat every 10 seconds keeps the page on the server.
295295
</ngmd-card>
296296
<ngmd-card icon="file" title="Source scan">
297297
The server scans your files for <code>&#64;Component</code> and <code>&#64;Directive</code> classes. It also supplies the file and line in the detail header.
@@ -317,7 +317,7 @@ The live tree reads `window.ng`, which only development builds expose. It uses t
317317

318318
### Refresh rate
319319

320-
On Angular 20 and later, the page reads the tree about 250 ms after Angular runs change detection, and every 4 seconds as a heartbeat. Until the app bootstraps, it reads the tree every 3 seconds. It also reads it at once when you select an instance. It reads the detail block only for the selected instance. The server drops a page after 15 seconds without a report, unless its tab is in the background. See [Tabs in the background](../getting-started/popup-and-hub.md#tabs-in-the-background).
320+
On Angular 20 and later, the page reads the tree about 250 ms after Angular runs change detection, and every 4 seconds as a heartbeat. Until the app bootstraps, it reads the tree every 3 seconds. It also reads it at once when you select an instance. It reads the detail block only for the selected instance. The server drops a page after 15 seconds without a report or a heartbeat, unless its tab is in the background. See [Tabs in the background](../getting-started/popup-and-hub.md#tabs-in-the-background).
321321

322322
## How to use it
323323

‎docs/CONTEXT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ The tree Angular rendered into, as the component, injector, signal graph and NgR
4141
_Avoid_: view tree, render tree, DOM (when the code does not depend on it)
4242

4343
**Push**:
44-
A report a collector sends to the server over RPC, such as `push-component-tree`. A collector sends one when something changed, and a keepalive at intervals so the server knows the page is still there. Pushes stay cheap.
44+
A report a collector sends to the server over RPC, such as `push-component-tree`. A collector sends one when something changed. One page heartbeat (`page-heartbeat`) every 10 seconds tells the server the page is still there, for every collector. Pushes stay cheap.
4545
_Avoid_: sync, upload, post
4646

4747
**Inspector**:

‎docs/contributing/coding-standards.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,9 @@ The overlay runs inside the user's app, so it must be correct, cheap and invisib
3232
- **Walk the host tree, not the DOM**, in the component, injector, signal graph and NgRx collectors. Take a `HostTree` (`host-tree.ts`) that defaults to `domTree()`, so the same collector runs on a platform without a DOM.
3333
- **Strip bundler prefixes** from class names (`className()` in `injector-tree.ts`), so `_App` shows as `App`.
3434
- **Don't match `_nghost-*` or `_ngcontent-*` attributes** with exact selectors; their names carry a suffix. Start from `[ng-version]` roots and the debug APIs.
35-
- **Keep pushes cheap.** Skip unchanged reports (compare with the last JSON sent), re-send now and then so the server doesn't expire the page, and avoid `querySelectorAll('*')` on a timer; cache and rescan on a `MutationObserver` signal.
35+
- **Keep pushes cheap.** Skip unchanged reports (compare with the last JSON sent); the page heartbeat (`page-heartbeat.ts`) keeps every store of the page alive, and `keepaliveDue` or `keepaliveAfter` says when the server lost the page and a report must go again, and avoid `querySelectorAll('*')` on a timer; cache and rescan on a `MutationObserver` signal.
3636
- **Serialize safely** with `serialize()` from `serialize.ts`: it limits depth and size and handles `Map`, `Set`, `Date`, class instances, cycles and Angular's signal sentinels.
37-
- **Every report carries a `pageId`.** The server keeps one entry per page, expires it after 15 seconds without a push, and forgets it on `pagehide` (`forget-<area>-page`). Two open tabs must never overwrite each other.
37+
- **Every report carries a `pageId`.** The server keeps one entry per page, expires it after 15 seconds without a push or a `page-heartbeat` (pass the TTL from `visibility.ttl()`, which honours both), and forgets it on `pagehide` (`forget-<area>-page`). Two open tabs must never overwrite each other.
3838
- **One connection owns each `pageId`.** Push, ping and forget handlers go through the shared owner check in `rpc/page-owners.ts` (`owners.write(pageId)` before storing a report, `owners.forget(pageId)` before dropping one), never an ad hoc check. The first connection to report a page owns it. A push or forget for that page from another connection is ignored, unless the owner closed or went quiet past the page expiry. The overlay mints a secret with the `pageId` and keeps it next to it (`sessionStorage` in a browser, memory in the native overlays), and shows it with `claim-page` before its first report. A connection that shows the matching secret takes the page over at once, so a reloaded tab gets its own `pageId` back while the old connection is still open. In-process calls (no RPC session) are allowed.
3939
- **Don't change app behavior.** Don't run the app's validators, guards or effects to learn something unless the user asked for it (recording, instrumenting), and say so in the UI.
4040

0 commit comments

Comments
 (0)