cdpmonitor

CDP Monitor

The monitor is the browser-facing layer of the kernel browser logging pipeline. It connects to Chrome's DevTools endpoint, tracks all page sessions via CDP's Target.setAutoAttach, and converts raw CDP notifications into typed events.Event values for downstream consumers.

Overview

cdpmonitor manages a Chrome DevTools Protocol (CDP) WebSocket connection to a running Chrome browser. It subscribes to CDP events across all attached tabs, translates them into structured events.Event values, and publishes them via a caller-supplied PublishFunc. It also derives synthetic events from sequences of CDP events and takes screenshots on significant page activity.

Chrome can restart independently of the monitor. When that happens, UpstreamProvider pushes a new DevTools URL and the monitor reconnects automatically, emitting lifecycle events so consumers can track continuity.

Event taxonomy

CDP-derived (1-to-1 with a CDP notification): console_log, console_error, network_request, network_response, network_loading_failed, page_tab_opened, page_navigation, page_dom_content_loaded, page_load, page_layout_shift, page_lcp

Computed (inferred from sequences of CDP events): network_idle (fires when in-flight requests drop to zero), page_layout_settled (1 s after page_load with no intervening layout shifts), page_navigation_settled (fires once page_dom_content_loaded and page_layout_settled have both fired for the same navigation; intentionally independent of network_idle so that a single hung request cannot stall the event).

Interaction (fired by interaction.js via Runtime.bindingCalled): interaction_click, interaction_key, interaction_scroll_settled

Monitor lifecycle (emitted by the monitor itself, not by Chrome): monitor_screenshot, monitor_disconnected, monitor_reconnected, monitor_reconnect_failed, monitor_init_failed

Responsibilities

Internals

Reconnect model

subscribeToUpstream listens to UpstreamProvider.Subscribe() for new DevTools URLs. On each URL change (indicating Chrome restarted), handleUpstreamRestart tears down the existing connection, dials the new URL with capped-exponential backoff (250 ms → 500 ms → 1 s → 2 s, up to 10 attempts), then restarts readLoop and re-initializes all CDP sessions. restartMu serializes concurrent restart signals so rapid Chrome restarts do not produce overlapping reconnects.

Goroutines

Stop() cancels lifecycleCtx, waits for readLoop via done, then waits for all other goroutines via asyncWg before closing the connection.

Lock ordering

Locks must be acquired left to right. Never hold a lock on the left while acquiring one further right.

restartMu -> lifeMu -> pendReqMu -> computed.mu -> pendMu
restartMu -> lifeMu -> sessionsMu

computed.mu and sessionsMu are never held simultaneously; cs.stop() and cs.resetOnNavigation() are called only after the relevant sessionsMu critical section is complete.

bindingRateMu is independent of this ordering and is always acquired alone.

Fields that need no mutex use sync/atomic: nextID, mainSessionID, running, lastScreenshotAt, screenshotInFlight.

WebSocket concurrency

coder/websocket guarantees one concurrent Read and one concurrent Write are safe on the same connection. readLoop is the sole reader. All writes go through send, which calls conn.Write directly; conn.Write is internally serialized by the library, so no external write mutex is needed.

Event data model

Envelope and top-level fields

Every event arrives as an Envelope:

{
  "seq": 42,
  "event": {
    "ts": 1746123456789000,
    "type": "network_request",
    "category": "network",
    "source": {
      "kind": "cdp",
      "event": "Network.requestWillBeSent",
      "metadata": {
        "telemetry_session_id": "cs_abc123",
        "cdp_session_id": "...",
        "target_id": "...",
        "target_type": "page"
      }
    },
    "data": { ... },
    "truncated": false
  }
}

Source object

"source": {
  "kind": "cdp",
  "event": "Network.requestWillBeSent",
  "metadata": {
    "cdp_session_id": "...",
    "target_id": "...",
    "target_type": "page"
  }
}

CDP identity primer

Five IDs appear across events. Understanding how they nest prevents confusion:

target_id          <- one per tab/window; stable across navigations
└── cdp_session_id <- WebSocket multiplexer channel to that target; resets on Chrome restart
    └── frame_id   <- one per frame (top-level or iframe); changes on navigation
        └── loader_id  <- one per document load; links a navigation to its network requests
            └── request_id <- one per request (stable across redirects in a chain)

Navigation context fields

Most event data objects include a nav context block stamped at the last page_navigation. These fields reflect the top-level frame most recently navigated in the session:

Events that do not compose BrowserEventContext

Of the 22 event types, two intentionally omit the standard nav context block:

• page_tab_opened: fires before a CDP session is attached to the new target, so session_id, frame_id, loader_id, and nav_seq are absent. Only target_id, target_type, and the tab's initial url/title/opener_id are populated.
• page_navigation: resets the navigation epoch, so it carries the new context fields inline but omits nav_seq (the value reported by subsequent events for this epoch is nav_seq + 1).

Consumers that destructure BrowserEventContext generically should treat these two events as special cases.

Per-event data fields

The canonical schema for each event's data payload is defined in openapi.yaml under the corresponding Browser*EventData schema (e.g. BrowserNetworkRequestEventData). All 22 event shapes are collected into the KnownBrowserTelemetryEvent discriminated union, which maps each type string to its concrete schema; use that as the entry point when looking up a specific event's fields. The table below summarises the key fields; refer to the schema for the authoritative field list and types.

Unless otherwise noted, events also include the nav context fields described above. Network events are the exception: they carry their own loader_id and frame_id directly and do not include nav context.

Console events

Network events

Page events

Computed events

network_idle, page_layout_settled, and page_navigation_settled carry nav context fields only.

Interaction events

All interaction events include nav context plus the fields below.

Monitor lifecycle events

Lifecycle events use source.kind = "local_process" and carry no nav context, except monitor_screenshot which includes nav context alongside the image payload.