Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

OpenTelemetry

最終更新 Markdown で表示Agent セットアップ

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。

ダッシュボードでの設定

  1. Cloudflare ダッシュボードで AI Gateway を開きます。
  2. Settings タブに移動します。
  3. コレクターのエンドポイント URL を指定して OTEL エクスポーターを追加します。
  4. コレクターが認証を求める場合は、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 と認証要件は、お使いの可観測性プラットフォームのドキュメントを参照してください。

役に立ちましたか?