AI API observability は、エンジニアリングチームが推測なしでモデルルーティングのインシデントを再構成できるようにするものです。ユーザーがタイムアウトを報告し、フォールバックモデルが異なる応答を返し、プロバイダーが 429 を返し、または上流の切り替え後に支出が急増することがあります。インシデントレビューには、生のプロンプトとステータスコードだけでは不十分です。リクエスト、ルート、リトライチェーン、選択されたモデル、レイテンシプロファイル、使用量、コスト、そして保存内容に関するプライバシー制御を示すログレコードが必要です。
このガイドは、ルーティングインシデントにおける AI API observability ログのフィールドレベルのチェックリストです。これは、1つのアプリケーションリクエストが複数の上流パスを通過しうる AI ゲートウェイ、マルチプロバイダールーター、または互換レイヤーを使用するチーム向けに書かれています。目的は、すべてのプロンプトを永遠に保存することではありません。目的は、機微な入力、出力、ツール引数、顧客識別子を制御しながら、何が起きたかを証明するのに十分なメタデータを保持することです。
Flatkey がこの問題に適しているのは、その公開製品説明が、1つの API キー、https://router.flatkey.ai/v1 の OpenAI 互換ベース URL、統合請求、そしてキー、使用量、ルーティングのための1つのダッシュボードを中心に据えているからです。Flatkey はまた、上流アカウント間での自動切り替えと負荷分散にも言及しています。これらは、ログが後からルーティングの問いに答えられる場合にのみ有用な信頼性機能です。
AI API オブザーバビリティはインシデントの質問から始まる
フィールドを選ぶ前に、インシデント責任者が答えるべき質問を定義しましょう。モデルルーティングでは、AI API オブザーバビリティは、1つのリクエスト記録または1つの相関トレースから次の質問に答えられるようにすべきです。
- どのアプリケーション、環境、チーム、キー、ワークフロー、顧客に安全なオーナーがリクエストを送信したのか?
- リクエスト時に、どのエンドポイントファミリー、要求されたモデル、ルートポリシー、フォールバックルールが適用されたのか?
- どのプロバイダー、モデル、上流アカウント、またはルートが実際にレスポンスを提供したのか?
- リクエストは再試行、切り替え、スロットリング、キューイング、ブロック、または中止されたのか?
- どのステータスコード、プロバイダーエラークラス、レート制限ヘッダー、タイムアウト、またはストリームイベントが結果を変えたのか?
- 入力、出力、キャッシュ、推論の各トークンは何個カウントされ、ルートのコストはいくらだったのか?
- プライバシー制御は、生のペイロード、マスキング済みペイロード、メタデータのみ、またはログエントリなしのどれを保存したのか?
ログがこれらの質問に答えられないなら、チームはその不足分をSlackの記憶、スクリーンショット、プロバイダーのサポートチケットで埋めることになります。それでは修復が遅れ、将来のルート変更への信頼も得にくくなります。
モデルルーティング障害インシデントログのチェックリスト
下の表は、この記事における中核となるAI API 可観測性アセットです。LLM API ログ、ゲートウェイログ、またはデータウェアハウスイベントの実装チェックリストとして使用してください。
| フィールドグループ | 収集するフィールド | ルーティング障害で重要な理由 | プライバシーに関する注意 |
|---|---|---|---|
| 相関 ID | アプリケーションのリクエスト ID、X-Client-Request-Id、プロバイダーの x-request-id、W3C traceparent、ゲートウェイログ ID、イベント ID。 |
ユーザー向けエラー、ゲートウェイの判断、プロバイダーへのリクエスト、トレーススパン、サポートチケットを結び付けます。 | 不透明な ID を使用してください。メール、IP、テナント名、プロンプト本文をトレースフィールドに埋め込まないでください。 |
| テナントと所有者 | プロジェクト、環境、API キー ID またはハッシュ、チーム、ワークフロー、顧客に安全なアカウント ID、コストセンター。 | 誰が影響を受けたか、またクォータ、コスト、修復を誰が担当するかを示します。 | 生の顧客名やユーザーのメールアドレスよりも、安定した内部 ID を優先してください。 |
| 要求されたルート | エンドポイントファミリー、要求されたモデル、プロバイダーの優先度、ルートポリシー、フォールバックポリシー、モデルエイリアスのバージョン、カタログ/価格設定のバージョン。 | クライアントが何を要求し、その時点でルーターに何が許可されていたかを再構築します。 | 別途承認されたデバッグモードが有効でない限り、ルートオブジェクトからプロンプトを除外してください。 |
| 選択されたルート | 最終プロバイダー、最終モデル、上流のアカウントまたはチャネル、必要に応じたリージョン、ルート決定理由、ポリシールール ID。 | 主要モデルがレスポンスを提供したのか、それともフォールバック経路で挙動やコストが変わったのかを証明します。 | アカウント識別子は、プロバイダーのシークレットや完全な認証情報ではなく、内部参照にしてください。 |
| 再試行とフォールバックのチェーン | 試行インデックス、再試行回数、直前のプロバイダー/モデル、失敗クラス、ステータスコード、フォールバック先、最終結果。 | 盲目的な再試行を防ぎ、フェイルオーバー階層が設計どおりに動作したかを示します。 | エラークラスと安全な抜粋を保存してください。プロンプト内容を含みうるプロバイダーの完全なエラー本文は保存しないでください。 |
| レイテンシとストリーミング | リクエスト開始時刻、ゲートウェイ所要時間、プロバイダー所要時間、最初のトークン/チャンクまでの時間、ストリーム開始、ストリーム完了、中断理由、クライアント切断。 | プロバイダーのレイテンシ、ゲートウェイのルーティング時間、ストリーミングの停止、クライアント側キャンセルを切り分けます。 | ストリーミングチャンクはコンテンツです。既定ではタイミングメタデータのみを記録し、コンテンツは統制されたデバッグモード下でのみ記録してください。 |
| 使用量とコスト | 入力トークン、出力トークン、キャッシュ済みトークン、推論トークン、必要に応じて画像/動画ユニット、リクエスト数、明細項目、推定または最終コスト。 | フォールバックによりトラフィックが別のプロバイダー、モデル、またはサービス階層に移った際の予算への影響を説明します。 | 通常のダッシュボードではキー、ワークフロー、チーム単位で集約し、ユーザー別ビューは制限してください。 |
| レスポンス形状 | 終了理由、ツール呼び出し ID/名前、出力タイプ、レスポンスステータス、切り捨てまたは不完全な詳細、サービス階層。 | モデルが通常終了したのか、ツールを呼び出したのか、制限に達したのか、不完全なレスポンスを返したのかを示します。 | ツール引数とツール結果には機微情報が含まれる場合があります。既定では ID と名前を保存してください。 |
| エラーとレート制限 | HTTP ステータス、プロバイダーのエラーコード、タイムアウトクラス、retry-after、残数/上限/リセットのリクエストヘッダー、残数/上限/リセットのトークンヘッダー。 | 不正なリクエスト、認証失敗、プロバイダー障害、クォータ枯渇、レート制限の急増を区別します。 | 広範な分析ツールに投入する前に、プロバイダーのエラーを安全なクラスへ正規化してください。 |
| ガバナンスと保持 | DLP アクション、ポリシー ID、コンテンツログモード、マスキングフラグ、ペイロードハッシュ、保持クラス、削除対象可否。 | セキュリティとコンプライアンスが、コンテンツが保存、マスキング、ブロック、または除外された理由を検証できます。 | 定義されたサポートまたは監査ワークフローで生コンテンツが不要な場合は、既定でメタデータのみのログにしてください。 |
プロバイダーをデバッグする前にIDを取得する
AI APIの可観測性の最初の仕事は相関です。OpenAIのAPIリファレンスでは、本番環境でリクエストIDをログに記録することを推奨しており、プロバイダーが生成する x-request-id の値と、呼び出し側が指定する X-Client-Request-Id の値の両方について記載しています。タイムアウトやネットワーク障害によってクライアントがプロバイダーのレスポンスヘッダーを受け取れない場合、後者が重要になります。
ゲートウェイでは、さらにもう1層追加します。内部リトライやフォールバックを経ても残るゲートウェイのリクエストIDです。1つのユーザーリクエストがプロバイダーAを試し、次にプロバイダーBを試し、最後にバックアップモデルに送られる場合、ゲートウェイIDはすべての試行をひとまとまりで結び付ける必要があります。プロバイダーのリクエストIDは試行ごとに固有のままにしておくべきです。トレースIDは、このAI呼び出しをアプリケーション全体の残りのリクエストに結び付ける必要があります。
W3C Trace Contextは、サービス間で分散トレースコンテキストを伝播するための traceparent と tracestate を定義しています。これらのヘッダーは、顧客の識別ではなくトレース相関のために使用してください。W3Cのプライバシー節は明確です。トレースフィールドには、個人を特定できる情報や、その他の機微情報を含めてはなりません。
要求されたルートと選択されたルートを別々に記録する
AI gateway monitoringでよくあるミスは、最終的なプロバイダーとモデルだけをログに残すことです。それでは最も重要なルーティングの証跡が失われます。つまり、ゲートウェイが判断を下す前に、クライアントが何を要求し、ポリシーが何を許可したのかです。
この2つのオブジェクトは分けて保持してください。
- Requested route: endpoint family, requested model or alias, route policy, provider preference, fallback policy, catalog version, pricing version, and request mode such as streaming or batch.
- Selected route: final provider, final model, upstream account or channel, region when relevant, route decision reason, and policy rule ID.
この分離は、フォールバック応答が有効ではあるものの意外な場合に重要です。要求されたルートがストリーミング有効の chat/completions で、タイムアウト後に選択されたルートが別のモデルに切り替わった場合、インシデントレビューでは意図した経路と実際の経路の両方を確認できます。また、利用料金が別のモデルや明細項目に計上された理由を、財務部門が理解するのにも役立ちます。
Flatkey の購入者も、同じ評価パターンを適用すべきです。まず AI API gateway requirements のチェックリストから始め、その後 load balancing and failover playbook を使って、ログを確認する前にどのルート変更が許可されるかを定義してください。
リトライとフォールバックのチェーンを記録する
リトライは、不完全なログが高くつく場面です。保存される項目が最終ステータスと最終モデルだけでは、チームはリクエストが1回目で成功したのか、1回のリトライ後なのか、あるいは複数のプロバイダーをまたいで5回試行したのかを判断できません。インシデント対応レベルのAI APIオブザーバビリティでは、リトライとフォールバックをひとつのチェーンとして扱います。
各試行には、次を含めるべきです。
- 試行インデックスと親のゲートウェイリクエストID。
- その試行のプロバイダー、モデル、上流アカウント、およびエンドポイントファミリー。
- 開始時刻、継続時間、タイムアウト種別、ストリーミング状態。
- ステータスコード、プロバイダーのエラー種別、プロバイダーのリクエストID、およびレート制限メタデータ。
- 試行がチェーンを終了しない場合のフォールバック先と判断理由。
このチェーンにより、ゲートウェイが実際の失敗モードを隠すのを防げます。形式不正のリクエストはクローズドに失敗させるべきで、プロバイダーを渡り歩くべきではありません。プロバイダーの500エラーなら1回のリトライで十分な場合があります。クォータ制限なら、承認済みの上流アカウントへ切り替えることがあります。顧客向けのモデル不一致では、サイレントなフォールバックではなく、制御されたエラーが必要になることがあります。
ストリームのレイテンシを測定する、完了した呼び出しだけでなく
ストリーミング応答には、総所要時間以上の情報が必要です。Vercel の AI Gateway のオブザーバビリティ文書では、ゲートウェイのメトリクスとして、最初のトークンまでの時間、リクエスト時間、トークン数、支出が挙げられています。OpenTelemetry の GenAI セマンティック規約には、gen_ai.response.time_to_first_chunk と gen_ai.request.stream が含まれます。これらのフィールドが有用なのは、多くのルーティング障害がストリーミング障害だからです。つまり、プロバイダーはリクエストを受け付けたが、最初のチャンクが遅れた、ストリームが停止した、またはクライアントが切断した、といったケースです。
少なくとも、リクエスト開始時刻、ゲートウェイの継続時間、プロバイダーの継続時間、最初のトークンまたはチャンクまでの時間、ストリーム開始フラグ、ストリーム完了フラグ、中断理由、クライアント切断状態を記録してください。非ストリーミング応答では、同じフィールドを null または false のままにできます。これにより、Chat Completions、Responses、プロバイダー固有のエンドポイントファミリーをまたいで単一のスキーマを維持できます。
デフォルトではストリームチャンクを保存しないでください。ストリームチャンクは応答コンテンツであり、応答コンテンツにはユーザーデータ、取得したコンテキスト、ツール結果、または規制対象情報が含まれる可能性があります。通常のAI API のオブザーバビリティでは、タイミングメタデータだけで停止の原因を特定できることがほとんどです。
使用量とコストをルート決定に結びつける
使用量とコストは、財務だけの項目ではなくインシデントの項目です。OpenAI の Responses API の例には、input、output、cached、reasoning、および total token usage が含まれます。OpenAI の organization usage エンドポイントは、project、user、API key、model、batch、service tier によるグループ化をサポートし、costs エンドポイントは project、line item、API key によるグループ化をサポートします。Vercel の AI Gateway ドキュメントでも、project と API key によるリクエスト要約、token counts、P75 duration、P75 TTFT、cost が同様に説明されています。
AI API observability では、可能であれば試行レベルで、そして常に最終リクエストレベルで使用量とコストを取得してください。フォールバックは運用上は正しくても、財務上は意外な結果を招くことがあります。model、route、usage、cost が同じイベントにそろっていなければ、エンジニアリングが説明する前に財務が支出の急増を目にするかもしれません。
Flatkey の公開価格とホームページの文言は、明確な価格設定、統合請求、使用量分析、そして keys、usage、routing のダッシュボードを示しています。このタスクのために保存された 2026年6月18日 の価格スナップショットでは、638 の model 行、23 の vendor、そして OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Gemini generateContent、image generation、OpenAI video を含む endpoint families が返されました。これらの件数は時点情報として扱い、pricing page と、ワークフロー内の特定モデルに関するダッシュボード記録を実際に確認してください。
メタデータのみのログをデフォルトにする
生のプロンプトとレスポンスは強力なデバッグツールですが、リスクの高いログでもあります。Cloudflare の AI Gateway のログドキュメントは有用な参考パターンです。そこでは、プロンプト、レスポンス、プロバイダー、タイムスタンプ、ステータス、トークン使用量、コスト、所要時間、ユーザーエージェントを含むリクエストログを説明しており、さらに、トークン数、モデル、プロバイダー、ステータスコード、コスト、所要時間などのメタデータを保持しながら、生のリクエスト本文とレスポンス本文の保存を抑制できるヘッダーについても文書化しています。
それが LLM API ログ にとって適切なデフォルト姿勢です。つまり、デフォルトではメタデータのみを収集し、生の内容を保存する前に明示的なデバッグモードまたはサポート用ワークフローを必須にします。OpenTelemetry GenAI のセマンティック規約では、入力メッセージ、出力メッセージ、システム指示、ツール呼び出しの引数、ツール呼び出しの結果は、機密情報を含み得るフィールドとして扱われています。ログポリシーはそれを反映すべきです。
実用的なポリシーには 4 つのモードがあります。
- ログなし: 一時的な処理を超えて保持してはならないリクエストに使用します。
- メタデータのみ: ルート、ID、レイテンシ、ステータス、使用量、コスト、マスキングフラグ。
- マスク済みペイロード: PII と秘密情報を除去した後の、選択されたリクエスト/レスポンスのフィールド。
- 生のペイロード: 特定のインシデントまたは顧客承認済みのサポートケース向けの、短期間でアクセス制御されたデバッグ用キャプチャ。
ルーティング ログ イベントのサンプル
このテンプレートは意図的にメタデータ優先です。名前はご利用のログシステムに合わせて調整してください。ただし、要求されたルート、選択されたルート、試行、使用量、コスト、プライバシー制御の分離は維持してください。
{
"gateway_request_id": "gw_01jz_route_abc",
"app_request_id": "req_9a7c",
"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
"client_request_id": "7c2c1b3a-4b55-4e36-bd47-8d1c2e2f2e11",
"owner": {
"project": "checkout-ai",
"environment": "production",
"api_key_id": "key_hash_6f12",
"team": "platform",
"workflow": "customer-chat"
},
"requested_route": {
"endpoint_family": "chat_completions",
"model": "primary-chat-model",
"stream": true,
"route_policy_id": "chat-prod-v8",
"fallback_policy_id": "chat-prod-safe-fallback-v3",
"catalog_version": "2026-06-18"
},
"selected_route": {
"provider": "provider_b",
"model": "backup-chat-model",
"upstream_account": "acct_pool_2",
"decision_reason": "primary_timeout",
"policy_rule_id": "fallback_on_timeout_once"
},
"attempts": [
{
"index": 1,
"provider": "provider_a",
"model": "primary-chat-model",
"provider_request_id": "req_provider_a_123",
"status_code": 504,
"error_class": "timeout",
"duration_ms": 12000,
"fallback_target": "provider_b"
},
{
"index": 2,
"provider": "provider_b",
"model": "backup-chat-model",
"provider_request_id": "req_provider_b_456",
"status_code": 200,
"duration_ms": 2400,
"time_to_first_chunk_ms": 620,
"finish_reason": "stop"
}
],
"usage": {
"input_tokens": 1284,
"output_tokens": 312,
"cached_input_tokens": 0,
"reasoning_output_tokens": 0
},
"cost": {
"currency": "usd",
"estimated_amount": 0.0048,
"line_item": "backup-chat-model"
},
"privacy": {
"content_logging_mode": "metadata_only",
"payload_redacted": true,
"retention_class": "30_day_incident_metadata"
}
}フィールド名は例であり、Flatkey API の契約ではありません。ゲートウェイ、データウェアハウス、インシデントツールが、生のコンテンツを必要とせずにルートに関する質問へ答えられるかどうかをテストするために使用してください。
A 10分のトリアージワークフロー
モデルルーティングのインシデントが始まったら、AI APIの可観測性 ワークフローは、オンコールエンジニアがプレッシャーの中でも実行できるほど短くあるべきです:
- 関連するリクエストを見つける: アプリのリクエストID、ゲートウェイのリクエストID、ユーザー向けエラーID、プロバイダーのリクエストID、またはトレースIDで検索します。
- 要求されたルートと選択されたルートを比較する: 要求されたモデル、ルートポリシー、フォールバックルール、最終的なプロバイダー、および最終モデルを確認します。
- 試行チェーンを読む: 最初の失敗、再試行回数、フォールバック先、最終結果を特定します。
- レート制限とクォータのコンテキストを確認する: プロバイダーが429を返した場合やトークン圧迫がある場合は、残量、制限、リセットのヘッダーを確認します。
- レイテンシとストリーミングを分けて見る: ゲートウェイの所要時間、プロバイダーの所要時間、最初のチャンクまでの時間、ストリーム終了、クライアント切断を比較します。
- 使用量とコストを突き合わせる: トークン数、サービスティア、コストの明細、およびチーム/キーの所有権を確認します。
- プライバシーモードを確認する: ログがメタデータのみ、マスク済み、未加工、または意図的に省略されているかを確認します。
- ルートアクションを決める: ポリシーをロールバックする、ルートを無効化する、トラフィック重みを下げる、クォータを増やす、バックグラウンド作業をキューに入れる、または閉じたまま失敗させます。
インシデントの後は、同じ手順をダッシュボードビューに変えます。最速のレビューは、エンジニアリング、サポート、財務が同じイベント形状を確認できるときに実現します。
AI API 可観測性における Flatkey の位置づけ
Flatkey は、1つの API キー、1つの互換ルーターエンドポイント、明確な価格設定、統合請求、そしてキー・使用量・ルーティングを確認できる1つのダッシュボードを求めるチーム向けに位置づけられています。この記事では、関連する検証の流れは実践的です。ステージングのクライアントを https://router.flatkey.ai/v1 に向け、非本番キーを使ってリクエストを送信し、可能な範囲で制御された失敗を発生させ、ダッシュボードにどの使用量、ルーティング、エラー、コストの記録が表示されるかを確認します。
キーごとの AI 使用量トラッキングを使って、ステージング、本番、顧客、ワークフローのトラフィックを分離します。AI API クォータ管理を使って、フォールバックが共有予算を消費しすぎないようにします。ルーティング変更に財務責任者が必要な場合は、チーム別の AI API コスト配賦を使います。
CTA はシンプルです。1つのキーの背後で AI API 可観測性をテストしたいなら、キーを取得し、Flatkey 経由でステージングルートを実行し、自動切り替えを本番で信頼する前に、ログが上記のインシデントに関する質問に答えられるかを確認してください。
よくある質問
AI API 可観測性とは何ですか？
AI API 可観測性とは、リクエスト ID、トレース、モデル、プロバイダー、ルート決定、リトライ、フォールバック、使用量、コスト、レイテンシ、エラー、プライバシー制御にわたってモデル API トラフィックを検査できる能力です。ルーティング障害では、クライアントが何を要求したかと、ゲートウェイが実際に何を選択したかの両方を説明できる必要があります。
LLM API ログは何を記録すべきですか？
LLM API ログは、相関 ID、所有者メタデータ、要求されたルート、選択されたルート、リトライチェーン、レイテンシ、ストリーミング状態、トークン使用量、コスト、終了理由、エラークラス、レート制限コンテキスト、コンテンツログモードを記録すべきです。生のプロンプトと出力は任意とし、アクセス制御を行い、可能であればマスキングしてください。
要求されたモデルと応答モデルを別々に記録するのはなぜですか？
要求されたモデルはクライアントの意図を示します。応答モデルは、実際にどのモデルがリクエストを処理したかを示します。フォールバック障害では、これらが異なる場合があります。両方を記録することは、品質レビュー、コスト照合、サポート対応に不可欠です。
リクエスト ID はプロバイダーサポートにどのように役立ちますか？
プロバイダーのリクエスト ID は、上流の API 呼び出しを識別します。呼び出し元が提供したリクエスト ID は、タイムアウトによりレスポンスヘッダーがクライアントに届かない場合に役立ちます。ゲートウェイのリクエスト ID とトレース ID とともに、両方の ID をインシデント記録に保持してください。
AI ゲートウェイ監視は生のプロンプトを保存すべきですか？
デフォルトでは保存すべきではありません。AI ゲートウェイ監視では通常、まずメタデータが必要です。ルート、モデル、ステータス、期間、使用量、コスト、プライバシーモードです。生のプロンプトや応答は、保持期間とアクセス制御を伴う、定義されたデバッグ、サポート、監査ワークフローの下でのみ保存してください。
参照したソース
- OpenAI API の概要: リクエストのデバッグとリクエスト ID
- OpenAI Chat Completions API リファレンス and Responses API リファレンス
- OpenAI の組織の使用状況とコストの API リファレンス
- Cloudflare AI Gateway のログ記録ドキュメント
- Vercel AI Gateway のオブザーバビリティ ドキュメント
- W3C Trace Context の勧告
- OpenTelemetry GenAI セマンティック規約の属性
ルーティングを変更する前の最終確認
自動フォールバックを信頼する前に、AI API observability をリリースゲートの一部にしてください。ルートポリシー、リトライ階層、トークンとコストのフィールド、レート制限ヘッダー、ストリーミングのタイムスタンプ、プロバイダーのリクエスト ID、プライバシーモード、保持クラスを確認します。そのうえで、制御されたステージング障害を実行し、元のプロンプトにアクセスしなくてもログが結果を説明できることを検証してください。
Flatkey は、統合対象を 1 つのキーと 1 つの互換性のあるベース URL にまで絞り込みます。ご自身のトラフィックでその信頼性レイヤーを評価するには、キーを取得し、ステージングのワークフローを実行して、実際の障害時にチームが必要とするルーティング、使用量、コスト、エラーの記録を確認してください。
