brd-browser-debug

Bright Data — ブラウザーセッションデバッガー

Browser Sessions API を使用して、Bright Data Scraping Browser のセッションを診断します。ライブのセッションデータを取得し、エラーの診断、帯域幅の分析、CAPTCHA の報告、最近のセッション全体にわたるパターン検出を行います。

セットアップ

API キーを設定します：

export BRIGHTDATA_API_KEY="your-api-key"

キーは Bright Data ダッシュボード → API トークン から取得してください。

セッションデータにゾーンがフィールドとして返されるため、ゾーンの設定は不要です。

使い方

最近のセッションを一覧表示してトリアージする

引数なしで /brd-browser-debug として呼び出します。

API リファレンス： GET /browser_sessions

セッションの取得

まず、limit=100（最大値）を指定し、最新順で 1 回呼び出します：

GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc
Authorization: Bearer $BRIGHTDATA_API_KEY

ページネーション： レスポンスには total、has_more、next_offset が含まれます。has_more が true で、分析にさらにデータが必要な場合（例：帯域幅の外れ値検出により多くのサンプルが必要な場合）、offset=<next_offset> を指定して次のページを取得します。十分なデータが集まるか、has_more が false になるまで続けます。

利用可能なフィルター — ユーザーが範囲を指定した場合に適用します：

• status=failed|finished|running — 特定のセッション状態に絞り込みます
• api_name=<zone> — 特定の Bright Data ゾーンに絞り込みます
• target_url=<domain> — ターゲットドメインで絞り込みます（例：ksp.co.il）
• start_date / end_date — ISO 8601 の日時範囲
• sort=timestamp|duration|bandwidth と order=asc|desc

ユーザーが特定のゾーン、日付範囲、ドメインについて尋ねた場合は、すべてのセッションを取得してクライアント側で絞り込むのではなく、該当するフィルターを適用します。

トリアージ手順

1. 健全性の概要を提示します：レスポンスの total と、finished / failed / running の件数。
2. 最新のセッション — 状態にかかわらず、必ず取り上げます（単一セッションモードと同じ詳細度で）。
3. 失敗したセッション — 失敗ごとに、セッション ID、タイムスタンプ、期間、帯域幅を示し、以下の「失敗したセッションの診断」セクションにあるシグナルを使って原因を推測します。
4. パターン検出 — 3 件以上のセッションで同じ error.code が発生している場合は、システム上の問題として扱います：

   "custom_headers が原因で 3 件のセッションが失敗しました。Bright Data が禁止しているヘッダーを上書きしています。コードから page.setExtraHTTPHeaders() を削除してください。"

5. 帯域幅の外れ値 — セッションを target_url のドメインごとにグループ化します。各ドメインで 3 件以上のセッションがある場合、帯域幅の中央値を計算します。そのドメインの中央値の 2 倍を超える帯域幅のセッションには外れ値のフラグを付け、異常に高い帯域幅を消費してから終了した失敗セッションかどうかも記載します。
6. CAPTCHA の発生状況 — CAPTCHA に遭遇したセッション数と、解決できたかどうかを報告します。
7. 結論を 1 行で締めくくります：最も重要な発見と、最も効果の大きい修正を示します。

単一セッションを調査する

/brd-browser-debug <session_id> として呼び出します。

API リファレンス： GET /browser_sessions/{session_id}

1. 呼び出します：

   GET https://api.brightdata.com/browser_sessions/<session_id>
   Authorization: Bearer $BRIGHTDATA_API_KEY
   

   セッション ID が見つからない場合は 404 が返されます。ユーザーに伝えて終了してください。

2. レスポンスのフィールドを使って詳細な分析を提示します：

   • ステータス（status）：running / finished / failed
   • ゾーン（api_name）：セッションを処理した Bright Data ゾーン
   • タイムスタンプ（timestamp）：ISO 8601。現地時間で分かりやすい形式で表示します
   • 期間（duration）：秒（null の場合あり）。失敗時に 2 秒未満なら、セッションがほとんど開始されていないことを示します
   • 帯域幅（bandwidth）：バイトを MB に変換します
   • ナビゲーション数（navigations）：0 の場合（何も読み込まれていない）にその旨を示します
   • CAPTCHA（captcha）：solved / none / detected / failed のいずれかです。detected はチャレンジが表示されたものの解決されなかったことを意味し、failed は解決を試みたものの成功しなかったことを意味します
   • ルート：target_url → end_url。大きな差異（ドメインの違い、ログイン画面、エラーページ）に注意します
   • エラー（error.code + error.message）：下記の「失敗したセッションの診断」にあるシグナルを使って原因を推測します

3. 最後に一行の判定を示します。

会話の文脈から自動検出する

会話内に Bright Data のブラウザーの問題が現れた場合（puppeteer のスタックトレース、エラーコード、brd.superproxy.io への言及、ユーザーによるセッション失敗の説明、またはスクレイパーが空や予期しない結果を返す場合。例：「カテゴリが 0 件見つかりました」「商品が 0 件でした」、予想より項目数が少ないなど）：

• 出力にセッション ID が表示されている場合 → そのセッションを単一セッションとして詳細に分析します。
• セッション ID が表示されていない場合 → 関連するターゲットドメインで絞り込み、一覧表示とトリアージを実行します。最も新しいセッションを、問題の原因である可能性が高いものとして強調します。
• 会話内で見られたエラーや予期しない動作を、API の返す内容と照合します。通常の帯域幅で正常に終了したセッションなのにスクレイパーが 0 件の結果を返した場合、原因はプロキシではなく、クライアント側のセレクターまたは抽出処理の不具合です。

機能

• スマートなトリアージ：セッションを単に一覧表示するのではなく、失敗パターンごとに自動的に分類します
• 動的な帯域幅の外れ値検出：ドメインごとにセッションを中央値と比較し、中央値の 2 倍を超えるセッションにフラグを付けます
• CAPTCHA レポート：CAPTCHA の発生率と解決率を表示します
• エラーの推論：セッションのシグナルを総合的に読み取り、問題の原因を推測します
• 設定不要：環境変数から API キーを読み込み、ゾーンの設定は必要ありません

失敗したセッションの診断

エラーコードだけに頼らないでください。利用可能なすべてのセッションシグナルを照合し、問題の原因を推測します。

• 期間とナビゲーション数：2 秒未満で失敗し、ナビゲーション数が 0 のセッションは、接続フェーズを越えられていません。設定または認証の問題が考えられます。失敗まで数分間実行されていたセッションは、実行時の問題（スクレイピング中のブロック、アイドルタイムアウト、ネットワーク切断）が考えられます。
• 他のセッションと比較した帯域幅：失敗したセッションの帯域幅が成功したセッションと同程度の場合、ターゲットに到達したものの、抽出中に失敗した可能性があります。帯域幅がほぼゼロの失敗セッションでは、何も読み込まれていません。
• CAPTCHA フィールド：captcha が detected で solved でない場合、未解決のチャレンジによってセッションが停止しています。ゾーンで CAPTCHA の解決を有効にすることを提案します。
• target_url と end_url：大きな差異（ドメインの違い、ログインページ、エラーページ）がある場合、セッションは意図したターゲットから別の場所へリダイレクトされています。
• error.message：未加工のメッセージテキストをそのまま使って、何が起きたかを説明します。メッセージに書かれている内容を超えて、推測したり意味を捏造したりしないでください。原因が不明な場合は、ユーザーに Bright Data サポートを案内します。