Browser Trace

すでにメイン自動化に駆動されているブラウザセッションに、2つ目の読み取り専用 CDP クライアントをアタッチします。トレーサーは DevTools フルストリームを NDJSON に記録し、スクリーンショットと DOM ダンプを並列でポーリングし、bash ツールで検索可能なディレクトリツリーにすべてをスライスします。

このスキルはページを駆動しません。リッスンするだけです。browser スキル、bb、Stagehand、Playwright、または CDP を話す他のものと組み合わせて使用します。

使用するタイミング

• ユーザーがブラウザ自動化の実行をデバッグしたい（フォーム失敗、要素の欠落、ナビゲーションのハング、JS 例外）。
• ユーザーが実行中の自動化を持っており、再起動せずにトレースをミッドフライトでアタッチしたい。
• ユーザーが CDP フルストリームをネットワーク / コンソール / DOM / ページバケットに分割したい。
• ユーザーがスクリーンショット + DOM スナップショットを時系列で取得し、タイムスタンプで CDP イベントに結合したい。

ユーザーがブラウザを駆動したいだけの場合は、代わりに browser スキルを使用してください。

セットアップチェック

node --version                                  # Node 18+ が必要
which browse || npm install -g @browserbasehq/browse-cli@alpha
which bb     || npm install -g @browserbasehq/cli   # Browserbase リモートの場合のみ必要
which jq     || true                                # オプション — アドホッククエリの場合のみ使用

browse cdp が存在することを確認（0.5.0-alpha-a4ca430+ で出荷）：

browse --help | grep -q "^\s*cdp " || echo "browse cdp not in this version — install @alpha"

動作原理

すべての Chrome DevTools ターゲットは、複数の同時 CDP クライアントを受け入れます。メイン自動化が 1 つのクライアント。このスキルが 2 つ目を追加し、観測ドメイン（Network、Console、Runtime、Log、Page）のみを有効化し、アクションコマンドは一切送信しません。

トレーサーは 3 つのパーツから構成されます：

1. フルストリーム: browse cdp <target> は、すべての CDP イベントを 1 行 1 JSON オブジェクト形式で cdp/raw.ndjson にストリーミングします。
2. サンプラー: ポーリングループが一定間隔（デフォルト 2 秒）で browse --ws <target> screenshot と browse --ws <target> get html body を呼び出します。--ws はワンショットで、デーモンをバイパスするため、メイン自動化と競合しません。
3. バイセクター: 実行後、bisect-cdp.mjs は raw.ndjson を 1 回走査し、CDP メソッドをキーとしたバケットごとの JSONL ファイルにスライスし、さらにトップレベルの Page.frameNavigated イベントを境界として、ページごとにバイセクトします。

クイックスタート

ローカル Chrome

# 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. トレーサーを開始。
node scripts/start-capture.mjs 9222 my-run

# 3. ポート 9222 に対してメイン自動化を実行。
browse env local 9222
browse open https://example.com
# ...実行が何をしようとも...

# 4. 停止してバイセクト。
node scripts/stop-capture.mjs my-run
node scripts/bisect-cdp.mjs my-run

Browserbase リモート

2 つのヘルパーがプラットフォーム側の記帳をラップします：bb-capture.mjs がセッションを作成またはアタッチしてトレーサーを開始し、bb-finalize.mjs は実行終了時にプラットフォームアーティファクト（最終セッションメタデータ、サーバーログ、ダウンロード）を実行ディレクトリにプルします。

Browserbase はセッションの最後の CDP クライアントが切断されるとすぐにセッションを終了します。常に --keep-alive で作成し、トレーサーの前（または一緒に）自動化クライアントをアタッチしてください。 bb-capture.mjs --new はこれを自動で行います。

export BROWSERBASE_API_KEY=...

# 1. keep-alive セッションを作成し、1 ステップでトレーサーを開始。
#    セッション id、connectUrl プレフィックス、およびブラウザで開いて
#    実行を対話的に監視できるライブデバッガ URL を出力します。
node scripts/bb-capture.mjs --new my-run

# 2. 自動化を駆動。bb-capture がセッション id をマニフェストにスタンプします。
SID=$(jq -r .browserbase.session_id .o11y/my-run/manifest.json)
browse --connect "$SID" open https://example.com
browse --connect "$SID" open https://news.ycombinator.com

# 3. トレーサーを停止、バイセクト、プラットフォームアーティファクトをプルしてリリース。
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 の代わりにセッション id を受け入れます：

# 実行中のセッションを選択（クライアント側でフィルタリング; bb sessions list に --status フラグがない）
bb sessions list | jq -r '.[] | select(.status == "RUNNING") | .id'

node scripts/bb-capture.mjs <session-id> mid-flight-debug
# ...トレーサーが既存の自動化クライアント と並行実行；中断なし...
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 なし：セッションを実行中のままに

Browserbase プラットフォームから取得するもの

bb-capture.mjs は manifest.json に browserbase ブロックを追加します（セッション id、プロジェクト、リージョン、started_at、expires_at、デバッガ URL）。bb-finalize.mjs は以下を書き込みます：

• <run>/browserbase/session.json — 最終 bb sessions get スナップショット（proxyBytes、status、ended_at、viewport、…）
• <run>/browserbase/logs.json — bb sessions logs 出力。多くの場合空。 cdp/raw.ndjson の CDP フルストリームが情報源です；これはサイドチャネルです。
• <run>/browserbase/downloads.zip — セッションがダウンロードしたファイル（あれば）。スクリプトはダウンロードがない場合に取得する空の 22 バイト zip を破棄します。

bb sessions recording（rrweb セッションリプレイ）は廃止されており、フェッチされません。ビジュアル情報源としての真実には、screenshots/ と dom/ のスクリーンショット + DOM ダンプを使用してください。

マニフェスト内のライブ debugger_url は、Browserbase により提供される対話型 Chrome DevTools ビューを開きます — トレーサーがディスクにフルストリームをキャプチャしている間、長時間実行の自動化を監視するのに便利です。

ファイルシステムレイアウト

.o11y/<run-id>/
  manifest.json                 実行メタデータ：target、domains、started_at、stopped_at
  index.jsonl                   サンプルあたり 1 行：{ts, screenshot, dom, url}
  cdp/
    raw.ndjson                  完全な CDP フルストリーム（1 行 1 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/                  bb-finalize.mjs により追加（Browserbase 実行のみ）
    session.json                最終 `bb sessions get` スナップショット（proxyBytes、status、ended_at、…）
    logs.json                   `bb sessions logs` 出力（多くの場合 []）
    downloads.zip               `bb sessions downloads get` 出力（セッションがファイルをダウンロードした場合のみ）

実行が bb-capture.mjs 経由で開始された場合、manifest.json はトップレベルの browserbase ブロックも携帯します：session_id、project_id、region、started_at、expires_at、keep_alive、debugger_url。

サマリーシェイプ

cdp/summary.json はあらゆる分析のエントリーポイントです：セッションレベルの合計と、トップレベルの Page.frameNavigated でインデックス付けされた pages[] 配列があります。ページごとのエントリはナビゲーション順で発行されます（ページ 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 は wall-clock ミリ秒で、manifest.started_at プラス各イベントの CDP 単調タイムスタンプオフセットから導出されます。domains[*] は、ゼロ以外の場合のみ errors/warnings キーを含みます。

query.mjs でドリルイン

対話型の探索には、パスを覚える代わりに scripts/query.mjs <run-id> <command> を使用してください：

node scripts/query.mjs my-run list                    # ページの 1 行テーブル
node scripts/query.mjs my-run page 1                  # ページ 1 の完全なサマリー
node scripts/query.mjs my-run page 1 network/failed   # ページ 1 の failed.jsonl を cat
node scripts/query.mjs my-run errors                  # ページ全体のすべてのエラー、pid で属性付け
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 でバイパスしても構いません。

トップ走査レシピ

# すべての失敗したネットワークリクエスト（jq -c で行区切り状態を保つ）
jq -c '.params' .o11y/<run>/cdp/network/failed.jsonl

# 特定のホストへのリクエストを検索
jq -c 'select(.params.request.url | test("api\\.example\\.com"))' \
  .o11y/<run>/cdp/network/requests.jsonl

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

# コンソールエラーのみ
jq -c 'select(.params.type == "error")' .o11y/<run>/cdp/console/logs.jsonl

# 訪問した URL のシーケンス
jq -r '.params.frame.url' .o11y/<run>/cdp/page/navigations.jsonl

# タイムスタンプに最も近く撮影されたスクリーンショットを検索（例：例外が発火した時）
ls .o11y/<run>/screenshots/ | sort | awk -v t=20260427T1714123NZ '
  $0 >= t { print; exit }'

完全な jq レシピライブラリとメソッド別バイセクトマップは REFERENCE.md を参照してください。エンドツーエンドのデバッグシナリオは EXAMPLES.md を参照してください。

ベストプラクティス

1. Browserbase で bb-capture.mjs を使用：--keep-alive を強制し、connectUrl をフェッチし、デバッガ URL をキャプチャし、マニフェストをスタンプします。手動で行うとミスが招きやすいです。
2. 所有していないセッションを --release しない：bb-finalize.mjs --release はあなたが --new で作成したセッション用です。bb-capture.mjs <session-id> 経由で本番セッションにアタッチする場合、bb-finalize.mjs を --release なしで実行し、元の自動化が実行中のままになるようにしてください。
3. リモートではオーダーが重要：Browserbase では、トレーサーの前（または一緒に）メイン自動化クライアントをアタッチし、--keep-alive でセッションを作成してください。そうしないと、トレーサーの WS が閉じるとセッションが終了します。
4. ~1 秒より速くポーリングしない：各サンプルはワンショット CDP 接続を開き、Chrome をスクリーンショットします。2 秒は良いデフォルトです。
5. ドメインを意識的に選択：デフォルト（Network Console Runtime Log Page）はほとんどのデバッグを網羅します。O11Y_DOMAINS="$O11Y_DOMAINS DOM" 経由で、DOM ツリー変異のために DOM を追加してください（非常にノイジー）。
6. リモートで自動化クライアントに --connect <session-id> を使用、新しい browse env remote ではありません（毎回新しいセッションが作成されます）。
7. クラッシュ後でも常に stop-capture.mjs を実行、バックグラウンドプロセスがリンガーにならず、マニフェストに stopped_at が取得されるようにしてください。
8. 実行ごとに 1 回バイセクト：bisect-cdp.mjs はべき等 — 毎回 raw.ndjson からバケットごとのファイルを上書きします。

トラブルシューティング

• browse cdp exited immediately：通常はターゲットに到達不可（ポート間違い）または Browserbase セッションがすでに終了していることを意味します。リモートの場合、bb 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" と言う：アタッチしようとしたセッションが終了しています。bb sessions list | jq '.[] | select(.status == "RUNNING")' で候補をリストし、再度試してください。
• browserbase/logs.json が空 []：予想通り — bb sessions logs は実際にはまばら。cdp/raw.ndjson の CDP フルストリームが情報源です。
• セッション記録（rrweb）はどこに？：bb sessions recording は廃止されており、このスキルはフェッチしません。screenshots/ のスクリーンショットストリームと dom/ の DOM ダンプを使用してください。

完全なリファレンスについては REFERENCE.md を参照してください。 デバッグ実行例については EXAMPLES.md を参照してください。