Трассировка браузера

Подключите второй клиент CDP, доступный только для чтения, к сеансу браузера, который уже управляется вашей основной системой автоматизации. Трейс записывает весь поток данных DevTools в формат NDJSON, параллельно опрашивает скриншоты и дампы DOM, а также разбивает все на дерево каталогов, в котором инструменты bash могут выполнять поиск.

Этот навык не управляет страницами — он только прослушивает. Используйте его в паре с навыком browser навыком browse, Stagehand, Playwright или любым другим инструментом, поддерживающим CDP.

Когда использовать

• Пользователь хочет отладить запуск браузерной автоматизации (неработающая форма, отсутствующий элемент, зависшая навигация, исключение JS).
• У пользователя запущена автоматизация, и он хочет подключить трассировку в процессе работы, не перезапуская её.
• Пользователь хочет разделить поток данных CDP на категории: сеть / консоль / DOM / страница.
• Пользователь хочет получать скриншоты и снимки DOM в динамике, привязанные к событиям CDP по временным меткам.

Если пользователь просто хочет управлять браузером, лучше использовать browser этот навык.

Проверка настроек

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

Убедитесь, что browse cdp существует:

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

Как это работает

Каждая цель Chrome DevTools поддерживает несколько одновременно работающих клиентов CDP. Ваша основная автоматизация представляет собой одного клиента; данный навык добавляет второго, который активирует только домены наблюдения (Сеть, Консоль, Время выполнения, Журнал, Страница) и никогда не отправляет команды действий.

Трейсер состоит из трёх частей:

1. Firehose: browse cdp транслирует каждое событие CDP в виде одного JSON-объекта в строке в cdp/raw.ndjson.
2. Sampler: цикл опроса вызывает browse screenshot --cdp --path и browse get html body --cdp с определенным интервалом (по умолчанию 2 с). Вспомогательная программа передает --cdp момент выборки, чтобы иметь возможность подключиться к отслеживаемому объекту из собственного процесса; как только сессия демона просмотра подключается к объекту CDP, последующие команды в этой сессии не нужно повторять --cdp.
3. Bisector: после завершения выполнения bisect-cdp.mjs проходит raw.ndjson один раз, разбивает его на файлы JSONL по корзинам с ключами по методам CDP, а также делит каждую страницу пополам, используя события верхнего уровня Page.frameNavigated событиями верхнего уровня в качестве границ.

Краткое руководство

Локальный Chrome

# 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 удалённый

Две вспомогательные функции обёртывают ведение учёта на стороне платформы: bb-capture.mjs создаёт сессию или присоединяется к ней и запускает трассировщик; bb-finalize.mjs в конце переносит артефакты платформы (окончательные метаданные сеанса, журналы сервера, загрузки) в каталог запуска.

Browserbase завершает сессию, как только отключается последний клиент CDP. Создайте сессию с помощью --keep-alive, затем присоедините автоматизацию к сессии connectUrl до запуска трассера или одновременно с ним. bb-capture.mjs --new он занимается настройкой сеанса keep-alive и трассера; ваша автоматизация по-прежнему должна быть присоединена.

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

Подключение к уже запущенной сессии (например, к той, которую создал ваш производственный работник) — bb-capture.mjs принимает идентификатор сеанса вместо --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

Что вы получаете от платформы Browserbase

bb-capture.mjs добавляет browserbase блок к manifest.json (идентификатор сессии, проект, регион, время начала, время окончания, URL отладчика). bb-finalize.mjs записывает:

• /browserbase/session.json — окончательный browse cloud sessions get снимок (proxyBytes, статус, ended_at, viewport, …)
• /browserbase/logs.json — browse cloud sessions logs вывод. Часто пуст. Поток данных CDP в cdp/raw.ndjson является основным источником данных; это — дополнительный канал.
• /browserbase/downloads.zip — файлы, загруженные в ходе сеанса, если таковые имеются (скрипт отбрасывает пустой ZIP-архив размером 22 байта, который вы получаете, когда файлов нет)

Загрузка артефактов воспроизведения сеанса устарела и не производится. Используйте скриншоты + дампы DOM в screenshots/ и dom/ для визуальной проверки достоверности.

Слово «live» debugger_url в манифесте открывает интерактивное окно Chrome DevTools, предоставляемое Browserbase — это удобно для наблюдения за длительно выполняющейся автоматизацией, пока трассировщик записывает поток данных на диск.

Структура файловой системы

.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)

Когда запуск инициировался с помощью bb-capture.mjs, manifest.json также содержит блок верхнего уровня browserbase : session_id, project_id, region, started_at, expires_at, keep_alive, debugger_url.

Фигура «Сводка»

cdp/summary.json является отправной точкой для любого анализа: она содержит итоговые данные на уровне сеанса и pages[] массив, индексированный по элементам верхнего уровня Page.frameNavigated. Записи по страницам выводятся в порядке навигации (страница 0 = первый конкретный URL).

{
  "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 представляют собой время в миллисекундах по часам, полученное из manifest.started_at плюс смещение монотонной временной метки CDP каждого события. domains[*] содержит только errors/warnings ключи, если они не равны нулю.

Углублённый анализ с помощью query.mjs

Для интерактивного изучения используйте scripts/query.mjs вместо того, чтобы запоминать пути:

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

За кулисами просто выполняется чтение cdp/summary.json и cdp/pages// дерево — можете смело обойти это, используя сырые jq/rg , как только вы узнаете его структуру.

Лучшие рецепты обхода

# 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 }'

См. файл REFERENCE.md, где приведена полная библиотека рецептов jq и карта методов с бисекцией. См. файл EXAMPLES.md для сценариев отладки от начала до конца.

Рекомендации

1. Используйте bb-capture.mjs на Browserbase: он обеспечивает --keep-alive, получает connectUrl, фиксирует URL отладчика и проставляет отметку в манифесте. Делать это вручную — значит рисковать ошибками.
2. Не запускайте `--release` для сеанса, которым вы не владеете: bb-finalize.mjs --release предназначен для сеансов, созданных с помощью --new. При подключении к сеансу в производственной среде с помощью bb-capture.mjs , запустите bb-finalize.mjs без --release , чтобы исходная автоматизация продолжала работать.
3. Для удалённого доступа порядок имеет значение: в Browserbase подключите основной клиент автоматизации до (или одновременно с) трассером и создайте сессию с помощью --keep-alive. В противном случае сессия завершится, как только закроется WS трассера.
4. Не запрашивайте данные чаще, чем раз в ~1 с: при каждом опросе выполняются команды чтения из командной строки браузера и делаются скриншоты Chrome. Хорошим значением по умолчанию является 2 с.
5. Выбирайте домены обдуманно: значения по умолчанию (Network Console Runtime Log Page) охватывают большинство случаев отладки. Добавьте DOM для изменений в дереве DOM (очень много шума) через O11Y_DOMAINS="$O11Y_DOMAINS DOM".
6. Используйте один сеанс Browserbase для клиента автоматизации на удаленном компьютере, присоединившись к connectUrl с помощью browse open ... --cdp "$CONNECT_URL" --session . Флаг --session Флаг указывает локальный браузерный демон; это не флаг присоединения к сеансу Browserbase.
7. Всегда запускайте `stop-capture.mjs`, даже после сбоя, чтобы фоновые процессы не затягивались, а манифест stopped_at.
8. Проводите бисекцию один раз за каждый запуск: bisect-cdp.mjs является идемпотентной операцией — она перезаписывает файлы для каждого сегмента из raw.ndjson каждый раз.

Устранение неполадок

• browse cdp exited immediately: обычно означает, что цель недоступна (неверный порт) или сеанс Browserbase уже завершился. Для удаленного доступа проверьте с помощью browse cloud sessions get — если status есть COMPLETED, создайте заново с помощью --keep-alive и сначала подключите автоматизацию.
• Пустой raw.ndjson, хотя процессы запущены: убедитесь, что страницу действительно управляет клиент CDP. Трейсер выдает только события, генерируемые браузером, поэтому простаивающий браузер генерирует ~5 строк сообщений attach/discover и больше ничего.
• Все скриншоты выглядят одинаково: проверьте index.jsonl — если url не меняется, значит, переход по странице ещё не произошёл. Цикл опроса работает независимо от темпа основной автоматизации.
• Сессия Browserbase завершается в середине выполнения: вероятно, произошло превышение --timeout. Создайте сессию заново с более длительным таймаутом (BB_SESSION_TIMEOUT=1800 node scripts/bb-capture.mjs --new ...) или снимите флаг таймаута.
• bb-capture.mjs указывает «not RUNNING»: сессия, к которой вы пытались подключиться, завершилась. Составьте список возможных вариантов с помощью browse cloud sessions list | jq '.[] | select(.status == "RUNNING")' и попробуйте ещё раз.
• browserbase/logs.json [] пуст: это ожидаемо — browse cloud sessions logs на практике является разреженным. Поток данных CDP в cdp/raw.ndjson является достоверным источником информации.
• Где запись сеанса (rrweb)?: извлечение артефактов воспроизведения сеанса устарело; этот с킬 их не извлекает. Используйте поток скриншотов в screenshots/ и дампы DOM в dom/.

Полную справочную информацию см. в файле REFERENCE.md. Примеры отладочных запусков см. в файле EXAMPLES.md.