browser-trace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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 the

browser

skill,

browse

, Stagehand, Playwright, or anything else that speaks CDP.

为已由主自动化程序驱动的浏览器会话附加一个只读的第二个CDP客户端。该跟踪工具会将完整的DevTools事件流记录为NDJSON格式，同时并行轮询截图和DOM转储，并将所有内容分割为bash工具可搜索的目录树结构。

此技能不会驱动页面——它仅负责监听。可与

browser

技能、

browse

、Stagehand、Playwright或任何支持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

browser

skill instead.

用户需要调试浏览器自动化运行任务（如表单提交失败、元素缺失、导航挂起、JS异常）。
用户正在运行自动化任务，希望在不重启的情况下中途附加跟踪工具。
用户希望将CDP事件流分割为网络/控制台/DOM/页面分组。
用户希望获取随时间变化的截图+DOM快照，并按时间戳与CDP事件关联。

如果用户仅需要驱动浏览器，请使用

browser

技能。

Setup check

安装检查

bash

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

Verify

browse cdp

exists:

bash

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

bash

node --version                                  # 需要Node 18+版本
which browse || npm install -g browse
which jq     || true                                # 可选——仅用于临时查询

验证

browse cdp

是否存在：

bash

browse --help | grep -q "^\s*cdp " || echo "browse cdp不可用——请更新browse"

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:

Firehose:
```
browse cdp <target>
```
streams every CDP event as one JSON object per line to
```
cdp/raw.ndjson
```
.
Sampler: a polling loop calls
```
browse screenshot --cdp <target> --path <file>
```
and
```
browse get html body --cdp <target>
```
on an interval (default 2s). The helper passes
```
--cdp
```
when it samples so it can attach to the traced target from its own process; once a browse daemon session is attached to a CDP target, follow-up commands in that session do not need to repeat
```
--cdp
```
.
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.

每个Chrome DevTools目标都支持多个并发CDP客户端。主自动化程序是一个客户端；此技能会添加第二个客户端，仅启用观测域（Network、Console、Runtime、Log、Page），且从不发送操作命令。

跟踪器包含三个部分：

事件流（Firehose）：
```
browse cdp <target>
```
将每个CDP事件以单行JSON对象的形式流式传输到
```
cdp/raw.ndjson
```
。
采样器（Sampler）：轮询循环按指定时间间隔（默认2秒）调用
```
browse screenshot --cdp <target> --path <file>
```
和
```
browse get html body --cdp <target>
```
。采样时辅助工具会传递
```
--cdp
```
参数，以便从自身进程附加到被跟踪的目标；一旦browse守护进程会话附加到CDP目标，该会话中的后续命令无需重复
```
--cdp
```
参数。
分割器（Bisector）：运行结束后，
```
bisect-cdp.mjs
```
会遍历
```
raw.ndjson
```
一次，将其分割为按CDP方法分组的JSONL文件，并使用顶层
```
Page.frameNavigated
```
事件作为边界，进一步按页面分割内容。

Quickstart

快速开始

Local Chrome

本地Chrome浏览器

bash

undefined

bash

undefined

1. Launch Chrome with a debugger port (any user-data-dir keeps it isolated).

1. 启动带有调试端口的Chrome浏览器（使用独立的user-data-dir保持隔离）。

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
--remote-debugging-port=9222
--user-data-dir=/tmp/chrome-o11y
about:blank &

2. Start the tracer.

2. 启动跟踪器。

node scripts/start-capture.mjs 9222 my-run

3. Run your main automation against port 9222.

3. 针对9222端口运行主自动化程序。

browse open https://example.com --cdp 9222

...whatever the run does...

...执行自动化任务...

4. Stop and bisect.

4. 停止并分割跟踪数据。

node scripts/stop-capture.mjs my-run node scripts/bisect-cdp.mjs my-run

undefined

node scripts/stop-capture.mjs my-run node scripts/bisect-cdp.mjs my-run

undefined

Browserbase remote

Browserbase远程浏览器

Two helpers wrap the platform-side bookkeeping:

bb-capture.mjs

creates or attaches to a session and starts the tracer;

bb-finalize.mjs

pulls platform artifacts (final session metadata, server logs, downloads) into the run dir at the end.

Browserbase ends a session as soon as its last CDP client disconnects. Create with
--keep-alive
, then attach automation to the session's
connectUrl
before or together with the tracer.
bb-capture.mjs --new
handles the keep-alive session and tracer setup; your automation still needs to attach.

bash

export BROWSERBASE_API_KEY=...

两个辅助工具封装了平台端的记录工作：

bb-capture.mjs

用于创建或附加到会话并启动跟踪器；

bb-finalize.mjs

在结束时将平台制品（最终会话元数据、服务器日志、下载文件）拉取到运行目录中。

当最后一个CDP客户端断开连接时，Browserbase会立即结束会话。创建会话时使用
--keep-alive
参数，然后在启动跟踪器之前或同时将自动化程序附加到会话的
connectUrl
。
bb-capture.mjs --new
会处理保活会话和跟踪器设置；你的自动化程序仍需附加到会话。

bash

export BROWSERBASE_API_KEY=...

1. Create a keep-alive session AND start the tracer in one step.

1. 一步完成创建保活会话并启动跟踪器。

Prints the session id, connectUrl prefix, and a live debugger URL you

打印会话ID、connectUrl前缀以及可在浏览器中打开的实时调试URL，

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.

2. 运行自动化程序。bb-capture已将会话ID标记到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.

3. 停止跟踪器、分割数据，然后拉取平台制品并释放会话。

node scripts/stop-capture.mjs my-run node scripts/bisect-cdp.mjs my-run node scripts/bb-finalize.mjs my-run --release


Attaching to a session that's *already running* (e.g. one your production worker created) — `bb-capture.mjs` accepts a session id instead of `--new`:

```bash

node scripts/stop-capture.mjs my-run node scripts/bisect-cdp.mjs my-run node scripts/bb-finalize.mjs my-run --release


附加到**已在运行**的会话（例如生产worker创建的会话）——`bb-capture.mjs`接受会话ID而非`--new`参数：

```bash

Pick a running session (filter client-side; browse cloud sessions list has no --status flag)

选择一个正在运行的会话（客户端过滤；browse cloud sessions list没有--status标志）

browse cloud sessions list | jq -r '.[] | select(.status == "RUNNING") | .id'

node scripts/bb-capture.mjs <session-id> mid-flight-debug

browse cloud sessions list | jq -r '.[] | select(.status == "RUNNING") | .id'

node scripts/bb-capture.mjs <session-id> 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

undefined

node scripts/stop-capture.mjs mid-flight-debug node scripts/bisect-cdp.mjs mid-flight-debug node scripts/bb-finalize.mjs mid-flight-debug # 不带--release：保持会话运行

undefined

What you get from the Browserbase platform

从Browserbase平台获取的内容

bb-capture.mjs

adds a

browserbase

block to

manifest.json

(session id, project, region, started_at, expires_at, debugger URL).

bb-finalize.mjs

writes:

```
<run>/browserbase/session.json
```
— final
```
browse cloud sessions get
```
snapshot (proxyBytes, status, ended_at, viewport, …)
```
<run>/browserbase/logs.json
```
—
```
browse cloud sessions logs
```
output. Often empty. The CDP firehose in
```
cdp/raw.ndjson
```
is the source of truth; this is a side channel.
```
<run>/browserbase/downloads.zip
```
— files the session downloaded, if any (the script discards the empty 22-byte zip you get when there are none)

Session replay artifact fetching is deprecated and isn't fetched. Use the screenshots + DOM dumps in

screenshots/

and

dom/

for visual ground truth.

The live

debugger_url

in the manifest opens an interactive Chrome DevTools view served by Browserbase — handy for watching a long-running automation while the tracer captures the firehose to disk.

bb-capture.mjs

会在

manifest.json

中添加一个

browserbase

块：包含会话ID、项目、区域、启动时间、过期时间、调试URL。

bb-finalize.mjs

会写入：

```
<run>/browserbase/session.json
```
——
```
browse cloud sessions get
```
的最终快照（proxyBytes、状态、结束时间、视口等）
```
<run>/browserbase/logs.json
```
——
```
browse cloud sessions logs
```
的输出。通常为空。
```
cdp/raw.ndjson
```
中的CDP事件流是真实数据源；这只是一个辅助渠道。
```
<run>/browserbase/downloads.zip
```
—— 会话下载的文件（如果有；脚本会丢弃无文件时生成的22字节空压缩包）

会话重放制品的获取已被弃用，不会被拉取。请使用

screenshots/

中的截图和

dom/

中的DOM转储作为视觉依据。

manifest中的实时

debugger_url

会打开由Browserbase提供的交互式Chrome DevTools视图——便于在跟踪器将事件流捕获到磁盘时，查看长时间运行的自动化任务。

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

When a run was started via

bb-capture.mjs

manifest.json

also carries a top-level

browserbase

block:

session_id

project_id

region

started_at

expires_at

keep_alive

debugger_url

.o11y/<run-id>/
  manifest.json                 运行元数据：目标、域、启动时间、停止时间
  index.jsonl                   每个采样对应一行：{ts, screenshot, dom, url}
  cdp/
    raw.ndjson                  完整CDP事件流（每行一个JSON对象）
    summary.json                {sessionId, duration, totalEvents, pages[]} —— 结构如下
    network/{requests,responses,finished,failed,websocket}.jsonl   会话级分组（始终生成）
    console/{logs,exceptions}.jsonl
    runtime/all.jsonl
    log/entries.jsonl
    page/{navigations,lifecycle,frames,dialogs,all}.jsonl
    dom/all.jsonl                                                  （仅当O11Y_DOMAINS包含DOM时生成）
    target/{attached,detached}.jsonl
    pages/                      按页面分割的内容，以顶层frameNavigated事件为边界索引
      000/                      第一个具体页面
        url.txt                 此页面的URL
        summary.json            此页面的域/网络/计时块（结构与pages[]条目相同）
        raw.jsonl               限定于此页面的事件流
        network/, console/, page/, runtime/, log/, target/, dom/    相同分组，仅生成非空文件
  screenshots/<iso-ts>.png      每个采样间隔对应一张PNG截图
  dom/<iso-ts>.html             每个采样间隔对应一份HTML转储
  browserbase/                  仅在Browserbase运行时由bb-finalize.mjs添加
    session.json                `browse cloud sessions get`的最终快照（proxyBytes、状态、结束时间等）
    logs.json                   `browse cloud sessions logs`的输出（通常为[]）
    downloads.zip               `browse cloud sessions downloads get`的输出（仅当会话有下载文件时生成）

当通过

bb-capture.mjs

启动运行时，

manifest.json

还会包含顶层

browserbase

块：

session_id

、

project_id

、

region

、

started_at

、

expires_at

、

keep_alive

、

debugger_url

。

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

startMs

endMs

durationMs

are wall-clock ms, derived from

manifest.started_at

plus the offset of each event's CDP monotonic timestamp.

domains[*]

only includes

errors

warnings

keys when non-zero.

cdp/summary.json

是任何分析的入口点：它包含会话级别的统计数据，以及按顶层

Page.frameNavigated

事件索引的

pages[]

数组。每页条目按导航顺序生成（页面0 = 第一个具体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 } }
    }
  ]
}

startMs

endMs

durationMs

是挂钟时间（毫秒），由

manifest.started_at

加上每个事件的CDP单调时间戳偏移量计算得出。仅当

errors

warnings

非零时，

domains[*]

才会包含这些键。

Drilling in with

query.mjs

使用

query.mjs

深入分析

For interactive exploration, use

scripts/query.mjs <run-id> <command>

instead of remembering paths:

bash

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

Behind the scenes it just reads

cdp/summary.json

and the

cdp/pages/<pid>/

tree — feel free to bypass it with raw

jq

rg

once you know the shape.

对于交互式探索，使用

scripts/query.mjs <run-id> <command>

代替手动记忆路径：

bash

node scripts/query.mjs my-run list                    页面的单行表格
node scripts/query.mjs my-run page 1                  页面1的完整摘要
node scripts/query.mjs my-run page 1 network/failed   页面1的failed.jsonl内容
node scripts/query.mjs my-run errors                  所有页面的错误，按页面ID归类
node scripts/query.mjs my-run errors 2                仅页面2的错误
node scripts/query.mjs my-run hosts                   按请求数排序的顶级主机
node scripts/query.mjs my-run host api.example.com    某主机的所有请求/响应
node scripts/query.mjs my-run summary                 完整的summary.json内容

它实际上只是读取

cdp/summary.json

和

cdp/pages/<pid>/

目录结构——熟悉结构后，你可以直接使用

jq

rg

绕过它。

Top traversal recipes

常用遍历示例

bash

undefined

bash

undefined

All failed network requests (use jq -c to keep it line-delimited)

所有失败的网络请求（使用jq -c保持行分隔格式）

jq -c '.params' .o11y/<run>/cdp/network/failed.jsonl

Find requests to a specific host

查找特定主机的请求

jq -c 'select(.params.request.url | test("api\.example\.com"))'
.o11y/<run>/cdp/network/requests.jsonl

4xx/5xx responses

4xx/5xx响应

jq -c 'select(.params.response.status >= 400) | {status: .params.response.status, url: .params.response.url}'
.o11y/<run>/cdp/network/responses.jsonl

Console errors only

仅控制台错误

jq -c 'select(.params.type == "error")' .o11y/<run>/cdp/console/logs.jsonl

Sequence of URLs visited

访问过的URL序列

jq -r '.params.frame.url' .o11y/<run>/cdp/page/navigations.jsonl

Find the screenshot taken closest to a timestamp (e.g., when an exception fired)

查找最接近某个时间戳的截图（例如异常触发时）

ls .o11y/<run>/screenshots/ | sort | awk -v t=20260427T1714123NZ ' $0 >= t { print; exit }'


See **REFERENCE.md** for the full jq recipe library and a method-by-method bisect map. See **EXAMPLES.md** for end-to-end debug scenarios.

ls .o11y/<run>/screenshots/ | sort | awk -v t=20260427T1714123NZ ' $0 >= t { print; exit }'


完整的jq示例库和按方法分割的映射请参见**REFERENCE.md**。端到端调试场景请参见**EXAMPLES.md**。

Best practices

最佳实践

Use
bb-capture.mjs
on Browserbase: it enforces
```
--keep-alive
```
, fetches the connectUrl, captures the debugger URL, and stamps the manifest. Doing it manually invites mistakes.
Don't
--release
a session you don't own:
```
bb-finalize.mjs --release
```
is for sessions you created with
```
--new
```
. When attaching to a production session via
```
bb-capture.mjs <session-id>
```
, run
```
bb-finalize.mjs
```
without
```
--release
```
so the original automation keeps running.
Order matters for remote: on Browserbase, attach the main automation client before (or together with) the tracer, and create the session with
```
--keep-alive
```
. Otherwise the session ends as soon as the tracer's WS closes.
Don't poll faster than ~1s: each sample runs browser CLI read commands and screenshots Chrome. 2s is a good default.
Pick domains deliberately: defaults (
```
Network Console Runtime Log Page
```
) cover most debugging. Add
```
DOM
```
for DOM-tree mutations (very noisy) via
```
O11Y_DOMAINS="$O11Y_DOMAINS DOM"
```
.
Reuse one Browserbase session for the automation client on remote by attaching to that session's
```
connectUrl
```
with
```
browse open ... --cdp "$CONNECT_URL" --session <name>
```
. The
```
--session
```
flag names the local browse daemon; it is not a Browserbase session attach flag.
Always run
stop-capture.mjs
, even after a crash, so background processes don't linger and the manifest gets
```
stopped_at
```
.
Bisect once per run:
```
bisect-cdp.mjs
```
is idempotent — it overwrites the per-bucket files from
```
raw.ndjson
```
each time.

在Browserbase上使用
bb-capture.mjs
：它会强制执行
```
--keep-alive
```
、获取connectUrl、捕获调试URL并标记manifest。手动操作容易出错。
不要
--release
不属于你的会话：
```
bb-finalize.mjs --release
```
仅适用于你用
```
--new
```
创建的会话。当通过
```
bb-capture.mjs <session-id>
```
附加到生产会话时，运行
```
bb-finalize.mjs
```
时不要加
```
--release
```
，以便原自动化程序继续运行。
远程环境下顺序很重要：在Browserbase上，先附加主自动化客户端（或与跟踪器同时附加），并使用
```
--keep-alive
```
创建会话。否则，跟踪器的WebSocket关闭后会话会立即结束。
轮询间隔不要快于~1秒：每个采样都会运行浏览器CLI读取命令和截图操作。2秒是合适的默认值。
谨慎选择域：默认值（Network Console Runtime Log Page）覆盖大多数调试场景。若需要DOM树变更跟踪（非常嘈杂），可通过
```
O11Y_DOMAINS="$O11Y_DOMAINS DOM"
```
添加
```
DOM
```
域。
远程环境下复用同一个Browserbase会话：通过
```
browse open ... --cdp "$CONNECT_URL" --session <name>
```
附加到该会话的
```
connectUrl
```
。
```
--session
```
标志用于命名本地browse守护进程，并非Browserbase会话附加标志。
始终运行
stop-capture.mjs
：即使崩溃后也要运行，避免后台进程残留，并为manifest添加
```
stopped_at
```
字段。
每次运行仅分割一次：
```
bisect-cdp.mjs
```
是幂等的——每次运行都会从
```
raw.ndjson
```
覆盖分组文件。

Troubleshooting

故障排除

browse cdp exited immediately
: usually means the target is unreachable (wrong port) or the Browserbase session has already ended. For remote, verify with
```
browse cloud sessions get <id>
```
— if
```
status
```
is
```
COMPLETED
```
, recreate with
```
--keep-alive
```
and attach automation first.
Empty
raw.ndjson
even though processes are running: confirm a CDP client is actually driving the page. The tracer only emits events that the browser generates, so an idle browser produces ~5 lines of attach/discover messages and nothing else.
Screenshots all look identical: check
```
index.jsonl
```
— if
```
url
```
doesn't change, the page hasn't navigated yet. The polling loop runs independently of the main automation's pace.
Browserbase session ends mid-run: it likely hit
```
--timeout
```
. Recreate with a higher timeout (
```
BB_SESSION_TIMEOUT=1800 node scripts/bb-capture.mjs --new ...
```
) or remove the timeout flag.
bb-capture.mjs <id>
says "not RUNNING": the session you tried to attach to ended. List candidates with
```
browse cloud sessions list | jq '.[] | select(.status == "RUNNING")'
```
and try again.
browserbase/logs.json
is empty
[]
: expected —
```
browse cloud sessions logs
```
is sparse in practice. The CDP firehose in
```
cdp/raw.ndjson
```
is the source of truth.
Where's the session recording (rrweb)?: session replay artifact fetching is deprecated; this skill doesn't fetch it. Use the screenshot stream in
```
screenshots/
```
and DOM dumps in
```
dom/
```
.

For full reference, see REFERENCE.md. For example debug runs, see EXAMPLES.md.

browse cdp exited immediately
：通常意味着目标不可达（端口错误）或Browserbase会话已结束。对于远程会话，使用
```
browse cloud sessions get <id>
```
验证——如果
```
status
```
为
```
COMPLETED
```
，请使用
```
--keep-alive
```
重新创建并先附加自动化程序。
进程运行但
raw.ndjson
为空：确认CDP客户端确实在驱动页面。跟踪器仅会输出浏览器生成的事件，因此空闲浏览器只会生成约5行附加/发现消息，无其他内容。
所有截图看起来都一样：检查
```
index.jsonl
```
——如果
```
url
```
没有变化，说明页面尚未导航。轮询循环独立于主自动化程序的运行节奏。
Browserbase会话中途结束：可能是触发了
```
--timeout
```
。使用更高的超时时间重新创建（
```
BB_SESSION_TIMEOUT=1800 node scripts/bb-capture.mjs --new ...
```
）或移除超时标志。
bb-capture.mjs <id>
提示"not RUNNING"：你尝试附加的会话已结束。使用
```
browse cloud sessions list | jq '.[] | select(.status == "RUNNING")'
```
列出候选会话并重试。
browserbase/logs.json
为空
[]
：这是正常情况——
```
browse cloud sessions logs
```
在实际使用中内容很少。
```
cdp/raw.ndjson
```
中的CDP事件流是真实数据源。
会话录制（rrweb）在哪里？：会话重放制品的获取已被弃用；此技能不会拉取它。请使用
```
screenshots/
```
中的截图流和
```
dom/
```
中的DOM转储。

完整参考请参见REFERENCE.md。示例调试运行请参见EXAMPLES.md。

browser-trace

Original

Translation

Browser Trace

浏览器跟踪

When to use

使用场景

Setup check

安装检查

How it works

工作原理

Quickstart

快速开始

Local Chrome

本地Chrome浏览器

1. Launch Chrome with a debugger port (any user-data-dir keeps it isolated).

1. 启动带有调试端口的Chrome浏览器（使用独立的user-data-dir保持隔离）。

2. Start the tracer.

2. 启动跟踪器。

3. Run your main automation against port 9222.

3. 针对9222端口运行主自动化程序。

...whatever the run does...

...执行自动化任务...

4. Stop and bisect.

4. 停止并分割跟踪数据。

Browserbase remote

Browserbase远程浏览器

1. Create a keep-alive session AND start the tracer in one step.

1. 一步完成创建保活会话并启动跟踪器。

Prints the session id, connectUrl prefix, and a live debugger URL you

打印会话ID、connectUrl前缀以及可在浏览器中打开的实时调试URL，

can open in a browser to watch the run interactively.

用于交互式查看运行过程。

2. Drive automation. bb-capture stamped the session id into the manifest.

2. 运行自动化程序。bb-capture已将会话ID标记到manifest中。

3. Stop the tracer, bisect, then pull platform artifacts and release.

3. 停止跟踪器、分割数据，然后拉取平台制品并释放会话。

Pick a running session (filter client-side; browse cloud sessions list has no --status flag)

选择一个正在运行的会话（客户端过滤；browse cloud sessions list没有--status标志）

...tracer runs alongside the existing automation client; no disruption...

...跟踪器与现有自动化客户端并行运行；无干扰...

What you get from the Browserbase platform

从Browserbase平台获取的内容

Filesystem layout

文件系统结构

Summary shape

摘要结构

Drilling in with query.mjs

使用query.mjs深入分析

Top traversal recipes

常用遍历示例

All failed network requests (use jq -c to keep it line-delimited)

所有失败的网络请求（使用jq -c保持行分隔格式）

Find requests to a specific host

查找特定主机的请求

4xx/5xx responses

4xx/5xx响应

Console errors only

仅控制台错误

Sequence of URLs visited

访问过的URL序列

Find the screenshot taken closest to a timestamp (e.g., when an exception fired)

查找最接近某个时间戳的截图（例如异常触发时）

Best practices

最佳实践

Troubleshooting

故障排除

Drilling in with
`query.mjs`

使用
`query.mjs`
深入分析