debug-browser-session

カーネルのブラウザーセッションをデバッグする

Kernel CLI を使って、正常に動作しない Kernel クラウドブラウザーセッションの原因を特定します。CLI からはセッションの VM に完全にアクセスできます。セッションのステータス、スクリーンショット、Playwright の実行、ログファイル、VM 内でのコマンド実行を確認できるため、ボット検出、Chrome のクラッシュ、ネットワーク／DNS の問題、ライブビュー／WebRTC の問題のいずれが原因かを特定するために必要な情報がすべて揃っています。

入力

調査には次の 2 つが必要です。

1. セッション ID — デバッグするブラウザーセッションです（例：abc123example456xyz）。
2. 問題の説明 — 発生している問題です（例：「特定のサイトへの移動時に ERR_HTTP2_PROTOCOL_ERROR が発生する」、「ブラウザーが応答しない」、「ページが読み込まれない」、「ライブビューが真っ白になる」）。

どちらかが不足している場合は、調査を進める前に確認してください。問題の説明に応じて、以下の確認項目の優先度を調整します。

前提条件

Kernel CLI のインストールと認証については、kernel-cli スキルを読み込んでください。より詳細なオプションが必要な場合は、そのリファレンスで CLI のすべてのコマンド（browser-management、filesystem-ops、process-execution、computer-controls）を確認できます。

CLI の基本コマンド

<SESSION_ID> をセッション ID に置き換えてください。

セッションのステータス

kernel browsers get <SESSION_ID> -o json

# If the normal lookup returns not found, recover the soft-deleted record by session ID.
kernel browsers get <SESSION_ID> --include-deleted -o json

削除済みのレコードから、created_at や deleted_at などの静的な設定とタイムスタンプを確認できます。VM、Playwright、スクリーンショット、curl、ログ、ライブビューの各コマンドには、引き続き稼働中のセッションが必要です。

現在の状態のスクリーンショットを撮る

kernel browsers computer screenshot <SESSION_ID> --to screenshot.png

Playwright でページの状態を確認する

kernel browsers playwright execute <SESSION_ID> "return { url: page.url(), title: await page.title() }"

ブラウザーサービスのログを読む

kernel browsers logs stream <SESSION_ID> --source supervisor --supervisor-process chromium --follow=false
kernel browsers logs stream <SESSION_ID> --source supervisor --supervisor-process neko --follow=false

その他の VM ログを確認するには、ファイルを直接一覧表示して読み込みます。

kernel browsers fs list-files <SESSION_ID> --path /var/log
kernel browsers fs read-file <SESSION_ID> --path /var/log/supervisord.log

Chrome と VM のネットワーク経路を比較する

# Uses Chrome's TLS fingerprint, cookies, headers, and proxy configuration.
kernel browsers curl <SESSION_ID> https://example.com -I -w 'status=%{http_code} total=%{time_total}\n'

# Uses curl inside the VM instead of Chrome's network stack.
kernel browsers process exec <SESSION_ID> -- curl -I https://example.com
kernel browsers process exec <SESSION_ID> -- cat /etc/resolv.conf

Playwright で Cookie を確認する

kernel browsers playwright execute <SESSION_ID> "const cookies = await page.context().cookies(); return { count: cookies.length, domains: [...new Set(cookies.map(c => c.domain))] }"

ブラウザーのテレメトリーイベント（セッション削除後も利用可能）

テレメトリーは、障害の発生前に有効化されていた場合にのみ役立ちます。イベントの記録はデフォルトでオフになっています。有効になっていた場合、収集済みのイベントはテレメトリーを無効にした後やセッションを削除した後も読み取れます。ソフト削除されたセッションの静的なレコードも、kernel browsers get <SESSION_ID> --include-deleted で取得できます。ただし、実行時の調査には引き続き稼働中のセッションが必要です。

デバッグで重要なカテゴリは、console（コンソール出力と捕捉されなかった例外）、network（リクエスト／レスポンスのメタデータ）、page（ナビゲーションとライフサイクル）です。特に重要なイベントタイプは、console_error、network_loading_failed、2xx 以外のステータスを含む network_response、system_oom_kill、monitor_disconnected（テレメトリーの欠落を示すため、それ以降のイベントは不完全なものとして扱います）です。カテゴリとイベントタイプの全一覧は、テレメトリーカテゴリのドキュメントを参照してください。

イベントを読む

kernel browsers telemetry events <SESSION_ID> --since 24h --all
kernel browsers telemetry events <SESSION_ID> --since 24h --categories console,network --all
kernel browsers telemetry events <SESSION_ID> --since 24h --types console_error,network_loading_failed

--since には RFC-3339 タイムスタンプ、または 5m のような期間を指定できます。デフォルトは直近 5 分間です。判断に迷う場合は、例のように --since 24h など、余裕のある期間を指定してください。削除済みのセッションでは、browsers get --include-deleted で created_at を取得し、期間を正確に設定してください。--all を指定すると、期間内のすべてのページを順に取得します（デフォルトでは 20 件のイベントからなる 1 ページのみを取得し、--limit は最大 100 件、手動でページを切り替えるには --offset カーソルを使用します）。--types フィルターを指定すると、期間全体が自動的に検索されます。イベントの完全なペイロードを取得するには -o json を使用してください。デフォルトのテーブルに表示されるのは、シーケンス、時刻、カテゴリ、タイプのみです。そのため、イベントの内容（network_response のステータスコード、コンソールのエラーメッセージ、URL など）に基づいて調査する場合は、JSON 出力が必要です。同じイベントは API／SDK（GET /browsers/{session_id}/telemetry/events。since のデフォルトは同じく直近 5 分間です）からも利用できます。また、Kernel MCP サーバーのビルドに含まれている場合は、manage_browsers ツールの get_telemetry アクションからも利用できます（デフォルトでセッション期間全体を対象とします）。稼働中のセッションでは、kernel browsers telemetry stream <SESSION_ID> を実行すると、発生したイベントを逐次取得できます。

キャプチャを有効にする

kernel browsers create --telemetry=console,network,page
kernel browsers update <SESSION_ID> --telemetry=console,network,page

有効にするとキャプチャはすぐに開始され、過去にさかのぼって記録することはできません。デバッグする予定の自動化では、問題が発生した際に証拠が残るよう、作成時にテレメトリ（console、network、page を含む）を有効にしてください。実行中のセッションでは、カテゴリを有効にして問題を再現してから、イベントを確認してください。

注意点：

• テレメトリはオプトイン方式です。 イベントがない場合、何も起きなかったのではなく、単に有効にされていなかった可能性があります。
• デフォルトのバンドルには、デバッグに不可欠なカテゴリ（console、network、page）が含まれません。 --telemetry=all で記録されるのは制御／接続／システム／captcha のみです。これらの情報が必要な場合は、（上記のように）console、network、page を明示的に指定してください。
• monitor_disconnected はテレメトリの欠落を示します。 コレクターが停止したため、次の monitor_reconnected まで、またはそれが見つからない場合はイベント履歴の末尾まで、console／network／page／interaction の記録は不完全として扱ってください。

よくある問題と解決策

ネットワークエラー（ERR_HTTP2_PROTOCOL_ERROR、ERR_CONNECTION_RESET など）

よくある原因はボット検出です。多くのサイトでは、Cloudflare、Imperva、Akamai などの CDN を使用してブラウザーのフィンガープリントを取得し、自動化をブロックしています。

ボット検出の兆候：

• VM の curl は動作するが、ページまたは kernel browsers curl は失敗する
• 「アクセスが拒否されました」、captcha ページ、「ブラウザーを確認しています…」などのメッセージが表示される
• ブラウザー設定で stealth: false になっている

kernel browsers get <SESSION_ID> -o json で stealth と明示的な proxy_id を確認してください。ステルスセッションで Kernel のデフォルトプロキシを使う想定の場合は、スクリーンショット、テレメトリ、ログを取得してから、その経路だけを切り分けてください。

# This mutates live routing.
kernel browsers update <SESSION_ID> --disable-default-proxy
# Reproduce the failing request once and capture the result.
kernel browsers update <SESSION_ID> --disable-default-proxy=false

デフォルトプロキシが現在有効であるべきだとセッションの所有者が確認した場合に限り、この A/B テストを実行してください。browsers get では以前の disable_default_proxy の状態を確認できないためです。--clear-proxy で代用しないでください。明示的なプロキシが削除されます。結果にかかわらずデフォルトプロキシを復元してください。直接接続で問題が解決した場合は、プロキシ経路を調査してください。

ステルス設定は作成時に指定するため、実行中のセッションでは切り替えられません。再現のためにステルス設定の代替セッションを作成する場合は、元のセッションを保持し、診断用の代替セッションのみを作業完了後に削除してください。

kernel browsers delete <DIAGNOSTIC_SESSION_ID>

ブラウザーが応答しない

原因：Chrome プロセスがクラッシュしたか、ハングしています。
確認事項：スーパーバイザーのログで Chromium の再起動イベントを確認してください。
解決策：タイムアウトに達していないことを確認し、ログでメモリの問題を調べ、新しいセッションを作成してください。

ページが読み込まれない

原因：ネットワーク、DNS、またはプロキシの問題です。
確認事項：kernel browsers curl と VM の curl を比較し、/etc/resolv.conf を確認してから、設定済みのプロキシを調べてください。Chrome だけで失敗する場合は、Chrome の状態、TLS フィンガープリント、Cookie、または Chrome のプロキシ経路に問題があると考えられます。両方の経路で失敗する場合は、VM／ネットワークスタックの下位層に問題があります。

ライブビューが動作しない

原因：Neko／WebRTC の問題です。
確認事項：kernel browsers view <SESSION_ID> でライブビューの URL を取得して開き、browsers logs stream で Neko のログを読み取り、browsers get で headless が false になっていることを確認してください。
解決策：WebRTC をブロックするファイアウォールがないか確認し、Playwright とスクリーンショットが引き続き動作するかを比較してください。動作する場合、ブラウザーは正常で、問題はライブビューに限定されています。

予想されるログエントリ（通常の動作）

以下は正常であり、問題を示すものではありません。

• Failed to call method: org.freedesktop.DBus.Properties.GetAll — DBus の権限（コンテナーでは想定内）
• vkCreateInstance: Found no drivers — VM に GPU がない（想定内）
• GCM の DEPRECATED_ENDPOINT — Google による廃止通知（影響なし）
• SharedImageManager::ProduceMemory エラー — GPU 関連（重大ではありません）

デバッグチェックリスト

• アクティブなセッションが見つかった、または --include-deleted で削除済みのメタデータを復元した
• スクリーンショットに想定どおりの内容が表示されている（またはエラーが確認できる）
• 現在の URL が想定どおりである
• スーパーバイザーのログで、すべてのサービスが稼働していることを確認した
• Chrome スタックと VM の curl の結果を比較した
• Chromium のログに重大なエラーがない
• Cookie とセッションの状態が正しい
• テレメトリーイベントで console_error / network_loading_failed / システムイベントを確認した（特にセッションが見つからない場合）
• 一時的なデフォルトプロキシの変更を元に戻した。診断用の置き換えセッションがあれば削除した

推奨する手順

1. ブラウザー情報を取得します。見つからない場合は --include-deleted を付けて再試行します。
2. 証拠を保存します。スクリーンショット、URL／タイトル、テレメトリー、ログの順に保存します。
3. 接続エラーを確認するため、Chrome スタックの curl と VM の curl を比較します。
4. 1 回再現させます。その後、関連する場合に限り、一時的なデフォルトプロキシの A/B テストを実行します。
5. 変更したルーティングを元に戻し、診断用の置き換えセッションがあれば削除します。

セッションが削除されている場合は、browsers get --include-deleted で静的メタデータを復元できます。テレメトリーは残された実行時のシグナルですが、セッションの実行中にキャプチャが有効になっていた場合に限ります。