Blank white background with no objects or features visible.

EMEAの皆様へ。TrueFoundryは、ヨーロッパ、中東、アフリカ全域で事業を拡大しています。詳細はこちら →

LLMのOpenTelemetry:マルチプロバイダーAI Gatewayの計装方法

By Boyu Wang

Updated: November 3, 2026

Published: July 2, 2026

20以上のプロバイダーをプロキシするAI Gatewayの計装は、通常のOTelよりも複雑です。本記事では、gen_ai.*セマンティックコンベンション、Gatewayのスパン階層(ルート、プロバイダー、ガードレール)、トレースツリーにおけるフォールバックの表現、Anthropic/OpenAI/Bedrockにわたるエラーの正規化、トレースごとのコスト属性付与、アプリケーションコードからのコンテキスト伝播、ストリーミングとTTFT、Datadog、Tempo、Jaeger向けのエクスポーター設定について詳しく解説します。

重要なポイント
  • → OpenTelemetryのGenAIセマンティックコンベンションはgen_ai.*ネームスペースの下に定義されています。OTel semconv v1.36.0の時点ではまだ開発中(Development)ステータスであり、仕様ではgen_ai.provider.name(非推奨のgen_ai.systemではなく)と標準のerror.type(gen_ai.error.typeではなく)を使用します。
  • → Gatewayのスパン階層は、ルート → ガードレールスパン (INTERNAL) + プロバイダースパン (CLIENT) となります。インバウンドリクエストごとに1つのルートスパン、アウトバウンドコールごとに1つのプロバイダースパン、実行された事前/事後フックごとに1つのガードレールスパンが作成されます。
  • → フォールバックは、同じルート配下に2つのプロバイダースパンとして表示されます。失敗したものはステータスERROR、成功したものはステータスOKとなります。ルートのステータスはクライアントが受信した結果を反映するため、フォールバックが成功すればOKとなります。
  • → コストの属性付与は、使用量属性とプロバイダーの価格設定に基づきます。各プロバイダースパンにgen_ai.usage.cost_usdとして記録され、ルートで合計された後、バックエンドでチーム別またはトレースタグ別に集計されます。
  • → トレースの伝播にはW3C traceparentヘッダーを使用します。アプリケーションがスパンを開始し、Gatewayがそれを引き継ぎます。LLMプロバイダーはトレースを拡張しませんが(ほとんどのプロバイダーは内部トレースを公開していません)、Gatewayのスパンがタイミングやトークンに関してプロバイダーから返されるすべての情報をキャプチャします。
  • → TrueFoundryのAI Gatewayは、これらすべて(スパン階層、正規化されたエラー語彙、トレースごとのコスト属性付与、traceparent伝播)をデフォルトの動作として実装しています。スパンは非同期(NATS経由)でOTLP互換のバックエンドにエクスポートされるため、可観測性システムの停止が推論処理をブロックすることはありません。

水曜日の午後2時14分、Northwind社にて。 Cargo Copilotが同時に12人のエンジニアに対してエラーを返し始めました。オンコールエンジニアがGatewayのダッシュボードを開きます。90秒以内に彼らは以下の状況を把握しました:過去5分間のAnthropic Sonnet 4リクエストの22%が529 overloaded_errorを返していたこと、Gatewayはそのうちの78%でAzure OpenAI gpt-5にフォールバックしたこと、フォールバックパスで1.8秒のレイテンシが加算されたこと、そしてこの時間枠での再試行とフォールバックにより会社に14ドルの追加コストが発生したこと。プロバイダーAのスパンは赤く、その隣のプロバイダーBのスパンは青く表示されています。ルートスパンは緑色です。オンコールエンジニアはダッシュボードを閉じます。他に対応すべき操作はありません。これこそが、あるべき優れたLLMの可観測性(Observability)の姿です。

本記事では、そのようなシステムを構築する方法を説明します。すでにサービス向けにOpenTelemetryが稼働していることを前提とし、それを前段にあるマルチプロバイダーAI Gatewayへどのように拡張するかについて解説します。

1. LLM向けOTelセマンティックコンベンション:gen_ai.*属性ネームスペース

OpenTelemetryのGenAIセマンティックコンベンションは、gen_ai.*ネームスペースの下でLLM呼び出しを計装するための標準語彙を定義しています。OTel semconv v1.36.0の時点において、このコンベンションはまだ開発中(Development)ステータスです。これは運用上重要であり、属性名が最近変更されたため、現在利用されている多くのSDKでは古い変種が出力される可能性があります。

最近変更された属性名
gen_ai.systemは非推奨となりました。現在の属性はgen_ai.provider.nameで、openai、anthropic、aws.bedrock、azure.ai.inferenceなどの値を持ちます。現在も多くの計装ライブラリがgen_ai.systemを出力しているため、ライブラリの採用が進むまではバックエンド側で両方を受け入れるべきです。同様に、初期ドキュメントにあるgen_ai.error.typeは、実際には標準のOTel error.type(低カーディナリティの識別子)です。迷った場合は、opentelemetry.ioの最新の仕様に従ってください。

以下は、成功したAnthropic Sonnet 4の呼び出しにおける実際のプロバイダースパンの属性セットの例です:

JSON — 成功した呼び出しにおけるプロバイダースパンの属性セット

注目すべき3つの詳細があります。gen_ai.request.modelはクライアントが要求したモデルであり、gen_ai.response.modelはプロバイダーが実際に提供したモデルです(これらは異なる場合があります。例えばclaude-sonnet-4は、特定の日付付きバージョンに解決されるエイリアスです)。トークン数には仕様通りキャッシュされたトークンが含まれます:gen_ai.usage.input_tokensが合計であり、キャッシュされた部分が別途分解されて記録されます。そしてgen_ai.usage.cost_usdは、標準のsemconvの上に重ねてTrueFoundryが出力する独自属性です。仕様ではトークンまでがカバーされていますが、コストの計算はGatewayの責務となります(§5を参照)。

2. Gatewayのスパン階層:ルート、プロバイダー、およびガードレールスパン

Gatewayへのインバウンドリクエストは、それぞれ1つのルートスパンを生成します。そのルートスパンには、Gatewayが実行する各作業単位(入力ガードレール、アウトバウンドのプロバイダー呼び出し、出力ガードレール)に対応する子スパンが紐付きます。フォールバックが発生した場合は、同じルート配下に2つ目のプロバイダースパンが作成されます(§3を参照)。

図1. 水曜日午後2時の障害時におけるCargo Copilotの実際のウォーターフォールトレース。Anthropicは505ミリ秒後に529を返し、GatewayはAzure OpenAIにフォールバック、ユーザーは2398ミリ秒でレスポンスを受信します。ガントチャートのように読み取ります — スパンは時間軸上のバーであり、階層は左列のインデントで示されます。

スパン種別(SpanKind)の定義は重要です。OpenTelemetry GenAI仕様に基づき、外部プロバイダーの呼び出しはCLIENTスパンとなります。ガードレールスパン(PIIの伏字化、スキーマ検証、Gatewayプロセス内で実行される処理全般)はINTERNALです。ルートスパン自体はSERVERとなります(Gatewayはクライアントから見てサーバーであるため)。

スパン名は定められた形式に従います:推論スパンには {operation} {model}(したがって chat claude-sonnet-4 と命名し、claude-sonnet-4-call や LLM call などとはしません)。ルートスパンやガードレールスパンにはフリーフォーマットの名前を使用します。このレイヤーでの一貫性が、チーム間で共通して利用可能なダッシュボードを実現する鍵となります。

3. トレースツリーにおけるフォールバック処理:マルチプロバイダートレース

フォールバックはOTelにおいて独立した概念ではなく、単に2つ目の兄弟スパンに過ぎません。Anthropicが529を返し、GatewayがAzure OpenAIにルーティングすると、トレースには同じSERVERルートの下に2つのCLIENTプロバイダースパンが表示されます。最初のアウトバウンド呼び出しはステータスがERRORとなり、エラー属性が付与されます。2つ目はステータスがOKとなります。ルートのステータスはクライアントが最終的に受け取った結果を反映するため、フォールバックが成功すればOKとなります。

この構成により、フォールバックの検索や分析が可能になります。TempoやJaegerにおいて、「Anthropicの過負荷をフォールバックでカバーし、成功したすべてのリクエストを表示する」という検索は、トレースツリーに対する以下のようなクエリになります:

可観測性バックエンド全体でのフォールバックパターンのクエリ

このクエリは運用上非常に有用です。アップストリームプロバイダーの調子が悪くなった場合、同じクエリを実行するだけで、フォールバックのヒット率、追加されたレイテンシ、合計のコスト影響をチーム別、モデル別、あるいは時間枠別にグループ化して取得でき、より深いLLMの可観測性を提供します。トレース構造そのものがこの役割を果たします。

4. エラーコードの正規化:プロバイダー固有のエラーから標準OTelステータスへ

各LLMプロバイダーは独自のエラーフォーマットを持っています。Gatewayの役割は、これらをダッシュボードやアラートが信頼して利用できる小規模で一貫した語彙に正規化しつつ、フォレンジック(原因究明)のために生のプロバイダー詳細を保持することです。

プロバイダー HTTP 生のエラー 正規化されたOTel属性
Anthropic 429 type: rate_limit_error error.type: RATE_LIMITED
gen_ai.anthropic.error_type: rate_limit_error
Anthropic 529 type: overloaded_error error.type: OVERLOADED
gen_ai.anthropic.error_type: overloaded_error
OpenAI 429 code: rate_limit_exceeded error.type: RATE_LIMITED
gen_ai.openai.error_code: rate_limit_exceeded
OpenAI 429 code: insufficient_quota error.type: QUOTA_EXCEEDED
gen_ai.openai.error_code: insufficient_quota
Azure OpenAI 429 rate_limit_exceeded + Retry-Afterヘッダー error.type: RATE_LIMITED
http.response.header.retry_after:
AWS Bedrock 429 ThrottlingException error.type: RATE_LIMITED
gen_ai.aws.bedrock.exception: ThrottlingException
AWS Bedrock 503 ServiceUnavailableException error.type: PROVIDER_UNAVAILABLE

基本原則:正規化された少数のerror.type値(RATE_LIMITED、QUOTA_EXCEEDED、OVERLOADED、PROVIDER_UNAVAILABLE、TIMEOUT、INVALID_REQUEST、CONTENT_FILTERED)が、プロバイダーを横断したダッシュボードやアラートルールを駆動します。プロバイダー固有の属性(gen_ai.anthropic.error_type、gen_ai.openai.error_code)はフォレンジックのために保持されます。正規化フィールドは低カーディナリティ、生のフィールドは高カーディナリティに保たれます。どちらも重要です。

5. トレースごとのコスト属性付与:計算式、キャッシュ、およびフォールバックコスト

コストはプロバイダーから直接出力されるものではなく、計算によって導出される属性です。Gatewayは、プロバイダーから報告された使用トークン数と、Gateway自身が維持する価格表を使用して、各プロバイダースパンの終了時にコストを計算します。

Python — 各プロバイダースパンにgen_ai.usage.cost_usdとして格納されるコスト計算式

大規模運用において、注意すべき2つのポイントがあります。第一に、仕様ではgen_ai.usage.input_tokensにすでにcache_read.input_tokensとcache_creation.input_tokensの両方が含まれていると規定されています。全input_tokensを通常の入力レートで課金した上で、さらにキャッシュ行の費用を加算すると、キャッシュ読み取り部分を過剰請求し、キャッシュ書き込み部分を二重計上することになります。入力レートを適用する前に両方を差し引いてください。第二に、フォールバックコストは加算されます:Anthropicが失敗してGatewayがAzure OpenAIを呼び出した場合でも、一部処理されたAnthropicのリクエストに対して課金される可能性があります(出力が返されなかった場合でも入力トークンは送信されているため)。両方のプロバイダースパンにcost_usdを付与し、ルートスパンでそれらを合計します。この合計値が、実際のトレースコストとなります。

ここから各種の集計が可能になります:チーム別コスト(呼び出し元の識別情報でスパンをタグ付け)、モデル別コスト、機能別コスト(アプリケーションが設定するservice.*属性でタグ付け)、トレースタグ別コスト(例:「support-ticket」対「code-generation」)。OTel側の実装はシンプルであり、主な作業は価格表を常に最新の状態に維持することです。

6. トレースの伝播:アプリケーションスパンとGatewayスパンの接続

Gatewayのトレースを有用なものにするには、その上流にあるアプリケーションのトレースと接続する必要があります。OpenTelemetryはW3C Trace Context仕様を使用します。これは、サービスの境界を越えてトレースIDと親スパンIDを伝達するtraceparent HTTPヘッダーです。Gatewayはインバウンドリクエストでこのヘッダーを読み取り、アプリケーションのスパンの子として自身のスパンを生成します。

OpenAI SDKを使用してGatewayを指すように設定されたPythonコードでは、伝播は次のようになります:

Python — アプリケーションがtraceparentを設定し、Gatewayがトレースを継続する

アプリケーションのタグ(northwind.team、northwind.feature)は、Gatewayがバゲージ(Baggage)および親スパンのカスタム属性を維持するため、ツリーの下位へと伝播します。これにより、Gateway側でNorthwind社のチーム構造に関する知識を持っていなくても、単一のコストダッシュボードで「先月サポートチームがエスカレーションの下書きにいくら費やしたか」という問いに答えることができます。

LLMプロバイダー自体はトレースを拡張しません — OpenAI、Anthropic、Bedrockは内部のトレースIDをクライアントに公開していません。取得できるのは、プロバイダー呼び出しに関するGateway側のビュー(Time-to-First-Byte、合計所要時間、トークン数)です。通常はこれで十分ですが、不十分な場合は、タイムスタンプを使用してプロバイダー独自の管理テレメトリと照合・関連付けを行います。

7. ストリーミングとTTFT:未受信レスポンスの計装方法

ストリーミングでは、レスポンスが単一のポイントインタイムのイベントではなく、数百年ミリ秒以上にわたって届くチャンクのシーケンスとなるため、スパンのタイミング測定が複雑になります。OTel GenAI仕様は、専用のメトリクスとスパンイベントパターンによってこれに対応しています。

GenAIメトリクス仕様で必須とされている関連メトリクスには、gen_ai.client.operation.duration(リクエスト全体から最後のチャンクまで)、gen_ai.client.operation.time_to_first_chunk(応答性の体感に最も影響するTTFT指標)、gen_ai.client.operation.time_per_output_chunk(チャンク間の間隔)があります。スパン自体には、TTFTをスパンイベントとして記録します:

Python — ストリームが開いている間にTTFTをスパンイベントとして記録する

運用上、2つのパターンが重要になります。スパンはストリーム全体が完了するまで開いたままにします — TTFTの時点で終了してしまうと、残りのタイミング情報が失われます。また、トークン数はストリームが閉じた時にのみ記録されます。これは、ほとんどのプロバイダーが最後のチャンク(Anthropic、OpenAI)または末尾のmessage_stopイベント内で最終的な使用量ブロックを送信するためです。早期にフラッシュするスパンエクスポーターを使用すると出力トークン数がゼロとなり、コスト属性付与が正しく行われません。

8. エクスポート設定:Datadog、Grafana Tempo、およびJaeger

TrueFoundryのGatewayは、OTLP/HTTPを介してOTelスパンを出力します。NATSを介してリクエストパスから分離されているため、バックエンドの障害が推論の利用可能性に影響を与えることはありません。Gatewayトレーシングドキュメントで統合パスがカバーされています。エクスポーターの設定はOTLP標準に準拠しており、互換性のある任意のバックエンドで動作します。

Datadog(OTLPインテーク経由)

Datadogは2025年12月以降、GenAIセマンティックコンベンションをネイティブでサポートしています。インテークパスは3つあります:直接OTLP、OTLPインジェストが有効化されたDatadog Agent、またはOpenTelemetry Collector(Datadog Distribution)です。

Datadog OTLPインテーク — 環境変数

Grafana Tempo(OTLP gRPC経由)

Grafana Tempo — gRPC OTLPエクスポーター

Jaeger(OTLP経由)

Jaeger — OTLP gRPC

本番ボリューム向けのサンプリング

開発段階および本番運用最初の1ヶ月間は100%のサンプリングで問題ありません。ボリュームが増加するにつれてのガイドライン:高ボリュームの正常系パスにはヘッドベースサンプリング(確率を例えば0.1に設定)を使用し、コレクター層でのテールベースサンプリングによって、ヘッドレートに関わらずエラーや遅延の発生したトレースを100%保持します。この組み合わせにより、障害発生時に重要なデータを失うことなく、ストレージコストを管理可能なレベルに抑えることができます。

高カーディナリティの属性(ユーザー識別子、リクエストID、プロンプトの全文など)については、スパン属性ではなくイベントやログを使用することを推奨します。OTelの属性カーディナリティバジェットは無視できず、10K文字のプロンプトをスパン属性として保持すると、予期せぬ高額なコストにつながる可能性があります。

9. よくある質問 (FAQs)

TrueFoundryのOTel collectorを使用する必要がありますか?それとも自前のものを持ち込めますか?

自前のコレクターを自由に持ち込むことができます。Gatewayは、互換性のある任意のバックエンドに対してOTLP標準のデータを出力します。TrueFoundryはDatadog、Honeycomb、Middleware、LangSmith、Grafana Tempoとの統合ドキュメントを提供しています。TrueFoundryがホストするコレクターは利便性のために提供されているものであり、ベンダーロックインを強いるものではありません。スパン上で完全なプロンプトやコンプレッション(出力結果)をキャプチャすべきですか?

デフォルトでは、キャプチャすべきではありません。現在の仕様では、gen_ai.promptやgen_ai.completion属性は非推奨となっており、コンテンツキャプチャが有効化されている場合は、イベント(スパン属性ではなく)として記録されるgen_ai.input.messagesおよびgen_ai.output.messagesの使用が推奨されています。その場合でも、キャプチャはオプトイン制にする必要があります。プロンプトにはPIIが含まれる可能性があり、巨大なプロンプトはスパンサイズを肥大化させます。すべてのトレースではなく、サンプリングされたトレースに対してキャプチャを行ってください。

ツール、サブエージェント、MCP呼び出しなどのエージェントトレースはどうなりますか?

GenAI仕様では、エージェントスパンを別途カバーしています:create_agent、invoke_agent、execute_tool。特にMCPツールの実行は、MCP計装によってトレース可能です。Gatewayはその境界上にあるすべての処理をキャプチャし、アプリケーションはその内部のすべての処理をキャプチャします。そしてトレースコンテキストがそれらを結合します。その結果、ツール呼び出しをINTERNALスパン、プロバイダー呼び出しをCLIENTスパンとして含む、エージェントループをエンドツーエンドでカバーする単一のウォーターフォールが得られます。

単一のトレースが複数のチームにまたがる場合、どのようにコストを割り当てますか?

所有者を識別する属性(northwind.team、northwind.cost_center、gen_ai.agent.name、あるいはその全て)をルートスパンにタグ付けします。コストはバックエンド側でそのタグごとに集計されます。タグの設定はアプリケーション側の責任であり、Gatewayはそれを保持して伝播させます。機能別や顧客別のコスト割り当てにも同じ仕組みが適用できます。

Developmentステータスであることを考慮すると、gen_ai属性に依存しても安全ですか?

バージョンの変更に留意すれば、概ね安全です。仕様がDevelopmentステータスであることは、非互換の変更が発生する可能性があることを意味します(最近のgen_ai.systemからgen_ai.provider.nameへの名称変更はまさにその例です)。緩和策として、OTEL_SEMCONV_STABILITY_OPT_IN環境変数が用意されており、計装ライブラリは古いコンシューマーを破壊することなく最新の実験的属性を選択的に利用できます。アップグレード時にはこれを意識して設定し、デフォルトの挙動がそのまま維持されることに依存しないようにしてください。

TrueFoundryはどこに位置づけられますか?

TrueFoundry AI Gatewayは、すべてのリクエストに対してOTel準拠のトレースを出力し、前述のスパン階層と最新仕様に沿ったgen_ai.*属性を設定します。トレースのエクスポートは非同期(NATS経由)で行われるため、可観測性バックエンドの状態が推論の利用可能性に影響を与えることはありません。また、Gatewayは§§5, 4, 3で説明したコスト計算、エラーの正規化、フォールバックトレースツリーの構築も処理します。自前のバックエンドをそのまま利用できる統合がファーストクラスでサポートされており、OTLP互換の任意の送信先が利用可能です。

次のステップ

現在LLMワークロードが可視化されていない場合、最も効果的な最初のステップは、Gatewayが稼働している場所からOTLP互換の任意のバックエンドにOTelデータをエクスポートすることです。これは週末の作業で完了できるレベルであり、スパンが流れ始めればダッシュボードの構築は容易です。

ここから始める: TrueFoundryトレーシングドキュメント。または、弊社のチームとの可観測性アーキテクチャレビューをご予約ください。

参考文献

引用文献は本文全体にリンクされています。以下のリストは、印刷およびリンク切れ対策としてすべてのURLをまとめたものです。

注:Northwind Logisticsは、設計を具体的なデプロイ例で説明するために使用された架空の企業です。§2の水曜日午後2時14分のトレースはスパンツリーを説明するために作成されたものであり、実際の本番環境のトレースはタイミングや稼働しているプロバイダーによって異なります。OTel GenAIセマンティックコンベンションは、OTel semconv v1.36.0の時点で開発中(Development)ステータスであり、属性名は今後も変更される可能性があります。

‍

Try now.

One gateway for all your models, MCP servers, and agents. No credit card needed.

Start free
Table of Contents

One Gateway for Every LLM, Agent and MCP Server

Book a 30-min with our AI expert

Book a Demo

The fastest way to build, govern and scale your AI

Book Demo
Summarize with
ChatGPT logo by OpenAI
Perplexity AI logo
Blurry red snowflake on white background, symmetrical frosty design with soft edges and abstract shape.

Discover More

No items found.
Guide to Langgraph vs Langchain
November 16, 2026
|
5 min read

LangChain vs LangGraph:どちらが最適か?

比較
A detailed guide on Claude Fable 5
November 16, 2026
|
5 min read

Claude Fable 5: API、ベンチマーク、料金、使い方

エンジニアリングとプロダクト
openrouter vs litellm
November 16, 2026
|
5 min read

LiteLLMとOpenRouter:あなたに最適なのはどちらか?

比較
November 16, 2026
|
5 min read

大規模言語モデルにおけるトランスフォーマーアーキテクチャ

LLM用語
No items found.

Recent Blogs

Black left pointing arrow symbol on white background, directional indicator.
Black left pointing arrow symbol on white background, directional indicator.
Take a quick product tour
Start Product Tour
Product Tour