AIエージェントのオブザーバビリティは、ユーザーリクエスト、モデル呼び出し、ツール選択、ポリシー判断、ツール実行、下流への効果、再試行、最終responseをまたいで、一つの実行を再構築できる必要があります。ログ、metric、trace、評価はそれぞれ別の問いに答えるため、モデルのテキストを収集するだけでは不十分です。
失敗した、または高コストのワークフローから始め、一つの識別子を正式なバックエンド結果まで追跡できるか確認します。
判断と実行の経路全体をtraceする
sequenceDiagram
participant U as User
participant A as Agent
participant M as Model
participant P as Policy
participant T as Tool
participant B as Backend
U->>A: Request
A->>M: Model call
M-->>A: Tool selection
A->>P: Authorize identity and action
P-->>A: Decision
A->>T: Tool call with operation ID
T->>B: Downstream request
B-->>T: Authoritative result
T-->>A: Structured result
A-->>U: Response
実行全体にはtrace、モデルとツールの処理にはspan、traceより長く続く可能性がある副作用にはoperation IDを使います。可能ならtool-call IDをサーバーまで伝えます。データベースrowから、完全なtraceを保存せずoperationとtraceへ戻れるようにします。
OpenTelemetryはモデル、エージェント、ツールのspan向けにGenAIセマンティック規約を公開しています。規約はまだ発展中なのでversionを固定し、実験的なattribute名をアプリケーション全体へ散らさず、小さな内部schema layerを設けます。
実行を説明する事実を取得する
モデルspan
provider、model、response identifier、latency、token usage、finish reason、retry count、prompt template versionを記録します。完全なプロンプトはポリシーで許可される場合だけ保存します。通常のtraceには、hash、redact済みsample、保護された参照で十分な場合があります。
ツールspan
表示されるツール名とversion、tool-call ID、redact済み引数、選択元、duration、result class、retry count、下流operation IDを記録します。「モデルがツールを選択」「ポリシーがツールを許可」「バックエンドがアクションを完了」を分けます。
ポリシーと承認のspan
代理対象のID、テナント、リソース、アクション、ポリシーversion、判断、reason code、approval referenceを記録します。access tokenや生のシークレットは決して記録しません。拒否されたリクエストは期待されたポリシー結果であり、必ずしもアプリケーションエラーではありません。
復旧span
再開した作業を元のworkflowとoperationへ紐づけます。システムが再試行したか、結果不明を照合したか、完了済みアクションを補償したか、人間のレビュー待ちで停止したかを記録します。障害復旧ガイドでこれらの分岐を説明しています。
metricは説明ではなく傾向に使う
集約metricには次を含めます。
- 成功、失敗、拒否、キャンセルされた実行数
- タスク完了率と人間へのescalation率
- percentile別のモデルとツールのlatency
- タスク・テナント単位のtokenとプロバイダーコスト
- ツール選択、検証、認可、バックエンドのerror rate
- 再試行、反復呼び出し、loop停止、結果不明
- queue delay、active run数、checkpoint age
プロンプトテキスト、ユーザーID、ツール引数、trace IDのような無制限の値をlabelへ使わないでください。これらは保護されたログまたはtraceへ置き、metricのdimensionを限定します。
ログを個別のredact済みイベントとして保持する
ログはデプロイ変更、ポリシー判断、操作遷移、プロバイダーエラー、クリーンアップに役立ちます。安定したevent名と構造化fieldを使います。同じ完全なモデルpayloadをすべてのレイヤーで記録しないでください。
データがプロセスから出る前にredactします。シークレット、Authorization header、個人データ、取得ドキュメント、ツール出力はプロンプトとエラーに現れる可能性があります。export後にsampleしても、漏えいは取り消せません。
評価で品質を測る
テレメトリーは何が起きたかを伝えます。しかし期待する振る舞いがなければ、responseが有用だったか、ツール選択が正しかったかを判断できません。本番障害とsample済みtraceをversion管理した評価セットへ追加し、モデル、プロンプト、ツール契約を変更する前に実行します。
AIエージェント評価ガイドでは、決定論的assertion、model judge、反復試行、release gateを分けています。
人間が対処できるアクションを中心にalertを作る
デプロイ後に増えた広範な認可エラー、破壊的ツール呼び出しの急増、trace連続性の欠落、反復する結果不明、queue age、支出上限、呼び出し回数または時間予算を超える実行など、対応方法がある条件にalertを出します。
すべてのモデルエラーでpageを送らないでください。まずprovider、model、tool、release、result classごとにまとめます。dashboardはノイズの多い品質変化を示せますが、pageは具体的な封じ込めまたはrollbackアクションへつながるべきです。
dashboardを増やす前に一つのtraceを監査する
実際の実行を一つ選び、手動で追います。prompt version、tool list、policy decision、downstream request、business result、cost、retryを特定できるか確認します。traceから影響を受けたoperationを、operationからtraceを見つけられるでしょうか。
以下のプロンプトは、データを送信せずにリポジトリに対して監査を行います。別の集約chartを作るより、最初に欠けたlinkをinstrumentation taskにする方が有効です。