agent-observability

エージェントのオブザーバビリティ

リクエストの受信からモデル、検索、ツール、引き継ぎ、応答までのスパンを通じて、エージェントの動作を説明可能にします。

使用する場面

• 新規または既存のエージェントのワークフローにテレメトリを追加する。
• 遅延が大きい、高コスト、不正確、ループする、または失敗する実行を診断する。
• ダッシュボード、アラート、サービスレベル指標、監査証跡を定義する。
• モデル、ツール、オーケストレーションフレームワーク全体でトレースを標準化する。

入力

ワークフローグラフ、ランタイムの境界、インシデントに関する質問、トラフィックと障害の想定、テレメトリスタック、データ分類、保持ポリシー、サンプリングの上限、担当者を収集します。観測できないものを明示します。

出力仕様

次を作成します。

1. オブザーバビリティの目標とシステム境界。
2. 識別子、スパンの分類体系、属性、秘匿化ルールを含むトレースとイベントのスキーマ。
3. 定義、単位、ディメンション、担当者を含むメトリクス。
4. ユーザーへの影響に結び付いたダッシュボードとアラートの仕様。
5. サンプリング、保持、アクセス、コストの計画。
6. 調査手順書と計装の検証結果。

ワークフロー

1. 「どのツールがタイムアウトを引き起こしているか？」や「解決済みタスクあたりのコストが増えたのはなぜか？」といった運用上の質問から始めます。意思決定に使わないフィールドは収集しません。
2. ユーザーに見える試行ごとに1つのトレースを定義します。モデル呼び出し、検索、ツール、引き継ぎ、承認、再試行、最終検証のスパンを作成します。親子関係を維持し、キューをまたいで相関識別子を伝播させます。
3. 安定したセマンティックフィールドを記録します。利用可能な場合は、バージョン識別子、ステータス、タイミング、トークンとコストの測定値、再試行回数、ツール名、ポリシーの適用結果、評価タグを含めます。属性を定義する前にtrace-schema.mdを確認してください。
4. コンテンツとメタデータを分離します。デフォルトではコンテンツを含まないテレメトリとし、プロンプトや応答の記録は、明示的な承認、秘匿化、アクセス制御、保持期間の制限がある場合にのみ許可します。
5. 少数のサービス指標を導き出します。タスク成功率、重大なポリシー違反、エンドツーエンドのレイテンシ、ツールの失敗率、エスカレーション率、完了タスクあたりのコストです。分母と、キャンセルやタイムアウトの扱いを定義します。
6. ユーザーの成果から依存関係の詳細へと掘り下げられるダッシュボードを作成します。個々のノイズの多いスパンではなく、対応可能な持続的な影響に対してアラートを設定し、担当者と手順書を付けます。
7. カーディナリティ、サンプリング、ストレージコストを管理します。許可されている場合は重大な失敗をすべて保持し、通常のトラフィックにはヘッドサンプリングまたはテールサンプリングを用いて、まれなエラー分類が失われないようにします。
8. データを信頼する前に、トレースの伝播、秘匿化、再試行の関連付け、クロックの処理、テレメトリ低下時の動作をテストします。

正規化されたスパンのコンテンツを含まない構造・健全性の概要を確認するには、python3 scripts/summarize_traces.py spans.jsonlを使用します。親が見つからない場合、ルート数が1以外の場合、親の循環がある場合、または連結成分が分離している場合は、終了コード1を返します。--strictを追加すると、コンテンツ、個人データ、秘密情報、または認証情報を含む可能性の高いフィールドが見つかった場合も終了コード1を返します。原子的なファイル書き込みには--output summary.jsonを追加します。出力先は新しいパスまたは通常のファイルである必要があり、表記、解決後のパス、シンボリックリンク、ハードリンクのいずれによっても入力と同じ場所を指してはなりません。検出結果にはフィールドパスと理由の分類のみが含まれ、疑わしい値は含まれません。

安全性と権限

• 秘密情報、認証トークン、生の認証情報、決済データ、または未承認の個人データは決して記録しません。
• 承認なしに、本番環境での記録を有効化したり、保持期間を変更したり、テレメトリをエクスポートしたり、アクセス範囲を広げたりしません。
• 最小権限の原則に従って生のトレースへのアクセスを制限し、機微なテレメトリへのアクセスを記録します。
• 必須の監査制御でフェイルクローズ動作が求められる場合を除き、計装の失敗によってユーザー向け処理をブロックしないようにします。
• トレースは不完全な証拠として扱います。テレメトリがないことは、アクションが発生しなかった証明にはなりません。

検証

• 合成リクエストを最初から最後まで追跡し、想定されるすべてのスパンが同じトレース ID を共有し、ルートがちょうど 1 つで、有向非巡回の連結親子グラフを形成していることを確認します。
• ツールのエラー、タイムアウト、再試行、拒否、承認の各経路を発生させ、ステータスと親子関係を検証します。
• 出力されたテレメトリを検索し、埋め込んだシークレットや個人データのカナリアがないことを確認します。
• 生のスパンからダッシュボードのメトリクスを再計算し、単位、分母、時間枠を確認します。
• アラートに担当者名と診断コンテキストが含まれ、高カーディナリティのディメンションが使われていないことを確認します。

障害への対処

• トレースの伝播が途切れた場合は、相関フィールドを含むローカルログを保持し、サービス間の結論が不完全であることを明示します。
• タイムスタンプが信頼できない場合は、プロセス内で単調増加する時間に基づく所要時間を優先し、ホスト間の順序について誤った判断を避けます。
• テレメトリ量が予算を超えた場合は、重要なエラーを破棄する前に、詳細な属性と通常トラフィックのサンプリングを減らします。
• 機密コンテンツが見つかった場合は、収集を停止してアクセスを制限し、インシデントポリシーに従い、認可された保持担当者の承認を得た場合に限り削除します。

例

「リリース後にリサーチエージェントの処理速度が低下した原因を調べる」場合は、バージョンタグ付きのエンドツーエンドトレースを比較し、取得、モデル、ブラウザツールの各スパンで p95 レイテンシを切り分け、再試行とキュー遅延を調査し、サンプリングに変更がなかったことを確認して、デプロイ時刻と回帰を関連付けます。そして、原因となった段階、影響を受けたコホート、証拠の限界、監視対象の修正策を提示します。