browser-trace

Files (12)

• EXAMPLES.md
• LICENSE.txt
• REFERENCE.md
• SKILL.md
• package.json
• bisect-cdp.mjs · scripts/
• cdp-firehose.mjs · scripts/
• lib.mjs · scripts/
• query.mjs · scripts/
• snapshot-loop.mjs · scripts/
• start-capture.mjs · scripts/
• stop-capture.mjs · scripts/

SKILL.md (first lines)

# Browser Trace

Attach a **second, read-only CDP client** to a browser session that is already being driven by your main automation. The trace records the full DevTools firehose to NDJSON, polls for screenshots and DOM dumps in parallel, and slices everything into a directory tree that bash tools can search.

This skill does **not** drive pages - it only listens. Pair it with `agent-browser` (the primary local driver, attached via `agent-browser connect <port>`), Playwright, Stagehand, or anything else that speaks CDP.

## When to use

- The user wants to debug a browser-automation run (failing form, missing element, hung navigation, JS exception).
- The user has a running automation and wants to attach a trace mid-flight without restarting it.
- The user wants to split a CDP firehose into network / console / DOM / page buckets.
- The user wants screenshots + DOM snapshots over time, joined to CDP events by timestamp.

If the user just wants to **drive** the browser, use the `agent-browser` skill instead.

## Setup check

```bash
node --version                                  # require Node 18+ (built-in WebSocket)
which jq     || true                            # optional - used only for ad-hoc querying
```

No `npm install` is needed: the firehose and sampler are raw CDP over Node's built-in `WebSocket`.

## How it works

Every Chrome DevTools target accepts **multiple concurrent CDP clients**. Your main automation is one client; this skill adds a second one that only enables observation domains (Network, Console, Runtime, Log, Page) and never sends action commands.

The tracer has three pieces:

1. **Firehose**: `cdp-firehose.mjs <target>` opens a native `WebSocket` to the target, enables the observation domains (and `Page.setLifecycleEventsEnabled` when `Page` is included), and streams every CDP event as one `{method, params, ts}` JSON object per line to `cdp/raw.ndjson`. Zero dependencies. If the socket closes it exits so the stream stays gap-free and `cdp/stderr.log` records the cause.
2. **Sampler**: `snapshot-loop.mjs` holds one persistent CDP connection for the whole run and, on an interval (default 2s), calls `Page.captureScreenshot` for a PNG and `Runtime.evaluate` for `document.body.outerHTML` and `location.href`. If the socket drops, the next tick reconnects instead of crashing the loop.
3. **Bisector**: after the run, `bisect-cdp.mjs` walks `raw.ndjson` once, slices it into per-bucket JSONL files keyed by CDP method, and additionally bisects per page using top-level `Page.frameNavigated` events as boundaries.

## Quickstart

```bash
# 1. Launch Chrome with a debugger port (any user-data-dir keeps it isolated).
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-o11y \
  about:blank &

# 2. Start the tracer.
node scripts/start-capture.mjs 9222 my-run

# 3. Run your main automation against port 9222. agent-browser attaches
#    over CDP (env -u guards against a stray AGENT_BROWSER_PROFILE that would
#    silently drive a different browser).
env -u AGENT_BROWSER_PROFILE agent-browser connect 9222
agent-browser open https://example.com
# ...whatever the run does...

# 4. Stop and bisect.
node scripts/stop-capture.mjs my-run
node scripts/bisect-cdp.mjs my-run
```

### Remote (Browserbase) sessions - not supported

This skill traces local CDP targets: a debug port or a page-level `ws://` URL. The former Browserbase helpers (`bb-capture.mjs` / `bb-finalize.mjs`) were removed because browse-cli 0.6.x dropped the entire `browse cloud` command group they shelled out to, and its replacement surface (`browse status --json` → browser-level `wsUrl`) does not expose a page-level target, which the firehose and sampler both need.

For ad-hoc inspection of a remote session driven by the `browser` skill, `browse cdp "$(browse status --json | jq -r .wsUrl)" --pretty` streams the session's DevTools events live (verified against browse-cli 0.6.0) - but it is a live view only, not this skill's capture/bisect pipeline.

## Filesystem layout

```
.o11y/<run-id>/
  manifest.json                 run metadata: target, domains, started_at, stopped_at
  index.jsonl                   one line per sample: {ts, screenshot, dom, url}
  cdp/
    raw.ndjson                  full CDP firehose (one JSON object per line)
    summary.json                {sessionId, duration, totalEvents, pages[]} - see shape below
    network/{requests,responses,finished,failed,websocket}.jsonl   session-wide buckets (always written)
    console/{logs,exceptions}.jsonl
    runtime/all.jsonl
    log/entries.jsonl
    page/{navigations,lifecycle,frames,dialogs,all}.jsonl
    dom/all.jsonl                                                  (only if O11Y_DOMAINS includes DOM)
    target/{attached,detached}.jsonl
    pages/                      per-page slices, indexed by top-level frameNavigated boundaries
      000/                      first concrete page
        url.txt                 the URL for this page
        summary.json            this page's domains/network/timing block (same shape as a pages[] entry)
        raw.jsonl               firehose scoped to this page
        network/, console/, page/, runtime/, log/, target/, dom/    same buckets, only non-empty files
  screenshots/<iso-ts>.png      one PNG per sample interval
  dom/<iso-ts>.html             one HTML dump per sample interval
```

When handing off trace artifacts, include the run directory and key files as openable locations:
`[manifest.json](/absolute/path/to/run/manifest.json)`,
`[screenshots](/absolute/path/to/run/screenshots)`, or matching `file://` URIs.
Do not report only the run id or a basename.

### Summary shape

`cdp/summary.json` is the entry point for any analysis: it has session-level totals and a `pages[]` array indexed by top-level `Page.frameNavigated`. Per-page entries are emitted in navigation order (page 0 = first concrete URL).

```json
{
  "sessionId": "45f28023-…",
  "duration": { "startMs": 1777312533000, "endMs": 1777312609000, "totalMs": 76000 },
  "totalEvents": 420,
  "pages": [
    {
      "pageId": 0,
      "url": "https://example.com/",
      "startMs": 1777312533000, "endMs": 1777312538886, "durationMs": 5886,
      "eventCount": 60,
      "domains": {
        "Network": { "count": 18, "errors": 1 },
        "Console": { "count": 2 },
        "Page":    { "count": 24 },
        "Runtime": { "count": 13 }
      },
      "network": { "requests": 4, "failed": 1, "byType": { "Document": 2, "Script": 1, "Other": 1 } }
    }
  ]

From vanducng/skills, MIT.

More from vanducng/skills