AIアプリのオブザーバビリティ｜ログ・トレース・品質・費用の設計

AIアプリのオブザーバビリティは、遅い・高い・誤るという結果だけでなく、どの入力、モデル、プロンプト、検索結果、ツール実行がその結果を生んだかを再現できる状態です。 本稿は、社内文書を検索して回答する業務アプリを例に、機密情報をログへ残し過ぎず、品質・応答時間・費用・障害を一つの要求IDで追う実装手順を示します。読み終えた時点で、必要なログ項目、保存しない情報、アラート条件、動作確認ケースを決められます。

AIアプリのオブザーバビリティは「再現できるか」で決まる

通常のWeb APIなら、HTTPステータス、処理時間、CPU、メモリから多くの障害を切り分けられます。生成AIを含む処理では、同じ200応答でも、根拠文書を取得できなかった、別のモデルへ迂回した、ツールの一部だけ成功した、回答が業務基準を満たさなかった、という失敗が残ります。そこで、インフラ指標に加えて、入力から業務結果までの因果関係を記録します。

完成条件はダッシュボードの枚数ではありません。問い合わせ番号を一つ指定したとき、担当者が10分以内に「どの版が動いたか」「外部呼び出しはどこで止まったか」「利用者へ何を返したか」「再実行すると副作用があるか」を説明できる状態を目標にします。10分は本稿の運用目標例であり、実測統計ではありません。この監視設計にも、記録していない外部要因や利用者の判断理由までは再現できないという限界があります。自社の一次対応SLOに置き換えてください。

共通の属性名でログ、メトリクス、トレースを結ぶ考え方は、OpenTelemetry Semantic Conventions 1.43.0が支えています^[1]。一方、OpenAIのTrace gradingは、エージェントの判断やツール呼び出しを経路単位で評価する方法を示します^[4]。前者は観測データの語彙、後者はAI経路の品質評価に使い、どちらも回答の真実性を自動証明するものではありません。

「APIが成功した」と「業務が完了した」を同じ成功フラグへ押し込むと、品質低下も部分失敗も見えなくなります。技術結果と業務判定は別項目で保存します。

前提環境とログを閲覧できる権限を先に決める

対象例は、利用者が社内規程について質問し、アプリが文書検索、モデル生成、引用検査を経て回答する構成です。アプリ、検索基盤、モデルAPI、監視基盤の時計を同期し、検証環境では本番の秘密鍵を使いません。トレースを横断するため、入口で128ビット以上のランダムな要求IDを発行し、外部APIにはベンダーが許すメタデータまたは自社側の対応表で関連付けます。

ログ閲覧権限は、開発者全員へ常時与える設計にしません。運用担当はマスキング済みのイベント、セキュリティ担当はアクセス記録、障害調査責任者は承認された期間だけ復号可能な原文、というように分けます。閲覧そのものを監査ログへ残し、退職・異動時にはID管理基盤から失効させます。

この設計をそのまま使わないケース

入力原文を法令・契約上保存できない業務、またはゼロデータ保持を条件とする環境では、全文トレースを前提にしません。ハッシュ、分類、件数、処理時間、版IDだけで原因を絞れるようにし、必要な再現は利用者が再提出した検証データで行います。OpenAI Agents SDKの公式Tracing文書では、生成と関数呼び出しの入出力に機微情報が含まれ得ること、既定で機微データを含める設定であること、ZDR対象組織では同サービスのトレースを利用できないことが説明されています。これは同SDK固有の仕様なので、自社基盤へ一般化せず採用製品ごとに確認します^[2]。

トレースを要求・生成・検索・ツール・評価の5種類に分ける

一つの巨大なJSONへすべてを詰めると、検索性とアクセス制御が悪化します。要求全体をtrace、各処理をspan、時点の出来事をeventとして扱い、親子関係で結びます。OpenTelemetry Semantic Conventions 1.43.0は、トレース、メトリクス、ログなどで共通の属性名を使う意義を示しています。一方、生成AI向け属性は専用リポジトリへ移動され、開発段階の項目を含みます。したがって、gen_ai.*を採る場合は利用した規約版を固定し、非互換変更に備えます^[1]。

モデルへのプロンプト全文や検索クエリは、障害解析には便利でも、個人情報や営業秘密を複製します。通常ログには文字列を置かず、入力分類、長さ、テンプレート版、データセットIDを記録します。原文が必要な調査だけ、別ストレージへ暗号化し、短い保持期間と案件単位の閲覧承認を設定します。

{
  "trace_id": "8f4c...",
  "span_id": "retrieval-02",
  "parent_span_id": "request-01",
  "operation": "retrieval",
  "app_release": "2026.07.30.1",
  "prompt_template": "policy-qa@17",
  "model": "provider/model-snapshot",
  "principal_type": "employee",
  "authorization_policy": "doc-acl@9",
  "retrieved_document_ids": ["rule-2026-04"],
  "input_tokens": 1840,
  "output_tokens": 312,
  "duration_ms": 1460,
  "technical_status": "ok",
  "business_status": "needs_review",
  "error_code": null
}

この例は架空のスキーマであり、OpenTelemetryの規定値をそのまま転記したものではありません。principal_typeには社員番号を入れず、認可判定に使った区分を残します。文書IDは閲覧権限を持つ利用者だけが解決できるようにし、ログから本文へ迂回できない構成にします。

最低限の関連付け

• 要求span: 受付時刻、利用経路、アプリ版、最終ステータス
• 生成span: モデルの固定名、パラメータ、トークン数、終了理由
• 検索span: 索引版、フィルター、取得ID、スコア、0件理由
• ツールspan: ツール版、認可結果、冪等キー、副作用、戻り値の分類
• 評価event: 採否、訂正種別、確認者の役割、評価基準版

入口から業務判定までを6段階で計装する

1. 入口で要求IDと利用者の権限スナップショットを作る

リバースプロキシまたはアプリの最初の処理で要求IDを発行し、認証主体、利用経路、テナント、認可ポリシー版を記録します。アクセストークンやCookieは保存しません。認可エラーはモデルへ渡さず、authorization_deniedで終了します。確認では、権限を持たない試験利用者が文書検索へ到達しないことをトレースで確かめます。

2. プロンプトとアプリ設定を内容ではなく版で追う

システム指示、few-shot例、出力スキーマ、モデル設定をGitのコミットまたは変更管理IDへ結びます。運用画面から変更できる値も設定スナップショットへ含めます。モデルの別名だけでは提供側の更新を区別できない場合があるため、取得できる固定スナップショット名や応答ヘッダーを残します。版を復元できない要求は、品質比較の母数から除外して調査対象にします。

3. RAGは「検索0件」と「権限で0件」を別の結果にする

検索クエリ、ACLフィルター、索引版、上位k件、再順位付けの有無をspanへ分けます。権限がなく0件だった場合と、権限内に関連文書がなかった場合では利用者への説明が違います。前者の詳細を回答へ漏らさない一方、運用ログでは認可拒否を集計します。文書本文を保存しないときも、文書ID、版、該当箇所、検索スコアは再現に必要です。

4. ツール実行は副作用の前後を記録する

メール送信やチケット更新では、モデルが引数を作った時点、アプリが検証した時点、人が承認した時点、外部サービスが受理した時点を分離します。タイムアウト後に外部処理が完了している可能性があるため、同じ冪等キーで状態照会してから再試行します。ログには秘密鍵を含む引数を残さず、項目名、値の型、対象IDのハッシュ、認可結果を保存します。

5. 出力検査をモデル呼び出しとは別spanにする

JSONスキーマ、引用の存在、禁止情報、数値整合、業務ルールの検査結果を個別に持たせます。生成成功後の検査不合格をモデル障害へ数えると、提供側の稼働率と自社品質が混ざります。再生成した場合は元のspanを上書きせず、試行番号と再生成理由を追加します。上限回数を超えたら人へ回し、無限ループを防ぎます。

6. 人の採否を最終イベントとして戻す

承認、軽微修正、全面書き直し、利用中止を選択式で取り、必要なら訂正箇所と理由を別記します。自由記述だけでは集計できず、選択肢だけでは改善理由を失います。OpenAIのTrace grading文書は、エージェントのトレースを構成する判断やツール呼び出しを採点対象にできる考え方を示しています。特定製品を使わなくても、最終回答だけでなく経路を評価する設計は有効です^[4]。

失敗時は再試行・代替・保留・停止を使い分ける

「失敗したら3回再試行」のような一律ルールは、費用増加と二重実行を招きます。失敗を一時的な通信障害、恒久的な入力不備、認可拒否、品質不合格、部分成功へ分け、次の動きを固定します。利用者へ返すメッセージには内部構成や権限外資源の存在を含めません。

タイムアウトのspanは「失敗」で閉じても、外部サービスの状態は「不明」です。この差を表すため、technical_status=timeoutとside_effect_status=unknownを分けます。後から状態照会で完了が判明したら、元ログを書き換えず補正イベントを追加します。監査時に当初判断と確定結果の両方を追えるようにするためです。

SLOとアラートは利用経路ごとに設定する

全要求の平均値だけを見ると、重要経路の悪化を見逃します。社内検索、顧客向け回答、文書下書き、外部更新を別サービスレベル指標にします。顧客向け回答では品質不合格と応答遅延、外部更新では越権拒否と部分成功を優先する、といった重み付けが必要です。

件数が少ない経路では割合だけをアラートにしません。たとえば1件中1件の失敗は100%ですが、サービス全体の障害とは限りません。「率と母数」「連続回数」「影響区分」を組み合わせます。品質は自動評価だけで決めず、週ごとに固定評価セットと無作為抽出を人が確認します。固定データと評価基準で変更前後を比較する方法は、OpenAIのEvals公式文書を参照できます^[3]。

費用は成功要求ではなく採用された業務結果で割る

モデルの請求額だけを1件当たり費用にすると、再試行、検索、外部ツール、人の確認を落とします。次は架空の月次試算です。実測値ではありません。

モデル費       96,000円
検索基盤費      24,000円
監視基盤按分    18,000円
人の確認費      75時間 × 3,000円 = 225,000円
月間総費用      96,000 + 24,000 + 18,000 + 225,000 = 363,000円
生成回答        6,000件
人が採用        4,950件
採用結果単価    363,000円 ÷ 4,950件 = 約73.3円/件

同じ月にAPI単価が下がっても、採用件数が4,000件へ落ちれば単価は約90.8円です。費用アラートでは、入力トークンの増加、再試行率、検索件数、確認時間のどれが変わったかをspanから分解します。単価上昇の原因が新しい規程へ切り替えた直後の必要なレビューなら、直ちにモデルを安価なものへ変える判断は適切ではありません。

プロンプトやモデル変更の費用比較では、固定した40件を共通の時間帯で実行し、採用基準も変えません。キャッシュの有無、ストリーミング、最大出力長が違う結果を横並びにしないでください。費用差だけでなく、合格率の信頼区間と重大誤り件数を併記します。

正常・境界・異常の40件でトレースを検収する

動作確認は、画面に回答が出たかではなく、期待するspanと停止動作が残ったかまで確認します。40件は通常20件、境界10件、異常10件という本稿の想定例です。対象業務の低頻度だが重大な例外を追加し、固定ケースは変更管理下に置きます。

1. 正常系: 権限内文書を取得し、引用検査を通過する。要求、検索、生成、検査、採否の親子関係が一つのtraceに並ぶ。
2. 情報不足: 関係文書が0件の質問で、モデルを呼ばず「資料不足」を返す。存在しない引用が作られない。
3. 権限外: 別部署の文書IDを直接指定しても検索結果とログ画面の双方で本文を見せない。
4. タイムアウト: モデルAPIを意図的に遅延させ、最大2回で終了する。待機時間と試行番号が残る。
5. 部分成功: 外部更新の応答を遮断し、同じ操作を再送せず状態照会へ移る。
6. 機密情報: ダミーの氏名・秘密鍵形式を入力し、通常ログに原文が出ない。許可のない閲覧者は隔離ログを開けない。
7. 版変更: プロンプト版を更新し、変更前後の要求が別版として集計される。
8. 品質不合格: 誤った数値を含む出力を模擬し、技術成功のまま業務不合格へ分類される。

検収では、40件すべての期待span存在率を計算します。たとえば必要spanが合計210個あり、208個を確認できた場合は208÷210×100=99.05%です。この2個が副作用操作の承認spanなら、率が高くても不合格です。件数と重大度を併用し、重大項目は一件でも欠落したら公開を止めます。

OpenAIのEvals公式文書は、テストデータと評価基準を用意して反復的に比較する仕組みを説明しています^[3]。監視検収では特定ベンダーの評価機能へ限定せず、期待結果、実行条件、実際の出力、判定理由を再実行可能な形で保存します。

サンプリングと属性数を制御し、調査可能性を失わない

全要求の全文と全spanを永久保存すると、費用と漏えい面積が増えます。一方、1%の無作為抽出だけでは、発生率0.1%の重大エラーをほぼ取り逃がします。通常成功は低率でサンプリングし、認可拒否、部分成功、品質不合格、利用者からの訂正は100%保存する、という事象別の方針が必要です。

表の率と期間は想定値であり、法令、契約、調査SLAに合わせて変更します。サンプリング判断は処理の最後だけで行うと、途中で落ちた要求を失います。入口では小さな暫定記録を作り、終了状態に応じて詳細を保持するtail samplingを検討します。監視基盤がtail samplingへ対応しない場合は、重大イベントを別ログへ確実に出します。Agents SDKのTracing文書が機微な入出力を含み得ると説明しているため、保存率を上げる前に内容記録の設定を再確認します^[2]。

高カーディナリティ属性も管理します。社員ID、文書ID、trace_idをメトリクスのラベルにすると、時系列数が爆発します。これらはログ検索用の属性に置き、メトリクスはモデル版、処理種別、結果区分、テナント階層など上限を管理できる値へ限定します。新しいラベル値が一時間で1,000を超えたら収集を止める、という上限を監視基盤側に設定します。

保存率を変えたら、変更前後で障害検知率を比較します。40件の異常注入を行い、詳細traceを取得できた件数が39件なら取得率は39÷40×100=97.5%です。1件が認可逸脱なら率に関係なく不合格とし、ルールの優先順位を修正します。

ダッシュボードを初動手順と一対一で結び付ける

グラフを増やしても、通知後に誰が何を確認するか決まっていなければ復旧は速くなりません。各アラートに、影響を受ける経路、最初に見るspan、停止スイッチ、利用者への告知、専門担当への引き継ぎ条件を付けます。ダッシュボードの所有者と手順書の所有者を同じ変更審査へ参加させます。

通知の優先度は、数値の大きさだけでなく影響で決めます。費用が20%上がっても利用上限内なら夜間の分析でよい一方、他人の回答が一件混ざれば即時停止です。通知には入力本文や秘密情報を載せず、trace_idと分類だけを送り、権限を持つ画面で詳細を開きます。

月に一度、過去の通知から一件を選び、当番者がランブックだけで停止、調査、復旧判断まで進める演習を行います。所要時間を「検知から担当確認」「担当確認から封じ込め」「封じ込めから復旧」に分けます。全体時間だけでは、連絡網と技術調査のどちらが遅いか判断できません。

変更前後を同じ母集団で比較し、監視基準を再設定する

モデル、プロンプト、索引、ツールの更新は、正常値そのものを変えます。新モデルが短い回答を返せばoutput tokenと応答時間は下がり、引用数も変わります。旧基準の閾値をそのまま使うと、改善を異常とみなすか、本当の劣化を隠します。

リリース候補には固定40件を実行し、旧版と新版の技術完了率、引用合格率、p95、採用結果単価、重大失敗を並べます。たとえば旧版が引用合格38/40、新版が39/40でも、新版の不合格1件が重要規程の取り違えなら採用しません。率の差だけでなく失敗内容を読みます。

限定配備では利用者の5%へ新版を割り当て、要求属性は同じ収集規則で記録します。モデルルーターが難しい案件だけ新版へ送る構成では単純比較できないため、案件種別と入力長で層別します。二週間または500件のうち後に到達した時点で基準値を再計算する、というのは本稿の提案例です。

監視基準の変更もリリース記録へ含めます。アラートを静かにするため閾値だけを上げる変更は認めず、基準期間、母数、除外条件、承認者を残します。更新後に旧版へ切り戻した場合は、監視閾値も旧版用へ戻ることを自動試験します。

監視で解決できない問題と専門担当へ渡す条件

ログが詳細でも、学習データの権利、モデル内部の因果、将来の同一出力は保証できません。トレースは起きた処理を説明する材料であり、回答の真実性を自動的に証明するものではありません。個人情報の保存可否は法務・プライバシー担当、侵害兆候はCSIRT、モデル更新による品質低下は評価責任者へ渡します。

次のいずれかに該当したら、アプリ担当だけで復旧を続けません。資格情報または個人データがログへ出た、取消不能な操作の状態が不明、異なる利用者のtraceが結合した、監査ログが欠落した、提供者側のモデル版を特定できず重大誤回答が再現しない、という場合です。対象経路を停止し、証拠保全と影響範囲の確認を優先します。

最初の導入範囲は、社内QAのように結果を取り消せて人へ戻せる一経路に絞ります。40件の検収と二週間の限定運用で、重大span欠落0件、権限逸脱0件、採否記録率95%以上を満たしたら、次の経路を追加します。これらは提案値であり、業務責任者が影響度に合わせて承認します。

次に取る行動：失敗した一件を要求IDで再構成する

直近の失敗から一件だけ選び、画面の要求IDを起点に、モデル版、取得文書、ツール実行、出力検査、利用者へ返した状態を10分以内に説明できるか試してください。途中で追跡が切れた場所が、最初に追加すべき属性またはログです。入力本文を保存しなければ調査できない場合は、保存期間と閲覧承認も同時に決めます。

参考文献・出典

1. OpenTelemetry公式仕様「OpenTelemetry semantic conventions 1.43.0」―AIアプリを含む分散処理でログ・メトリクス・トレースの属性名をそろえる規約（2026年7月30日参照）
2. OpenAI公式ドキュメント「OpenAI Agents SDK: Tracing」―AIエージェントの生成・ツール実行のトレースと機微データ設定（オンライン版、2026年7月30日確認）
3. OpenAI公式ドキュメント「Working with evals」―AIアプリの品質を固定データと評価基準で比較する手順（オンライン版、2026年7月30日確認）
4. OpenAI公式ドキュメント「Trace grading」―実行トレース内の判断とツール呼び出しを採点する方法（オンライン版、2026年7月30日確認）