agent-host-logs

Agent Host デバッグログ

このスキルを使用して、Developer: Export Agent Host Debug Logs... で生成されるバンドルを確認します。通常のタイムスタンプ付き Code OSS ログディレクトリとは異なります。

バンドルにはトークン、プロンプト、ファイル内容、ターミナル出力、パス、設定が含まれる可能性があるため、機密情報として扱ってください。分析はローカルで行い、秘密情報や無関係なユーザーコンテンツを引用しないでください。タイムスタンプ、イベント名、ID、ステータス値、一般的なプロパティ値は問題ありません。

バンドルを開く

エクスポート名は通常 ah-logs で始まり、zip ファイルの場合と、すでに展開されたフォルダーの場合があります。zip ファイルの場合は、同梱の展開ツールを使用します。

python3 .github/skills/agent-host-logs/scripts/extract.py "<archive>.zip"

最後の行に、一時展開先のパスが表示されます。そのフォルダーで作業し、完了後はその正確なフォルダーのみを削除してください。

デスクトップの ZIP エクスポートでは、ホストが所有するログは、クライアントが所有するログやサイドカーとともに host-logs.zip 内に圧縮されています。このエントリがある場合は、同じ展開ツールを <extracted-folder>/host-logs.zip に対して実行し、両方の展開フォルダーを確認してください。ホストアーカイブには events.jsonl、プロバイダーログ、Agent Host プロセスログ、Mission Control トランスポートログが含まれます。フォルダー形式のエクスポートでは、これらのファイルはエクスポートフォルダーに直接配置されます。

ログの収集と保存中は、エクスポートをキャンセルできます。最終的な保存先の切り替え中は、処理が完了するか、以前のエクスポートが復元されるまでキャンセルが無効になります。復元に失敗した場合は、以前のエクスポートが保存されているバックアップがエラーに示されます。ホストログの収集またはコピーが一部しかできなかった場合は、保存されたクライアントログとともに警告が表示されます。

ファイルはベストエフォートで収集されるため、有効なバンドルに次の一部のみが含まれる場合があります。

events.jsonl
usage.jsonl
customizations.json
agenthost.log
agenthost.1.log
agenthost-server.log
vscode-logs/Window/renderer.log
vscode-logs/Window/renderer.1.log
vscode-logs/Shared/sharedprocess.log
ahp/*.jsonl
ahp/mission-control/*.jsonl
copilot-logs/*.log
remote-agenthost.log

ファイルの内容

基本的な流れは次のとおりです。

Window/client <-> AHP <-> Agent Host process <-> Copilot SDK

パス	内容
host-logs.zip	デスクトップエクスポートのうち、ホストが所有する部分を圧縮したものです。以下で説明するホストファイルにアクセスするには、別途展開してください。
events.jsonl	選択したセッションの永続化された Copilot SDK イベントです。ターン、メッセージ、ツール、権限、フック、スキル、サブエージェントが含まれます。他のログよりもはるかに長い期間を記録している場合があります。
usage.jsonl	クライアントが記録したトークン／クレジット使用量です。モデル呼び出しごとに 1 件のレコードが記録されます（turnId、モデル、入力／出力／キャッシュのトークン数、累積 totalNanoAiu）。SDK の assistant.usage イベントは一時的なもので、events.jsonl には記録されないため、これが呼び出しごとの使用量を記録する唯一のデータです。エージェントホストのデバッグログが有効だった場合にのみ存在します。
customizations.json	セッションで読み込まれたスキル／フック／エージェント／MCP サーバーのスナップショットです。SDK の session.*_loaded イベントは一時的なものであるため、実際に有効だった内容を記録する唯一のデータです。エージェントホストのデバッグログが有効だった場合にのみ存在します。
ahp/*.jsonl	クライアント接続の AHP 通信です。_ahpLog.dir は c2s または s2c、_ahpLog.ts はワイヤー上のタイムスタンプです。リクエスト、レスポンス、サブスクリプション、アクション、通知、クライアントから見える順序を確認する際に使用します。
ahp/mission-control/*.jsonl	受信した Mission Control クライアントとのホスト側の通信です。セッションが選択される前の認証失敗も含まれます。_ahpLog.transport は mission-control で、connectionId にはクライアント ID と接続世代が組み合わされています。ホストのエクスポートには、セッション固有のエクスポートであっても、残りの 1,000 件のアーティファクト予算内で、ローテーション済みのセグメントを含む、直近 10 件までの更新ファイルが含まれます。これらのログには、他の共有セッションの通信が含まれることがあります。
agenthost*.log	ローカルまたはサーバー上の Agent Host プロセスの動作を記録します。起動、認証、セッション、プロバイダーイベント、ツール、Git／ワークツリー、ホスト側のエラーが含まれます。番号付きのファイルは、ローテーション済みの古いセグメントです。
copilot-logs/*.log	選択したセッション ID に言及する Copilot SDK プロセスログです。プロセスログには他のセッションも含まれる場合があります。
vscode-logs/Window/*	Window ロググループの現在のファイルとローテーション済みファイルです。レンダラー／クライアントの動作、ネットワークアクティビティ、ビュー、その他のウィンドウ所有ログが含まれます。
vscode-logs/Shared/*	Shared ロググループの現在のファイルとローテーション済みファイルです。通常は補助的な証拠であり、ノイズが多いこともよくあります。
Agent Host (<name>).log	名前付きリモート Agent Host から転送されたログです。
remote-agenthost.log	入手可能な場合に直接ダウンロードされたリモートの agenthost.log です。

調査の始め方

1. ファイルを一覧表示し、サイズを記録します。
2. 報告された症状、おおよその発生時刻、ローカルまたはリモートのホスト、既知のセッション、チャット、ターン、リクエスト、ツールの ID を特定します。
3. 症状に最も近いファイルから調べます。
   • ターンまたはプロバイダーの動作：events.jsonl
   • トークン／クレジットの使用量またはコストに関する質問：usage.jsonl
   • クライアント／サーバーの状態または順序：ahp/*.jsonl
   • ホスト実装の障害：agenthost*.log
   • SDK の動作：copilot-logs/*.log
   • UI の動作：vscode-logs/Window/renderer.log とそのローテーション済みセグメント
4. 既知の時刻または ID で検索し、同じ操作を隣接するレイヤーでたどります。

相関に役立つフィールドには、未加工のセッション ID、セッション／チャット URI、turnId、interactionId、ツール／リクエスト ID、JSON-RPC リクエストの id、AHP の serverSeq、イベントの id／parentId などがあります。

Copilot セッションの更新失敗

デフォルトの Info ログレベルでは、agenthost*.log に更新操作、構成と SDK セッション ID、チャット、ターン、および最初に一致した reason が記録されます。一致したトリガーのうち、報告されるのは最初のものだけです。これにより、再起動チェックの短絡評価順序が保たれます。構造上の理由は、内容を記録せずに、クライアントツール、クライアントプラグイン、ルート MCP 構成を区別します。

attemptId を使って、Preparing SDK session と、対応する SDK resumeSession started／settled の記録を追跡してください。各接続済み SDK セッションのシャットダウンと切断の記録は、instanceId を使って追跡してください。これにより、同じ SDK セッションをラップする連続したラッパーを区別できます。disconnectRpc=pending および shutdownReceived=true の disconnect wait completed 記録は、切断 RPC の完了前にシャットダウン通知によって呼び出し元の待機が解除されたことを意味します。disposed=true の後も含め、後続の RPC 完了または失敗は別途記録されます。通知だけでも、ホスト側の待機だけでも、ネイティブのクリーンアップが完了した証拠にはなりません。ティアダウンと再開の競合があったと結論づける前に、SDK プロセスログと照合してください。

重要なヒント

• events.jsonl、Copilot SDK ログ、AHP のタイムスタンプは通常 UTC です。通常の .log ファイルはローカルマシンの時刻を使う場合があり、リモートログは別のタイムゾーンを使う場合があります。
• AHP ログは接続単位で、複数のセッションを含むことがあります。Copilot SDK のプロセスログにも複数のセッションが含まれる場合があります。
• Mission Control のレーン通信は、デスクトップクライアントの chat.agentHost.ahpJsonlLoggingEnabled 設定とは独立して記録されます。認証リクエストのトークンは秘匿化されますが、その他のセッションコンテンツは機密情報のままです。
• Mission Control の履歴は、接続の世代をまたいで、ホストのログディレクトリごとに10ファイル、750 MiBまで保持されます。ディレクトリへのエクスポートでは、ホスト側のコピーが成功するまでクライアント側の代替候補が保持されます。ホスト側のアーティファクトが利用できない場合、Mission Control のログは代わりに ahp/ の下に表示されます。
• AHP ファイルは .jsonl、.1.jsonl、.2.jsonl などの名前でローテーションされます。順序を再構成するには _ahpLog.ts を使ってください。
• subscribe の結果には完全なスナップショットが含まれることがあります。その内容がサブスクリプション時点で変更されたとは限りません。
• _ahpLog.truncated: true は、そのログレコードから大きな値が省略されたことを意味します。
• 警告またはエラーの重大度だけでは、因果関係の証明にはなりません。一致する失敗レスポンス、完了記録の欠落、またはユーザーから見える影響を探してください。
• エクスポート時の収集はベストエフォートのため、ファイルが欠落していても異常ではありません。