Rastreo del navegador

Conecta un segundo cliente CDP de solo lectura a una sesión de navegador que ya esté siendo controlada por tu automatización principal. El rastreo registra todo el flujo de datos de DevTools en formato NDJSON, recopila capturas de pantalla y volcados del DOM en paralelo, y organiza todo en un árbol de directorios que las herramientas de bash pueden rastrear.

Esta habilidad no controla páginas, solo escucha. Combínala con la browser función, browse, Stagehand, Playwright o cualquier otra herramienta compatible con CDP.

Cuándo utilizarla

• El usuario quiere depurar una ejecución de automatización del navegador (formulario que falla, elemento que falta, navegación bloqueada, excepción de JS).
• El usuario tiene una automatización en ejecución y quiere añadir un seguimiento sobre la marcha sin reiniciarla.
• El usuario quiere dividir un flujo de datos de CDP en grupos de red, consola, DOM y página.
• El usuario quiere capturas de pantalla e instantáneas del DOM a lo largo del tiempo, vinculadas a eventos de CDP mediante una marca de tiempo.

Si el usuario solo quiere controlar el navegador, utilice la browser habilidad correspondiente.

Comprobación de la configuración

node --version                                  # require Node 18+
which browse || npm install -g browse
which jq     || true                                # optional — used only for ad-hoc querying

Comprueba que browse cdp existe:

browse --help | grep -q "^\s*cdp " || echo "browse cdp not available — update browse"

Cómo funciona

Cada objetivo de Chrome DevTools admite varios clientes CDP simultáneos. Tu automatización principal es un cliente; esta skill añade un segundo cliente que solo habilita los dominios de observación (Red, Consola, Tiempo de ejecución, Registro, Página) y nunca envía comandos de acción.

El rastreador consta de tres partes:

1. Firehose: browse cdp transmite cada evento de CDP como un objeto JSON por línea a cdp/raw.ndjson.
2. Muestreador: un bucle de sondeo llama a browse screenshot --cdp --path y browse get html body --cdp a intervalos (por defecto, cada 2 s). El ayudante pasa --cdp cuándo realiza el muestreo para poder conectarse al objetivo rastreado desde su propio proceso; una vez que una sesión del demonio de exploración se conecta a un objetivo CDP, los comandos posteriores de esa sesión no necesitan repetir --cdp.
3. Bisector: tras la ejecución, bisect-cdp.mjs recorre raw.ndjson una vez, lo divide en archivos JSONL por «bucket» con el método CDP como clave y, además, realiza una bisección por página utilizando los Page.frameNavigated como límites.

Guía rápida

Chrome local

# 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.
browse open https://example.com --cdp 9222
# ...whatever the run does...

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

Browserbase remoto

Dos funciones auxiliares se encargan de la gestión por parte de la plataforma: bb-capture.mjs crea o se vincula a una sesión e inicia el rastreador; bb-finalize.mjs extrae los artefactos de la plataforma (metadatos finales de la sesión, registros del servidor, descargas) y los coloca en el directorio de ejecución al finalizar.

Browserbase finaliza una sesión tan pronto como se desconecta su último cliente CDP. Crea la sesión con «--keep-alive» y, a continuación, vincula la automatización a «connectUrl» de la sesión antes o al mismo tiempo que el rastreador. bb-capture.mjs --new Se encarga de la configuración de la sesión «keep-alive» y del rastreador; tu automatización aún debe añadirse.

export BROWSERBASE_API_KEY=...

# 1. Create a keep-alive session AND start the tracer in one step.
#    Prints the session id, connectUrl prefix, and a live debugger URL you
#    can open in a browser to watch the run interactively.
node scripts/bb-capture.mjs --new my-run

# 2. Drive automation. bb-capture stamped the session id into the manifest.
SID=$(jq -r .browserbase.session_id .o11y/my-run/manifest.json)
CONNECT_URL="$(browse cloud sessions get "$SID" | jq -r .connectUrl)"
BROWSE_NAME=my-run-browser
browse open https://example.com --cdp "$CONNECT_URL" --session "$BROWSE_NAME"
browse open https://news.ycombinator.com --session "$BROWSE_NAME"

# 3. Stop the tracer, bisect, then pull platform artifacts and release.
node scripts/stop-capture.mjs my-run
node scripts/bisect-cdp.mjs my-run
node scripts/bb-finalize.mjs my-run --release

Al vincularse a una sesión que ya está en ejecución (por ejemplo, una creada por tu trabajador de producción): bb-capture.mjs acepta un ID de sesión en lugar de --new:

# Pick a running session (filter client-side; browse cloud sessions list has no --status flag)
browse cloud sessions list | jq -r '.[] | select(.status == "RUNNING") | .id'

node scripts/bb-capture.mjs  mid-flight-debug
# ...tracer runs alongside the existing automation client; no disruption...
node scripts/stop-capture.mjs mid-flight-debug
node scripts/bisect-cdp.mjs mid-flight-debug
node scripts/bb-finalize.mjs mid-flight-debug   # without --release: leave the session running

Lo que obtienes de la plataforma Browserbase

bb-capture.mjs añade un browserbase bloque a manifest.json (ID de sesión, proyecto, región, started_at, expires_at, URL del depurador). bb-finalize.mjs escribe:

• /browserbase/session.json — instantánea final browse cloud sessions get instantánea (proxyBytes, estado, ended_at, ventana de visualización, …)
• /browserbase/logs.json — browse cloud sessions logs salida. A menudo vacía. El flujo de datos del CDP en cdp/raw.ndjson es la fuente de referencia; esto es un canal secundario.
• /browserbase/downloads.zip — archivos descargados por la sesión, si los hay (el script descarta el archivo zip vacío de 22 bytes que se obtiene cuando no hay ninguno)

La obtención de artefactos de reproducción de sesiones está obsoleta y no se lleva a cabo. Utiliza las capturas de pantalla y los volcados de DOM en screenshots/ y dom/ como referencia visual.

El debugger_url del manifiesto abre una vista interactiva de Chrome DevTools servida por Browserbase —muy útil para observar una automatización de larga duración mientras el rastreador captura el flujo de datos en el disco.

Estructura del sistema de archivos

.o11y//
  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/.png      one PNG per sample interval
  dom/.html             one HTML dump per sample interval
  browserbase/                  added by bb-finalize.mjs (Browserbase runs only)
    session.json                final `browse cloud sessions get` snapshot (proxyBytes, status, ended_at, …)
    logs.json                   `browse cloud sessions logs` output (often [])
    downloads.zip               `browse cloud sessions downloads get` output (only if the session downloaded files)

Cuando se inicia una ejecución mediante bb-capture.mjs, manifest.json también incluye un browserbase : session_id, project_id, region, started_at, expires_at, keep_alive, debugger_url.

La forma «Resumen»

cdp/summary.json es el punto de entrada para cualquier análisis: contiene los totales a nivel de sesión y una pages[] matriz indexada por el nivel superior Page.frameNavigated. Las entradas por página se emiten en orden de navegación (página 0 = primera URL concreta).

{
  "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 } }
    }
  ]
}

startMs / endMs / durationMs Son milisegundos de reloj real, derivados de manifest.started_at más el desplazamiento de la marca de tiempo monótona CDP de cada evento. domains[*] solo incluye errors/warnings claves cuando son distintas de cero.

Profundizar con query.mjs

Para una exploración interactiva, utiliza scripts/query.mjs en lugar de memorizar las rutas:

node scripts/query.mjs my-run list                    # one-line table of pages
node scripts/query.mjs my-run page 1                  # full summary for page 1
node scripts/query.mjs my-run page 1 network/failed   # cat failed.jsonl for page 1
node scripts/query.mjs my-run errors                  # all errors across pages, attributed by pid
node scripts/query.mjs my-run errors 2                # errors from page 2 only
node scripts/query.mjs my-run hosts                   # top hosts by request count
node scripts/query.mjs my-run host api.example.com    # all requests/responses for a host
node scripts/query.mjs my-run summary                 # full summary.json

En segundo plano, simplemente lee cdp/summary.json y el cdp/pages// árbol; no dudes en saltártelo utilizando el código en bruto jq/rg una vez que conozcas la estructura.

Recetas de recorrido en orden ascendente

# All failed network requests (use jq -c to keep it line-delimited)
jq -c '.params' .o11y//cdp/network/failed.jsonl

# Find requests to a specific host
jq -c 'select(.params.request.url | test("api\\.example\\.com"))' \
  .o11y//cdp/network/requests.jsonl

# 4xx/5xx responses
jq -c 'select(.params.response.status >= 400)
       | {status: .params.response.status, url: .params.response.url}' \
  .o11y//cdp/network/responses.jsonl

# Console errors only
jq -c 'select(.params.type == "error")' .o11y//cdp/console/logs.jsonl

# Sequence of URLs visited
jq -r '.params.frame.url' .o11y//cdp/page/navigations.jsonl

# Find the screenshot taken closest to a timestamp (e.g., when an exception fired)
ls .o11y//screenshots/ | sort | awk -v t=20260427T1714123NZ '
  $0 >= t { print; exit }'

Consulta REFERENCE.md para ver la biblioteca completa de recetas de jq y un mapa de bisección método por método. Consulta EXAMPLES.md para ver escenarios de depuración de principio a fin.

Buenas prácticas

1. Utiliza bb-capture.mjs en Browserbase: garantiza --keep-alive, obtiene la connectUrl, captura la URL del depurador y estampa el manifiesto. Hacerlo manualmente invita a cometer errores.
2. No utilices `--release` en una sesión que no te pertenezca: bb-finalize.mjs --release es para sesiones que hayas creado con --new. Al conectarte a una sesión de producción mediante bb-capture.mjs , ejecuta bb-finalize.mjs sin --release para que la automatización original siga ejecutándose.
3. El orden es importante para el modo remoto: en Browserbase, conecta el cliente de automatización principal antes (o al mismo tiempo que) el rastreador, y crea la sesión con --keep-alive. De lo contrario, la sesión finalizará tan pronto como se cierre el WS del rastreador.
4. No realices sondeos a intervalos inferiores a ~1 s: cada muestra ejecuta comandos de lectura de la CLI del navegador y realiza capturas de pantalla de Chrome. 2 s es un buen valor por defecto.
5. Elige los dominios con cuidado: los predeterminados (Network Console Runtime Log Page) cubren la mayor parte de la depuración. Añade DOM para las mutaciones del árbol DOM (muy ruidosas) mediante O11Y_DOMAINS="$O11Y_DOMAINS DOM".
6. Reutiliza una sesión de Browserbase para el cliente de automatización remoto conectándote a connectUrl con browse open ... --cdp "$CONNECT_URL" --session . El --session indicador designa el demonio de navegación local; no es un indicador de conexión a una sesión de Browserbase.
7. Ejecuta siempre «stop-capture.mjs», incluso tras un fallo, para que los procesos en segundo plano no permanezcan activos y el manifiesto se stopped_at.
8. Realiza una bisección una vez por ejecución: bisect-cdp.mjs es idempotente: sobrescribe los archivos por compartimento desde raw.ndjson cada vez.

Solución de problemas

• de browse cdp exited immediately: suele significar que no se puede acceder al destino (puerto incorrecto) o que la sesión de Browserbase ya ha finalizado. Para el modo remoto, compruébalo con browse cloud sessions get — si status es COMPLETED, vuelve a crearla con --keep-alive y conecta primero la automatización.
• raw.ndjson vacío aunque los procesos se estén ejecutando: confirma que un cliente CDP esté controlando realmente la página. El rastreador solo emite eventos que genera el navegador, por lo que un navegador inactivo produce unas 5 líneas de mensajes de conexión/detección y nada más.
• Todas las capturas de pantalla parecen idénticas: comprueba index.jsonl — si url no cambia, la página aún no ha navegado. El bucle de sondeo se ejecuta independientemente del ritmo de la automatización principal.
• La sesión de Browserbase finaliza a mitad de la ejecución: probablemente se haya alcanzado --timeout. Vuelve a crearla con un tiempo de espera mayor (BB_SESSION_TIMEOUT=1800 node scripts/bb-capture.mjs --new ...) o elimina el indicador de tiempo de espera.
• bb-capture.mjs indica «not RUNNING»: la sesión a la que intentabas conectarte ha finalizado. Enumera las opciones con browse cloud sessions list | jq '.[] | select(.status == "RUNNING")' y vuelve a intentarlo.
• browserbase/logs.json está vacío []: es lo esperado — browse cloud sessions logs es escaso en la práctica. El flujo de datos de CDP en cdp/raw.ndjson es la fuente de referencia.
• ¿Dónde está la grabación de la sesión (rrweb)?: la obtención de artefactos de reproducción de sesiones está obsoleta; esta habilidad no los recupera. Utiliza el flujo de capturas de pantalla en screenshots/ y los volcados de DOM en dom/.

Para consultar la referencia completa, véase REFERENCE.md. Para ver ejemplos de ejecuciones de depuración, véase EXAMPLES.md.