OpenTelemetry

AI Gateway は、OpenTelemetry 互換バックエンドへのトレースエクスポートに対応しています。既存の可観測性基盤と合わせて、AI リクエストのパフォーマンスを監視・分析できます。

概要

OpenTelemetry（OTEL）連携は、ゲートウェイが処理した AI リクエストのトレーススパンを自動でエクスポートします。スパンには次の詳細が含まれます。

リクエストのモデルとプロバイダー
トークン使用量（入力と出力）
リクエストのプロンプトと生成結果
コスト見積もり
カスタムメタデータ

この連携は分散トレーシングの OpenTelemetry 仕様 ↗ に従い、OTLP（OpenTelemetry Protocol）形式を使います。JSON と protobuf の両方のエンコーディングに対応しています。

設定

ゲートウェイで OpenTelemetry トレーシングを有効にするには、ゲートウェイ設定に 1 つ以上の OTEL エクスポーターを設定します。各エクスポーターは次を受け付けます。

URL（必須）: OTEL コレクターのエンドポイント URL
Headers（任意）: エクスポートリクエストに付ける追加のカスタムヘッダー。コレクターが認証を求める場合は、ここに渡します（例: Authorization: Bearer <token>）。
Authorization（任意）: Secrets Store 内のシークレットへの参照。コレクターの認可ヘッダー値が入ります。設定すると、AI Gateway は実行時にシークレットを解決し、エクスポートリクエストの Authorization ヘッダーとして送ります。多くの場合、Headers で認証を渡す方が簡単です。
Content type（任意）: エクスポート形式 — json（デフォルト）または protobuf。

ダッシュボードでの設定

Cloudflare ダッシュボードで AI Gateway を開きます。
Settings タブに移動します。
コレクターのエンドポイント URL を指定して OTEL エクスポーターを追加します。
コレクターが認証を求める場合は、Headers フィールドにトークン値を入れた Authorization ヘッダーを追加します。

エクスポートされるスパン属性

AI Gateway は、Gen AI のセマンティック規約 ↗ に従い、次の属性付きでスパンをエクスポートします。

標準属性

属性	型	説明
`gen_ai.request.model`	string	リクエストに使った AI モデル
`gen_ai.model.provider`	string	AI プロバイダー（例: `openai`、`anthropic`）
`gen_ai.usage.input_tokens`	int	消費した入力トークン数
`gen_ai.usage.output_tokens`	int	生成した出力トークン数
`gen_ai.prompt_json`	string	モデルに送ったプロンプト / メッセージ（JSON エンコード）
`gen_ai.completion_json`	string	モデルからの生成結果 / レスポンス（JSON エンコード）
`gen_ai.usage.cost`	double	リクエストの推定コスト

カスタムメタデータ

cf-aig-metadata ヘッダーでリクエストに付けたカスタムメタデータも、スパン属性として含まれます。ユーザー ID、チーム名、その他の業務コンテキストとトレースを紐づけられます。

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header 'Authorization: Bearer {api_token}' \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-metadata: {"user_id": "user123", "team": "engineering"}' \
  --data '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

上記のリクエストでは、エクスポートされるトレースに user_id と team が追加のスパン属性として含まれます。

トレースコンテキストの伝播

AI Gateway はトレースコンテキストの伝播に対応しています。AI Gateway のスパンを、アプリケーション側のトレースとつなげられます。カスタムヘッダーでトレースコンテキストを渡せます。

cf-aig-otel-trace-id（任意）: トレース ID として使う 32 文字の 16 進文字列
cf-aig-otel-parent-span-id（任意）: 親スパン ID として使う 16 文字の 16 進文字列

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header 'cf-aig-otel-trace-id: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6' \
  --header 'cf-aig-otel-parent-span-id: a1b2c3d4e5f6g7h8' \
  --header 'Authorization: Bearer {api_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

これらのヘッダーを渡すと、AI Gateway のスパンは既存のトレースとつながります。渡さない場合、AI Gateway は新しいトレース ID を自動生成します。

よく使う OTEL バックエンド

AI Gateway の OTEL 連携は、OpenTelemetry 互換の任意のバックエンドで使えます。例:

正しい OTLP エンドポイント URL と認証要件は、お使いの可観測性プラットフォームのドキュメントを参照してください。