セッションからAgentのバグレポートを収集し、送信する¶
Agent の応答が想定と異なる、ツールが停止する、接続が不安定、診断用ログが不足する場合は、問題が発生したセッションから直接バグレポートを生成できます。現在のセッションと Agent のランタイム状態を収集し、config.toml(旧インストールでは agent.env)内の機密値の代入のみをマスクして、運用担当者やサポートが解析できる ZIP としてアップロードします。
開始する前に、Agentがオンラインであり、問題が発生した元のセッションを開いていることを確認してください。バグレポートは現在のセッションのみを収集し、他のセッションからのチャット内容は自動的に含まれません。
報告書を収集し、直接サポートに送信する。¶
報告書を担当者に提出する必要がある場合は、最初の要求に受信先の住所と症状を記載してください。
Collect a Bug Report for the current Session and send the download link to tec-support@guance.com. Symptom: the page keeps showing that the Agent is thinking after a tool finishes.
Agentは、以下のステップを実行します:
- 現在のセッションのバグレポートを収集してアップロードします。機密値の代入をマスクする対象は
config.toml(旧インストールではagent.env)のみです。 - ZIPファイルの一時的なダウンロードリンクを取得します。
- 指定されたメールアドレスに、ファイル名、リンク、および有効期限を送信します。
この流れでは、セッションからZIPファイルをダウンロードし、それを手動でメールの添付ファイルとしてアップロードするという手間を省きます。メールには一時的なダウンロードリンクが含まれており、ZIPファイルは含まれていません。受信者はリンクが切れる前に、必ずレポートをダウンロードする必要があります。
送信する前に、受取人のアドレスを確認し、診断データの取り扱いに承認された人にのみ報告書を送信してください。
現在のセッションに関するバグレポートを収集する¶
このメッセージをセッション内で送信してください:
症状についても、同じメッセージに記載することができます:
Collect a Bug Report for the current Session. Symptom: the page keeps showing that the Agent is thinking after a tool finishes.
Agent は情報を収集し、config.toml(旧インストールでは agent.env)内の機密値の代入のみをマスクして、レポートをパッケージ化し、アップロードします。通常は 2 分以内に完了します。CPU Profile を有効にすると、サンプリング時間が追加で必要になる場合があります。
アップロードが成功した後、ZIPファイルとダウンロードに関する情報がセッションに表示されます。レポートは、30日間、プラットフォーム上に保持されます。一時的なダウンロードリンクは、デフォルトで7日間有効です。リンクが切れる前に、レポートをダウンロードまたは転送してください。
標準の権限モードで収集を承認する¶
標準の承認モードでは、診断データを読み取る前に、ツールの承認が表示されます。この承認には、収集範囲、データカテゴリ、およびCPU Profileが含まれているかどうが記載されています。
収集範囲が適切であることを確認して承認してください。承認を拒否する、リクエストをキャンセルする、または以前の実行を停止する新しいメッセージを送信した場合、Agent はレポートを収集もアップロードもしません。
YOLO/Full Accessモードでは、承認ダイアログが表示されません。Agentは、レポートを直接収集・アップロードします。一方、プラットフォームは、ツール呼び出しに関する承認監査データを記録します。
既存のバグレポートをメールで送信する¶
もし、最初のリクエストで報告書のみが生成された場合は、同じセッションで続行してください。
メールの内容には、ZIPファイルの名前、有効期限、および一時的なダウンロードリンクが含まれています。ZIPファイルは添付ファイルとしては含まれていません。受信者はリンクが切れる前に、必ずこの報告書をダウンロードする必要があります。
報告書に含まれるデータの管理¶
デフォルトでは、このレポートには以下が含まれています:
- セッション中の元のユーザーメッセージは、コンテンツの置換なしで、収集開始時までのものです。
- ツールのイベント情報、その他のチャット記録、および有効なコンテキスト。これらは、既存の予算内で実施されるものです。
- 最近のAgentのログ記録および実行時のメトリクス。
- プロセス、コンテナ、ネットワークプローブ、ビルドの情報。
- 元の環境変数と設定、および機密値の代入をマスクした
config.toml(旧インストールではagent.env)。 - Profile、Skill、スキーマ、およびMCPの同期診断概要。
- サイズを制限した goroutine ダンプとヒーププロファイル。
ログ収集では、ファイルごとや合計サイズによる切り詰めは行いません。log_since_hours(既定は 24 時間)で最近更新されたファイルを選び、開いた時点のサイズまで読み取り、内容を置換せずに圧縮します。その後の追記によって収集範囲は広がりません。ローテーションで失われたログは復元できず、メモリ上だけのリングバッファログは partial と表示されます。Agent は最大 1 GiB(1,073,741,824 バイト)の ZIP を受け付け、一時ファイルからストリーミングします。上限を超える ZIP はログを捨てずに明示的に失敗します。Beak v0.13.0 のアップロード上限はファイルごとに 32 MiB のため、それより大きいレポートはアップロードに失敗します。Agent の上限を変更してもサーバーの上限は変わりません。大きいレポートへの対応には後続のサーバー更新が必要です。メールではダウンロードリンクを共有するため、添付サイズの制限は受けません。
session/user-messages.jsonl はメッセージ ID、送信者、タイムスタンプ、本文、既存のマルチモーダルコンテンツと添付参照を保持します。ツールイベントや通常テキストの切り詰め上限は適用されず、圧縮された要約が元のメッセージを置き換えることもありません。session/chat.jsonl と session/events.jsonl は、サイズ制限のある補助診断データです。
このレポートは、ユーザーメッセージをBeakの履歴と照合しています。session/user-messages-coverage.jsonおよびマニフェストのuser_messagesには、カットオフ、メッセージの数、既知の時間範囲、および完全性が記録されています。オフライン操作、サポートされていない履歴API、または回復不可能な履歴は、読み取れるメッセージを保持し、partialにその理由を記録します。アップロード制限を超えるZIPファイルは、ユーザーメッセージを破棄する代わりに、明示的に失敗します。
添付ファイルは、その内容をダウンロードすることなく、既存の参照情報やメタデータを保持します。メッセージ内に既に存在するマルチモダルなコンテンツも引き続き含まれます。このレポートは、他のセッションからのチャット内容や、Skill、Schema、MCPパッケージ、またはワーキングディレクトリファイルからのコンテンツを積極的に収集しません。ユーザーメッセージのエクスポートには、追加のLLMリクエスト記録は不要であり、また、完全なプロバイダーのリクエストやシステムのプロンプトが含まれていることを意味しません。
CPUの使用状況を診断するには、CPU Profileを明示的に要求してください。
CPU Profile は既定では収集しません。1–30 秒の収集時間を指定できます。サンプリングは Agent に少量の負荷を追加するため、CPU の問題を調べる場合にのみ有効にしてください。
また、特定のカテゴリーを明示的に除外することもできます:
Collect a Bug Report for the current Session without environment variables or configuration snapshots.
診断レポートの取り扱いを安全に行う¶
Agent v0.16.0 の元の内容を含む depth 1/2 のレポートを obscli bug-report view で表示するには、obscli v0.16.0 以降を使用してください。旧ビューアーはこれらのレポートを拒否します。新しいビューアーは、過去のマスク済みレポートと depth 3 のレポートにも対応します。
Agent が機密値の代入をマスクするのは、レポート内の config.toml(旧インストールでは agent.env)のみです。その他の環境変数、設定、ログ、セッション内容、LLM の証拠は、認証情報の走査や文字列の置換をせずに元の内容を保持します。バグレポートにはキー、トークン、個人情報が含まれる場合があります。機密の診断データとして扱ってください。
レポートをダウンロードした後:
- 責任を持った人々とのみ共有し、管理されたチャンネルを通じて行ってください。
- 公開のチケットサイト、公開のコードリポジトリ、または公開のファイル共有サービスにアップロードしないでください。
- トラブルシューティング後に不要になったローカルコピーを削除します。
- セッションに手動で貼付されたパスワード、トークン、または個人情報が含まれている場合は、送信する前に受取人に通知し、組織のデータ処理ポリシーに従ってください。
コレクションのトラブルシューティングやアップロードの失敗の解決¶
承認はまだ保留中です¶
標準の承認モードでは、有効期限が切れる前に承認が必要です。承認の有効期限が切れた場合は、再度収集リクエストを送信してください。
もしAgentがYOLO/Full Accessに設定されているにもかかわらず、承認を要求する場合、またはapproval_id is required for diagnostic assetsを報告する場合は、BeakおよびAgentを最新バージョンに更新し、再度試行します。
別の報告書も既に進行中です。¶
各Agentは、一度に一つのバグレポートのみを収集できます。現在のタスクが完了するまで待ってから、再試行してください。複数のセッションから同時に収集を開始しないでください。
報告の状況は部分的です。¶
partialというのは、1つまたは複数の診断ソースが利用できなかった、タイムアウトした、またはセキュリティ検査によって削除されたことを意味します。残りのコンテンツはまだアップロードされています。不足している項目については、レポートを参照し、必要なコンテンツがない場合は、Agentの権限、ログファイル、ネットワーク状態を確認した上で、再度アップロードしてください。
アップロードの返信期限が過ぎてしまいました。¶
このエラーは、Agent のバージョンが収集とアップロードで 1 つのタイムアウトを共有している場合に発生することがあります。Agent を最新バージョンに更新して再試行してください。問題が続く場合は、Agent から Beak への接続と、Agent ログの確認に従って最近のエラーを調べてください。
診断用アセットが利用できません。¶
もしページに、そのサービスが診断用のアセットをサポートしていないと報告されている場合は、BeakおよびAgentが互換性のあるバージョンにアップグレードされていることを確認してください。アップグレード後、Agentを再起動し、元のセッションから再度収集を開始してください。
メールにはダウンロードリンクが含まれていません。¶
まず、セッション内でバグレポートが正常に生成されたかを確認してください。また、一時的なダウンロードリンクが有効期限切れになっていないかも確認してください。Agentに、生成されたレポートを再度送信してもらうよう依頼してください。もしメールにまだリンクがない場合は、Agentを更新し、メール機能が正しく設定されているかを確認してください。
記録:LLM 診断データ¶
モデルに送信される正確なコンテキストを調査するために、この値をAgentのconfig.tomlに明示的に設定します(古いインストールではagent.envを使用)。
Agent を再起動してください。このオプションは config.toml(旧インストールでは agent.env)からのみ読み取られます。プロセス環境だけに設定しても記録は有効になりません。既定値は 0 です。
| 深さ | 録音され、エクスポートされたコンテンツ |
|---|---|
0 |
既存のバグレポート内容です。追加のLLMの記録内容はありません。 |
1 |
各セッションのセッション、ラウンド、コール、再試行、目的、タイミング、および状態。 |
2 |
各セッションにおける最新の完了した通話のメタデータ、および要求と応答の完全な情報を含む。エクスポートでは、元のコンテンツが保持されます。 |
3 |
最初の呼び出しから、各セッションにおける生のリクエスト、ストリームされた応答、解析されたモデル結果、およびツールデータを取得します。 |
オンライン収集では、chat_depth=1またはchat_depth=2を要求することができますが、既存の承認とアップロードプロセスが必要であり、デフォルト値は0です。オンラインツールは3の深さを拒否します。記録された深さを超える深さを要求すると、requested_depth_not_recordedが返され、ZIPは生成されません。設定を増やしても、以前の呼び出しを回復することはできません。カバレッジレポートでは、古いまたは部分的に記録されたセッションが表示されます。
ローカルにエクスポートする¶
このコマンドをAgentホスト上で実行してください:
obs-agent --config /etc/obs-agent/config.toml --bug-report --depth=2 --bug-report-output /var/lib/obs-agent/reports/support.zip
コマンドはローカルに ZIP を作成し、status、絶対パスの path、size_bytes、sha256 を含む JSON オブジェクトを 1 つ標準出力に出します。親ディレクトリは事前に存在する必要があり、既存のファイルは上書きしません。レポートはアップロードされません。Agent の実行中でも使用できます。
管理された環境でローカルの品質評価を行う場合は、記録深度を 3 に設定してから実行します。
obs-agent --config /etc/obs-agent/config.toml --bug-report --depth=3 --bug-report-output /var/lib/obs-agent/reports/support-UNREDACTED.zip
深度 3 のレポートは機密性の高いファイルです。 マスクされていない業務テキスト、システムプロンプト、推論、ツール引数と結果、モデルに実際に送信したインラインのマルチモーダルデータが含まれます。標準エラー出力、マニフェスト、LLM インデックスに UNREDACTED と表示されます。出力ディレクトリへのアクセスを制限し、保管、転送、廃棄を管理してください。
深度 2 では記録したリクエストと応答の元の内容を保持します。認証情報の文字列があってもエクスポートは妨げられません。ZIP 構造、JSON の妥当性、記録の完全性は引き続き検証します。通信の認証ヘッダーは別途記録しません。独立した config.toml(旧インストールでは agent.env)内の機密値の代入のみをマスクします。env.json、config.json、通常のログ、ランタイムメタデータ、記録された LLM コンテンツは元の値を保持します。記録ファイルのモードは 0600 で、セッション削除通知が Agent に届くと削除されます。深度 3 には呼び出し数、本文サイズ、ZIP サイズの上限がありません。十分なディスク容量を確保してください。
収集は Agent を停止せず、開始時点のスナップショットを取得します。実行中の呼び出しでは記録済みのデータを保持し、in_progress と表示します。完全記録のセッションに説明できない欠落がある場合、不完全な証拠を完全なものとして示す代わりに recording_gap を返します。