AI可観測性実装チェックリスト：本番導入の20ステップ
AI可観測性の実装チェックリストは、「APIが稼働しているか？」よりも難しい問いに答えるべきです。本番のAI機能は、HTTP 200を返しながら、誤った答えを返したり、古い取得コンテキストを使ったり、間違ったツールを呼び出したり、高コストのフォールバックを介して再試行したり、機密のプロンプトデータをログに漏らしたり、実用には遅すぎる応答時間になったりすることがあります。
実践的な目標は、ユーザーに見える各結果を、それを生み出したモデルの試行、取得ステップ、ツール呼び出し、ポリシー判断、レイテンシ、トークン使用量、コストに結び付けることです。そのためには、従来のアプリケーションテレメトリに加え、AI固有のコンテキストと評価シグナルが必要になります。
このガイドでは、LLMアプリケーション、エージェント、検索拡張生成システム、マルチモデルゲートウェイ向けの段階的な実装計画を示します。ベンダー中立であり、可能な限りOpenTelemetryの概念を使用しています。また、シグナルから意思決定へのマップ、受け入れテストマトリクス、7日間のロールアウト計画、テレメトリ契約、インストრუსメンテーションパターン、アラート運用手順、ベンダースコアカードも含め、チームが要件定義から運用開始まで進められるようにしています。
AI可観測性を一文でいうと
AI可観測性とは、相関のあるトレース、メトリクス、ログ、評価、ユーザー結果の集合から、AIワークフローの挙動、品質、信頼性、安全性、コストを説明できる能力です。
モニタリングは、しきい値が変化したことを知らせます。可観測性は、なぜ変化したのか、どのリクエスト、モデル、プロンプト、検索結果、ツール、テナント、リリースが関与していたのかを特定するのに役立ちます。
このガイドのAI可観測性実装チェックリストは、一度きりの文書化作業ではなく、リリースゲートとして使用してください。モデル、プロンプト、検索インデックス、ツールスキーマ、ルーティングポリシー、評価器を変更するたびに再実行してください。
AIアプリケーションでは、1件のリクエストに複数の異なる試行が含まれる場合があります。
ユーザーアクション
└─ アプリケーションワークフロー
├─ 検索クエリ
├─ モデル試行 1
├─ ツール呼び出し
├─ モデル試行 2
└─ 検証とユーザーに見える結果
これらのステップを1つのトレースまたはリクエストIDの下で結び付けられない場合、デバッグは推測に頼ることになります。
AI可観測性の最小データモデル
データモデルはAI可観測性実装チェックリストの基盤です。ダッシュボード、アラート、評価、インシデントクエリはすべて、一貫した相関フィールドに依存するためです。
まず、ワークフローレベルの1つのトレースと、各主要操作の子スパンから始めます。OpenTelemetryは、トレース、メトリクス、ログ、バゲッジを中核シグナルとして定義しています。その生成AIセマンティック規約は、モデルおよびエージェント操作のための発展途上の語彙を提供しており、2026年8月4日時点では、専用のOpenTelemetryセマンティック規約リポジトリで保守されています。これらの規約は進化し得るため、実装するバージョンを固定し、コード全体にベンダー固有のフィールド名を散在させるのではなく、小さな内部互換レイヤーを維持してください。
少なくとも、次のフィールドグループを収集してください。
| フィールドグループ | 記録する内容 | 重要な理由 |
|---|---|---|
| 相関 | trace_id, request_id, セッションID、ワークフロー、環境、リリース |
リクエスト全体のパスを結び付ける |
| ルート | プロバイダー、要求したモデル、解決されたモデル、リージョン、エンドポイントまたはルートの別名 | リクエストが実際にどこで実行されたかを示す |
| 試行 | 試行回数、再試行理由、フォールバック元と先 | 1件のユーザーリクエストと複数の課金対象呼び出しを区別する |
| パフォーマンス | キュー時間、最初のトークンまでの時間、総レイテンシ、ツールと検索のレイテンシ | 遅い段階を特定する |
| 使用量 | 入力、キャッシュされた入力、出力、推論、またはプロバイダー固有の使用量フィールド | 容量とコストを説明する |
| 結果 | ステータス、正規化されたエラークラス、終了理由、検証結果 | 通信の成功とタスクの成功を区別する |
| 品質 | 評価器のバージョン、スコア、合格/不合格、ユーザーフィードバック、受け入れられた結果 | 応答が有用だったかを追跡する |
| ガバナンス | テナント、ポリシー判断、マスキング状態、保持クラス | プライバシーと監査コントロールを支援する |
生のプロンプトと応答を必須フィールドとして扱うのは避けてください。多くのシステムでは、既定で無効にするか、別途管理された評価データセットにのみ保存すべきです。
すべてのシグナルを運用上の意思決定に結び付ける
テレメトリが多ければ自動的に良いわけではありません。属性、メトリクス、ダッシュボードを追加する前に、それが支える意思決定と、その意思決定の責任者を明確にしてください。
| シグナル | 答える問い | 典型的な判断 | 主担当 |
|---|---|---|---|
| 承認済み完了率 | ワークフローは顧客のタスクを解決したか？ | ロールバックする、プロンプト/モデルを変更する、または下流の失敗を調査する | プロダクトおよびAIエンジニアリング |
| p95エンドツーエンドレイテンシ | 完全な体験は十分に速いか？ | ルートを変更する、検索/ツールのレイテンシを削減する、またはストリーミングを調整する | プラットフォームエンジニアリング |
| 最初のトークンまでの時間 | ストリーミングは応答性があると感じられるか？ | キューイング、プロバイダールート、またはプロンプトサイズを調整する | プラットフォームエンジニアリング |
| フォールバック率 | 主要ルートは健全で経済的か？ | プロバイダーの健全性、容量、またはルートポリシーを調査する | 信頼性エンジニアリング |
| 承認済み結果あたりのコスト | 再試行や低品質結果で節約が相殺されていないか？ | モデルの組み合わせ、キャッシュ、プロンプトサイズ、または検証を変更する | エンジニアリングおよびFinOps |
| 検索による根拠付けの合格率 | 回答は許可された関連コンテキストを使用したか？ | インデックス、フィルター、リランカー、または引用検証を再構築する | 検索/RAG担当者 |
| ツール照合失敗 | 外部の副作用は安全に完了したか？ | ツールを停止する、状態を照合する、または冪等性を修復する | アプリケーション担当者 |
| マスキング失敗件数 | 機密データがエクスポーターに到達しているか？ | エクスポートを停止する、テレメトリを隔離する、またはポリシーを更新する | セキュリティ/プライバシー |
この表は、ダッシュボードに多数のチャートがあるのに、変更がどのアクションを引き起こすべきか誰にも分からない、という一般的な失敗モードを防ぎます。
実用的なトレース構造
ユーザーに見えるワークフローには1つのトレースを使い、プロバイダ呼び出しごとに無関係なトレースを分けないでください。ルートは顧客のタスクを表し、子スパンは結果に寄与した操作を表すべきです。
workflow: answer_support_question
attributes: tenant_class, release, accepted_outcome, final_status
├─ retrieval.search
│ attributes: index_version, top_k, authorization_result
├─ gen_ai.attempt
│ attributes: provider, requested_model, resolved_model, attempt=1
├─ tool.lookup_order
│ attributes: tool_schema_version, idempotency_key, result
├─ gen_ai.attempt
│ attributes: provider, resolved_model, attempt=2, fallback_reason
└─ evaluation.validate_answer
attributes: evaluator_version, pass, score_band
OpenTelemetry の生成AIセマンティック規約は、まだ進化中です。共通語彙として扱いつつ、規約のバージョンを固定し、ローカル拡張を記録し、アップグレードはステージングでテストしてください。accepted_outcome のようなビジネス成果は、自社の安定したアプリケーション名前空間に保持し、セマンティック規約の変更でプロダクトレポーティングが壊れないようにします。
フェーズ1: ダッシュボードを追加する前に成果を定義する
1. ワークフローと受け入れ可能な成果を定義する
まずプロバイダ全体のトークンチャートから始めないでください。次のような顧客タスクから始めます:
- サポート回答がエスカレーションなしで受け入れられる;
- コードパッチがテストに合格する;
- 抽出結果が必要なスキーマに一致する;
- エージェントが手動復旧なしで要求されたアクションを完了する;
- 生成メディアが製品レビューのゲートを通過する。
機械可読な workflow 名と accepted_outcome または同等の結果を作成します。これが、品質、コスト、信頼性メトリクスの分母になります。
2. 障害分類を定義する
少なくとも次のクラスを分けてください:
- transport failure: タイムアウト、接続エラー、または上流の 5xx;
- capacity failure: レート制限、クォータ、キュー飽和、またはコンテキスト制限;
- contract failure: 無効な JSON、欠落フィールド、未対応のツールスキーマ、または壊れたストリーム;
- quality failure: 回答が無関係、誤り、不完全、または根拠に基づいていない;
- safety failure: ポリシー違反、プロンプトインジェクションの成功、または安全でないツール実行;
- business failure: 技術的には有効だが、ユーザーが拒否または離脱する出力。
単一の error=true 次元では不十分です。どの問題なのかが隠れてしまい、必要なのがインフラ対応なのか、プロンプト変更なのか、モデル変更なのか、プロダクト変更なのかが分からなくなります。
3. 初期サービスレベル指標を選ぶ
ユーザー体験を反映する小さなセットから始めます:
workflow availability = accepted workflow completions / eligible workflow starts
quality pass rate = evaluator-passing completions / evaluated completions
p95 end-to-end latency = p95(workflow completed - workflow started)
cost per accepted outcome = total workflow cost / accepted outcomes
プロバイダーの可用性は製品のSLIではなく、診断用メトリクスとして扱ってください。取得、ツール、検証、またはルーティングが壊れていると、プロバイダーが正常でもワークフローは失敗し得ます。
フェーズ2: 完全なリクエスト経路を計測する
4. ユーザーに見えるワークフローごとに1つのルートスパンを作成する
取得やモデルのルーティングが始まる前に、アプリケーション境界でルートトレースを生成してください。そのコンテキストを、キュー、ワーカー、ゲートウェイ、ツールサービス、コールバック全体に伝播させます。
次の用途には子スパンを使用します:
- 取得と再ランキング;
- すべてのモデル試行;
- 各ツール呼び出し;
- ガードレールまたはポリシーのチェック;
- 出力の解析と検証;
- フォールバックの選択;
- 永続化と下流への配信。
5. 要求されたルートと解決されたルートを記録する
クライアントが指定したモデルが、実際にリクエストを処理したモデルとは限りません。以下の両方を記録してください:
{
"ai.requested_model": "support-balanced",
"ai.resolved_provider": "provider-b",
"ai.resolved_model": "model-version-2026-07",
"ai.route_reason": "primary_rate_limited",
"ai.attempt": 2
}
これはマルチプロバイダーシステムでは不可欠です。また、モデルのフォールバック戦略を、見えないものではなく監査可能なものにします。
6. ストリーミングを別個に計測する
総レイテンシだけではストリーミング体験を表せません。次を取得してください:
- キュー滞留時間;
- 接続およびプロバイダーのレイテンシ;
- 最初のトークン、または最初の有用なイベントまでの時間;
- 生成時間;
- エンドツーエンドの完了時間;
- クライアントによるキャンセル時刻。
リクエストは総レイテンシが許容範囲でも、最初のトークンまでの時間が長い場合があります。また、最初のトークンはすぐ出ても、その後に停止してしまうこともあります。
7. リトライとフォールバックを第一級の試行として扱う
最初の失敗した試行を最終的な成功で上書きしてはいけません。1つのワークフロースパンには、課金対象となるすべての試行を含めるかリンクしてください。具体的には:
- リトライ回数;
- トリガー;
- バックオフ時間;
- プロバイダーとモデル;
- トークン数とコスト;
- 部分出力の状態;
- 最終結果。
これにより、リトライの連鎖が「成功率100%」として見えてしまうのを防げます。
フェーズ3: AI固有の品質コンテキストを追加する
8. プロンプト、ツール、ポリシー、評価器をバージョン管理する
生のコンテンツだけでなく、安定した識別子を保存してください:
prompt_version
tool_schema_version
retrieval_index_version
policy_version
evaluator_version
route_policy_version
これらの次元により、変更前後のリリースを比較できます。バージョン管理がなければ、品質低下の原因特定は難しくなります。
9. 取得品質をトレースする
検索拡張生成では、次を記録してください:
- クエリのバージョンとフィルター;
- 取得レイテンシ;
- ドキュメントまたはチャンクID;
- ソースの新しさ;
- top-k と再ランキング器のバージョン;
- 空結果率;
- アクセス制御の判定;
- 引用またはグラウンディング検証の結果。
完全な機密文書を汎用のトレース保存領域に置かないでください。デバッグポリシーで明示的にコンテンツ取得が許可されていない限り、管理された参照またはハッシュを保存します。
10. ツール呼び出しと副作用をトレースする
各ツールスパンには、ツール名、スキーマバージョン、認可判定、レイテンシー、正規化された結果、そして外部への副作用を発生させたかどうかを含める必要があります。
副作用のあるツールについては、冪等性キーと再調整状態も記録してください。これは、モデル呼び出しがツールの完了後にタイムアウトした場合に重要です。
11. オンライン評価とオフライン評価を統合する
オンラインシグナルは高速ですがノイズが多く、サムズアップ、離脱、再生成、修正、エスカレーション、またはタスク完了などがあります。オフライン評価はより遅いものの制御しやすく、精選されたテストセット、ルーブリック採点、実行可能なテスト、および人手レビューがあります。
両方を同じワークフローとバージョン識別子に結び付けてください。変更を明示しないまま、異なる評価者バージョンのスコアを1本のトレンドラインに混ぜないでください。
フェーズ4: プライバシー、セキュリティ、保持を制御する
12. 収集前にテレメトリを分類する
次の3つのレベルを定義します。
- メタデータ: ルート、タイミング、トークン、ステータス、バージョン、ID。
- 派生コンテンツシグナル: 長さ、言語、安全カテゴリ、評価者スコア、またはハッシュ。
- 生コンテンツ: プロンプト、応答、取得したテキスト、ツール引数、ツール結果。
メタデータは広く収集します。生コンテンツは、ユースケース、ユーザー通知、アクセス制御、保持ポリシーがそれを支える場合にのみ収集してください。
13. 収集境界でマスキングする
可能であれば、マスキングはエクスポート前に行うべきです。以下を対象にしてください。
- APIキー、ベアラートークン、Cookie、認可ヘッダー;
- メールアドレス、電話番号、口座番号、政府発行ID;
- ツール引数や取得した文書内のシークレット;
- 署名付きURLとデータベース接続文字列;
- 共有可観測性ストアで禁止されているテナント固有コンテンツ。
エクスポートされる属性には許可リストを使用してください。拒否リストでは、いずれ新しいシークレット保持フィールドを見落とします。この AI APIキー管理ガイドで説明されているのと同じ規律を適用してください。
14. データクラスごとに保持期間とアクセスを設定する
生コンテンツは、低リスクのメトリクスと同じ保持期間を継承すべきではありません。個別の保存領域、暗号化、アクセスロール、監査ログ、削除プロセスを定義してください。ポリシー文書があれば十分だと決めつけるのではなく、削除をテストしてください。
NIST AI Risk Management Framework とその Generative AI Profile は、システムライフサイクル全体にわたる継続的な測定、文書化、リスク管理を重視しています。可観測性は証拠の提供に役立ちますが、無差別なログ記録は新たなプライバシーおよびセキュリティリスクを生み出す可能性があります。
15. 高カーディナリティのディメンションを制御する
ユーザーID、トレースID、プロンプトテキスト、文書ID、または生のエラーメッセージをメトリクスラベルにしないでください。高カーディナリティのデータはトレースまたはログに保持し、その後、ワークフロー、モデルファミリー、エラークラス、環境、リージョンなどの上限付きメトリクスを派生させます。
フェーズ5: アクションにつながるアラートを構築する
16. ユーザーに影響する症状でアラートを出す
次のような症状でページングします。
- 受理された完了率が目標を下回る;
- 品質合格率がリリースのガードレールを超えて低下する;
- p95レイテンシーまたは最初のトークンまでの時間がエラーバジェットを消費している;
- 受理された結果あたりのコストが上限を超える;
- 危険な副作用またはポリシー違反の失敗;
- フォールバック率が通常帯を超えて上昇する。
プロバイダーのエラー、トークンのスパイク、検索ミスは、ユーザー向けの目標を直接脅かす場合を除き、診断用アラートまたはダッシュボード信号として使用します。
17. SLOアラートにバーンレートのウィンドウを使う
静的なしきい値はノイズが多くなりがちです。エラーバジェットのバーンレート・アラートは、サービスが許容された失敗予算をどれだけ速く消費しているかを問います。GoogleのSREガイダンスでは、より速いウィンドウとより遅い確認ウィンドウを組み合わせることで、深刻なインシデントをすぐにページできる一方、短いスパイクのたびに対応が必要になるのを防ぐことが推奨されています。
18. リリースとルートの注釈を追加する
すべてのダッシュボードには、プロンプト、アプリケーション、ルーティング、モデル、評価器のリリースを表示すべきです。デプロイの注釈を追加し、カナリア群とコントロール群を比較します。そうしないと、チームは何が変わったのかを見ずに線の動きだけを見ることになります。
フェーズ6: 本格展開前の検証
19. 失敗ドリルを実施する
少なくとも以下をテストします:
- 上流のタイムアウト;
- レート制限とクォータ枯渇;
- 不正な構造化出力;
- 部分的なストリーミング中断;
- 検索が許可されたコンテキストを返さない;
- ツールは成功したが応答が失われる;
- フォールバックによりモデルの挙動が変わる;
- テレメトリ・エクスポーターが利用不可;
- マスキング規則が未知のフィールドを受け取る。
ワークフローが安全に失敗し、トレースが整合性を保ち、アラートが適切な責任者を特定することを確認します。
20. 4段階で展開する
- シャドー: ルーティングやユーザーの挙動を変えずにテレメトリを送信する。
- カナリア: 少量のトラフィックに対して有効化し、オーバーヘッド、カーディナリティ、データ品質を比較する。
- ガード付き本番: リリースしきい値とロールバックルールを適用する。
- 本番全体: プライバシー、信頼性、コストのチェックに合格した後に拡大する。
OpenTelemetryはヘッドサンプリングとテールサンプリングのパターンをサポートします。可能な限り、すべてのエラーとまれな失敗クラスを保持し、そのうえで通常の成功トラフィックをサンプリングしてコストを抑えます。サンプリングルールは、インシデントを説明するために必要な正確なトレースを削除してはなりません。
本番受け入れテストマトリクス
受け入れテストは、AI可観測性実装チェックリストが成功リクエストだけでなく、失敗、プライバシー、テレメトリ損失のシナリオでも機能することを証明します。
スパンがトレースビューアに表示されるからといって、可観測性が完成したと宣言してはいけません。制御されたテストを実行し、各リリースゲートの証拠を保存してください。
| テスト | 注入条件 | 必要なテレメトリ証跡 | 合格条件 |
|---|---|---|---|
| 上流タイムアウト | 主要モデル経路を強制的に期限超過させる | 最初の試行のスパン、タイムアウト分類、再試行またはフォールバックの判断、最終結果 | 孤立したスパンがないこと。最終的な処理結果と総コストが可視化されていること |
| レート制限 | プロバイダーの429を返すか、テスト用クォータを使い切る | 生のプロバイダーコード、正規化されたキャパシティ分類、バックオフ時間、経路変更 | 再試行予算が上限付きで管理され、アラートが経路のオーナーを示していること |
| 無効な構造化出力 | 不正なJSONまたは必須フィールドの欠落を返す | 契約検証スパン、バリデーターのバージョン、修復試行、最終的な合否 | HTTP成功が受理済み成功としてカウントされないこと |
| ストリーム破損 | 最初のトークンの後で出力を中断する | 最初のトークンまでの時間、部分出力フラグ、課金対象使用量、再試行の判断 | 重複コンテンツとツールの二重実行が防止されていること |
| 空の検索結果 | 承認済みドキュメントを返さない | 検索フィルタ、認可結果、空結果の理由、回答ポリシー | システムが承認済みのコンテキストなし動作に従うこと |
| ツールの曖昧性 | モデルのリクエストがタイムアウトする間にツールを完了させる | 冪等性キー、副作用の状態、再照合結果 | ツールが二重実行されず、状態を復旧できること |
| 秘匿情報マスキングのカナリア | テストフィールドに合成シークレットを挿入する | エクスポートされたシークレット値を伴わないローカル検知イベント | 境界を出る前にエクスポートがブロックまたはマスキングされること |
| エクスポーター停止 | テレメトリの送信先を停止する | エクスポーターのキュー/ドロップ指標とアプリケーションの健全性 | ユーザートラフィックが信頼性予算内に収まること |
| サンプリング確認 | 高成功率トラフィックの中でまれなエラーを発生させる | エラートレースは保持され、通常の成功は設定どおりにサンプリングされる | サンプリング後もインシデント例を検索できること |
| リリース回帰 | 既知の遅延または品質低下があるカナリアをデプロイする | リリース注釈、カナリア対象群、コントロール群、SLI比較 | ロールバック閾値が発火し、変更オーナーを特定できること |
各テストについて、オーナー、テスト日、トレースID、期待されるアラート、観測されたアラート、修復チケットを記録してください。これにより、可観測性は一度きりの計測プロジェクトではなく、繰り返し可能なリリース制御になります。
7日間の実装計画
集中して取り組むチームであれば、AI可観測性実装チェックリストは、各日にレビュー可能な証跡を残す7日間のシーケンスとして実装できます。
このシーケンスは意図的に範囲を絞っています。チームが対象範囲を拡大する前に、信頼できる縦断的なスライスを提供します。
- 1日目 — 成果契約: 価値の高いワークフローを1つ選び、対象となる開始条件、受け入れ可能な成果、失敗クラス、SLIの式を定義する。
- 2日目 — トレースの骨格: ルートワークフローのスパンを作成し、アプリケーション、キュー、ゲートウェイ、検索レイヤー、ツール全体にコンテキストを伝播する。
- 3日目 — モデルの試行: 要求された経路と解決された経路、試行回数、レイテンシ、終了理由、プロバイダーの使用状況、再試行、フォールバックを記録する。
- 4日目 — 品質とコスト: バリデーターの結果、評価器のバージョン、ユーザー成果、正規化されたワークフローコストを結合する。
- 5日目 — プライバシー制御: フィールドを分類し、許可リストによるエクスポートを実装し、マスキングをテストし、保持期間を設定し、アクセス境界を検証する。
- 6日目 — SLOとダッシュボード: 最小限のダッシュボードを構築し、リリース注釈を追加し、バーンレートアラートを定義し、担当者を割り当てる。
- 7日目 — 障害訓練: 受け入れマトリクスを実行し、ギャップを修正し、カナリアを開始し、ロールバック条件を文書化する。
7日目の終わりに目指すのは、普遍的な計装ではない。目標は、振る舞い、品質、信頼性、安全性、コストを最初から最後まで説明できる、1つの本番ワークフローである。
リリース用の最小ダッシュボード
ダッシュボードはAI可観測性実装チェックリストの運用ビューである。まず顧客成果を示し、次にインフラの詳細を示すべきである。
最初の運用ビューは、インシデント中に使える程度に小さく保つ:
- 成果行: 対象となる開始、受け入れられた完了、品質合格率、そして放棄またはエスカレーション。
- 信頼性行: 正規化されたエラー、フォールバック率、再試行増幅、エラーバジェット消費。
- レイテンシ行: エンドツーエンドのp50/p95/p99、キュー時間、最初のトークンまでの時間、検索レイテンシ、ツールレイテンシ。
- 経済性行: 入力/出力/キャッシュ済みトークン、総ワークフローコスト、受け入れられた成果1件あたりのコスト。
- 変更行: アプリケーション、プロンプト、ルートポリシー、モデル、検索インデックス、ツールスキーマ、評価器のリリース。
- 調査リンク: 各失敗クラス、リリース、ルート、影響を受けたワークフローの代表的なトレース。
ダッシュボードは、症状からトレースへたどれる経路を支援すべきである。アラートが品質低下を示しているのに、チームが数クリックで影響を受けたワークフローのトレースに到達できないなら、調査ループは不完全である。
AI可観測性プラットフォーム評価スコアカード
商用評価では、プラットフォームに最長の機能一覧があるかではなく、あなたの運用モデルを支えられるかをテストすべきである。候補は、同じ計測済みのパイロットワークロードに対して採点する。
| 基準 | 重み | パイロットで確認する内容 |
|---|---|---|
| ワークフロー相関 | 20% | 1つのトレースで、モデル試行、検索、ツール、検証、ユーザー結果が結合されている |
| OpenTelemetry相互運用性 | 15% | 標準のエクスポート/インポートが機能し、ローカル拡張もクエリ可能で、データが移植可能である |
| 品質と評価の結合 | 15% | オンラインフィードバックとバージョン管理されたオフライン評価が本番トレースに接続される |
| プライバシーとガバナンス | 15% | フィールドの許可リスト、マスキング、リージョン制御、アクセスロール、監査ログ、削除テスト |
| 信頼性運用 | 15% | SLO、バーンレートアラート、サンプリング制御、リリース注釈、インシデント訓練のサポート |
| コスト配賦 | 10% | プロバイダー利用、再試行、フォールバック、キャッシュ済みトークン、承認済み結果あたりのコストが整合する |
| エージェント/RAG/ツールのカバレッジ | 5% | 検索および副作用を伴うツール操作に、第一級のスパンとフィルターがある |
| 運用コスト | 5% | 取り込み、保存、クエリ、保持、エンジニアリングのオーバーヘッドが想定ボリュームに収まる |
各基準を1〜5で採点し、重みを掛け、パイロットからの文書化された証拠を必須としてください。ダッシュボードが洗練されて見えても、テレメトリー契約を保持できない、またはデータをエクスポートできないプラットフォームは、運用上のロックインを生みます。
コピー可能なテレメトリー契約
AI可観測性実装チェックリストを最速で運用可能にする方法は、これをバージョン管理されたテレメトリー契約に変えることです。この契約では、すべてのワークフローとモデル試行が出力すべき内容、任意のフィールド、許可される値、そして高ボリュームのインデックスから除外すべきフィールドを定義します。
以下の例では内部名前空間を使用しています。アプリケーションコードを規約変更から切り離すために、これを1つのアダプター内で固定されたOpenTelemetry GenAI規約にマッピングしてください。
telemetry_contract:
version: "2026-08-04"
workflow_span:
required:
- ai.workflow.name
- ai.workflow.version
- ai.request.id
- deployment.environment
- service.version
- ai.outcome.status
- ai.outcome.accepted
- ai.latency.total_ms
optional:
- ai.tenant.tier
- ai.experiment.id
- ai.user.feedback
prohibited:
- end_user.email
- end_user.name
- raw.authorization_header
model_attempt_span:
required:
- ai.attempt.number
- ai.route.requested_model
- ai.route.resolved_provider
- ai.route.resolved_model
- ai.result.status
- ai.usage.input_tokens
- ai.usage.output_tokens
- ai.latency.first_token_ms
- ai.latency.total_ms
conditional:
- ai.fallback.reason
- ai.error.class
- ai.error.provider_code
- ai.usage.cached_input_tokens
content_capture:
default: "off"
allowed_when:
- approved_evaluation_dataset
- explicit_debug_session
controls:
- redact_before_export
- access_logged
- retention_approved
この契約は、API スキーマと同じようにコードレビューで確認してください。新しいモデルプロバイダー、エージェントツール、フォールバックポリシー、または評価器は、そのテレメトリフィールドが契約にマップされ、同じ受け入れテストに合格するまでリリースしてはいけません。
1つの AI ワークフローのためのインスツルメンテーションパターン
各チームがスパン名と属性を個別に発明しないようにしてください。ルートのワークフロースパンを作成し、子の試行を記録し、正規化された結果を取得し、エクスポート前にマスキングを適用する小さなラッパーを提供します。
この Python の例は、意図的にプロバイダー非依存です。内部の属性名は、ラッパーまたはコレクター層で、固定している OpenTelemetry のセマンティック規約バージョンに変換する必要があります。
from opentelemetry import trace
tracer = trace.get_tracer("checkout-assistant")
def run_ai_workflow(request, router, evaluator):
with tracer.start_as_current_span("ai.workflow.checkout_help") as workflow_span:
workflow_span.set_attribute("ai.workflow.name", "checkout_help")
workflow_span.set_attribute("ai.workflow.version", "2026-08-04")
workflow_span.set_attribute("ai.request.id", request.request_id)
result = None
for attempt_number in range(1, 3):
with tracer.start_as_current_span("ai.model.attempt") as attempt_span:
route = router.resolve(request, attempt_number)
attempt_span.set_attribute("ai.attempt.number", attempt_number)
attempt_span.set_attribute("ai.route.requested_model", request.model)
attempt_span.set_attribute("ai.route.resolved_provider", route.provider)
attempt_span.set_attribute("ai.route.resolved_model", route.model)
result = route.generate(request)
attempt_span.set_attribute("ai.result.status", result.status)
attempt_span.set_attribute("ai.usage.input_tokens", result.input_tokens)
attempt_span.set_attribute("ai.usage.output_tokens", result.output_tokens)
if result.status == "ok":
break
attempt_span.set_attribute("ai.error.class", result.error_class)
evaluation = evaluator.score(request, result)
workflow_span.set_attribute("ai.outcome.status", result.status)
workflow_span.set_attribute("ai.outcome.accepted", evaluation.accepted)
workflow_span.set_attribute("ai.evaluator.version", evaluation.version)
workflow_span.set_attribute("ai.quality.score", evaluation.score)
return result
本番コードでは、所要時間、最初のトークンまでの時間、フォールバック理由、キャンセル、ストリーミングエラー、例外も記録する必要があります。重要な設計上の選択は階層です。1つの顧客ワークフローに1つ以上の課金対象の試行が含まれ、ワークフローは最終的に受け入れられた結果を記録します。
アラートポリシーと初動対応ランブック
AI可観測性実装チェックリストは、ダッシュボードに対応ルールがなければ不完全です。各ローンチ指標には、トリガー、担当者、最初の診断クエリが必要です。
| アラート | 例示的なトリガー | 最初の確認事項 | 即時対応 |
|---|---|---|---|
| 受容済み成果の消費 | 高速および低速のエラーバジェット消費 | どのワークフロー、リリース、ルート、またはテナントが変更されたか？ | ロールアウトを停止するか、該当するリリースを元に戻す |
| レイテンシー回帰 | p95のワークフロー遅延がSLOを超過 | キュー、検索、モデル、またはツールのレイテンシーが変化したか？ | 遅いステージを迂回するか、負荷を減らす |
| フォールバック急増 | フォールバック率が通常範囲を超える | 主要プロバイダーが失敗、スロットリング、またはタイムアウトしているか？ | 正規化済みおよび生のプロバイダーエラーを確認する |
| 成果当たりコストの急増 | 受容率が横ばいまたは低下しているのにコストが上昇する | リトライ、出力長、または高コストなルートが増えているか？ | リトライを上限設定し、以前のルートポリシーを復元する |
| 品質スコア低下 | オンラインまたはサンプリングした評価器の合格率が低下する | プロンプト、検索、モデル、または評価器のバージョンが変わったか？ | リリース対象コホートを直近の健全なコホートと比較する |
| ツールの不確実性 | 副作用結果を整合させられない | タイムアウトまたはキャンセルの前にツールは完了したか？ | 自動リトライを停止し、照合に進む |
| テレメトリ損失 | 期待されるスパンまたは使用量の完全性が低下する | 計装が壊れているのか、エクスポートのバックプレッシャーが増加しているのか？ | 欠落したテレメトリを運用インシデントとして扱う |
オンコールビューは、アラートからワークフロー、リリース、要求モデル、解決済みルート、エラークラスで絞り込まれたトレースへ直接リンクできるべきです。インシデント中にレスポンダーがこれらのフィルターを手動で再構築しなければならないなら、そのシステムはリリース準備ができていません。
責任分担と本番引き継ぎ
ロールアウト前に、このチェックリストを担当ロールに割り当ててください。明確な意思決定者のいない共有責任は、通常、誰もが閲覧できるが誰も保守しないダッシュボードを生みます。
| 責任 | 説明責任を負うロール | 必要な引き継ぎ証跡 |
|---|---|---|
| ワークフロー成果の定義 | プロダクトまたはAI機能のオーナー | 受容済み成果のルールと却下例 |
| スパンおよびメトリクスのスキーマ | プラットフォームまたは可観測性のオーナー | バージョン管理されたテレメトリ契約とスキーマテスト |
| ルートおよびフォールバックのフィールド | ゲートウェイまたは信頼性のオーナー | 要求/解決済みルートと試行の検証 |
| 品質評価器 | AIエンジニアリングのオーナー | 評価器のバージョン、データセット、しきい値、既知の制限 |
| プライバシーと保持 | セキュリティまたはプライバシーのオーナー | データ分類、マスキングテスト、保持承認 |
| SLOとアラート | サービスオーナー | SLO文書、ページングルール、ダッシュボード、ランブック |
| コスト配賦 | エンジニアリング財務のオーナー | 使用量の完全性と成果当たりコストの照合 |
| リリース準備 | エンジニアリングリード | 完了済みの受入マトリクスとロールバックトリガー |
起動後30日レビューを予定してください。未使用のフィールドを削除し、繰り返し有用なデバッグクエリをダッシュボード表示に昇格させ、カーディナリティとストレージコストを見直し、ワークフローの動作が変わったら契約を更新します。
そのまま使える AI 可観測性実装チェックリスト
このリストをローンチゲートとして使用してください:
- [ ] 各ワークフローと許容される顧客成果を定義する。
- [ ] トランスポート、キャパシティ、契約、品質、安全性、ビジネス上の失敗を定義する。
- [ ] 可用性、品質、レイテンシ、成果あたりコストの SLI を選定する。
- [ ] 必須、任意、禁止フィールドを含むバージョン管理されたテレメトリ契約を承認する。
- [ ] ユーザーが認識できる各ワークフローごとに 1 つのルートトレースを作成する。
- [ ] キュー、ツール、検索、ゲートウェイをまたいでコンテキストを伝播する。
- [ ] 要求されたプロバイダー/モデルルートと解決されたプロバイダー/モデルルートを記録する。
- [ ] すべてのリトライおよびフォールバック試行ごとに個別のスパンを作成する。
- [ ] キュー時間、最初のトークンまでの時間、総レイテンシを収集する。
- [ ] プロバイダーが報告するトークン使用量と正規化コストを収集する。
- [ ] プロンプト、ツール、検索インデックス、ポリシー、ルート、評価器をバージョン管理する。
- [ ] 検索参照、鮮度、認可、グラウンディング結果を記録する。
- [ ] ツールの認可、冪等性、結果、副作用の状態を記録する。
- [ ] ユーザーフィードバックとオフライン評価結果をトレースに結び付ける。
- [ ] テレメトリをメタデータ、派生シグナル、または生コンテンツとして分類する。
- [ ] エクスポート前にシークレットと機密フィールドをマスキングする。
- [ ] データクラスごとに個別の保持ポリシーとアクセスポリシーを適用する。
- [ ] 高カーディナリティ値をメトリクスラベルに含めない。
- [ ] ユーザー影響のある SLO とエラーバジェット消費に対してアラートを設定する。
- [ ] リリースを注釈し、カナリアとコントロールを比較する。
- [ ] 障害、プライバシー、サンプリング、エクスポーター停止の訓練を実施する。
- [ ] リリースゲート用に受け入れテストの証跡とトレース ID を保存する。
- [ ] 重み付けした 1 つのパイロット採点表で可観測性プラットフォームを比較する。
- [ ] 成果、スキーマ、プライバシー、SLO、品質、コストについて責任を持つオーナーを割り当てる。
- [ ] ページングが必要なアラートごとに、一次対応ランブックとトレースクエリを紐付ける。
よくある AI 可観測性のミス
データポリシーなしでプロンプトをログに記録する
生のプロンプトはデバッグ中に便利に見えますが、顧客データ、シークレット、著作物、または規制対象情報を含む可能性があります。まずはメタデータから始め、正当な理由がある場合にのみ制御されたコンテンツ収集を有効にしてください。
リクエスト単位のコストを結果単位のコストとして測定する
検証に失敗する安価なリクエストは、安価ではありません。リトライ、フォールバック、人的修正はワークフローコストに含める必要があります。同じ原則はプロンプトキャッシュの ROIにも当てはまります。孤立したトークンレートではなく、受け入れられたタスクを最適化してください。
すべてのモデル呼び出しを独立して扱う
エージェントと RAG システムはワークフローです。モデル、検索、ツールのスパンが相関していなければ、チームは因果関係を再構築できません。
1 つのプロバイダーダッシュボードだけに依存する
プロバイダーダッシュボードは上流の使用量やエラー把握には有用ですが、アプリケーション全体の成果、検索システム、ツール実行、ユーザーフィードバック、プロバイダー横断のフォールバック経路までは把握できません。
意思決定を定義する前にすべてを計測する
テレメトリには運用コストがあります。各フィールドは、デバッグ、アラート、評価、ガバナンス、または最適化の意思決定を支援すべきです。誰も使っていないフィールドは削除しましょう。
AIゲートウェイの位置づけ
LLMゲートウェイは、複数のアプリケーションとプロバイダーが1つの制御点を通過するため、相関付けとポリシー境界として有用です。観測データを可観測性スタックへエクスポートする前に、ルート、試行、使用量、レイテンシー、エラーメタデータを正規化できます。
ゲートウェイだけで解決するわけではありません。アプリケーションコードは、依然としてワークフローの結果、検索コンテキスト、ツールの意味、ユーザーフィードバック、ビジネスコンバージョンを担います。最も強力な設計は、ゲートウェイのテレメトリとこれらのアプリケーションレベルのシグナルを結び付けることです。
Flatkeyは、複数のAIモデルに対してOpenAI互換の単一アクセスレイヤーを提供します。プロバイダー連携を統合中であれば、Flatkeyを確認し、このチェックリストを使ってアプリケーション層とルーティング層を取り巻くテレメトリ契約を定義してください。
よくある質問
AI可観測性では何を最初に実装すべきですか？
AI可観測性実装チェックリストは、まず各顧客ワークフローごとに1つのルートトレース、モデル試行ごとの子スパン、要求されたモデルと解決されたモデルのフィールド、レイテンシー、使用量、正規化されたエラー、そして受け入れられた結果のシグナルから始めてください。プライバシーポリシーで許可される場合は、後から生のプロンプトの取得を追加します。
LLMの可観測性にOpenTelemetryだけで十分ですか？
OpenTelemetryは、トレース、メトリクス、ログのためのトランスポート非依存の基盤に加え、進化中の生成AIセマンティック規約を提供します。それでも、ワークフロー定義、評価、プライバシー制御、SLO、ダッシュボード、インシデントプロセスは必要です。
プロンプトとレスポンスはトレースに保存すべきですか？
デフォルトでは保存しません。まずはメタデータ、バージョン、ハッシュ、派生した品質シグナルを使用してください。生のコンテンツは、明確な目的、アクセス方針、保持期間、削除プロセスを備えた管理されたシステムにのみ保存します。
どのAI可観測性メトリクスが最も重要ですか？
まずは、受け入れ完了率、品質合格率、p95のエンドツーエンドレイテンシー、ストリーミング時の初回トークンまでの時間、フォールバック率、受け入れられた結果あたりのコストから始めてください。これらが信頼できるようになってから、ワークフロー固有のメトリクスを追加します。
複数のAIプロバイダーはどう監視すればよいですか？
プロバイダー間で1つの安定したテレメトリスキーマを使用します。各試行について、要求されたルートと解決されたプロバイダー/モデルの両方を記録し、プロバイダーの生コードを破棄せずにエラーを正規化し、すべての試行を同じワークフロートレースの下で結合します。
