--- title: "OpenTelemetryのGenAIセマンティック規約｜gen_ai属性とメトリクスの体系・移行の判断" url: "https://www.issoh.co.jp/tech/details/17007/" published: 2026-08-26 updated: 2026-08-26 categories: ["AI"] publisher: "株式会社一創" --- # OpenTelemetryのGenAIセマンティック規約｜gen\_ai属性とメトリクスの体系・移行の判断 生成AIアプリケーションの計装で最初に迷うのは、属性名を自分で決めてよいのかどうかです。OpenTelemetryには `gen_ai` 名前空間の規約が用意されていますが、この規約は2026年6月に本体リポジトリから切り離され、移動先にはタグ付きリリースが1件もありません。ここでは属性とメトリクスの体系、本文を残すときの制御、改名の履歴から読む安定度、そして自社スキーマから寄せるかどうかの判断を、2026年8月時点の一次情報で整理します。属性命名の一般則とResource属性の扱いは[セマンティック規約そのものを解説した記事](https://www.issoh.co.jp/tech/details/16568/)に譲ります。 ## まとめ｜先に決める3点と、規約へ寄せる範囲の線引き 決めるのは3点だけです。第一に、必須属性の2つ（`gen_ai.operation.name` と `gen_ai.provider.name`）を出すかどうか。第二に、入出力メッセージの本文を残すかどうか。第三に、画面と警報の定義を規約の属性名で直接書くか、自社の名前を1枚かませるか。 規約は現在すべて Development です。専用リポジトリに移った後もタグ付きリリースは出ておらず、参照するスキーマを版で固定できません。属性名も過去に3度入れ替わっています。全面準拠を前提に画面と警報を作り込むと、改名のたびに定義を書き直す作業が発生します。 現実的な線引きはこうです。計装が出す属性名は規約へ寄せ、参照する側（画面・警報・課金集計）は自社の名前で受けて、間で対応付ける。こう割り切ると、規約の版が動いても壊れるのは対応付けの1か所で済みます。 ## GenAI規約が本体から分離した経緯と2026年8月時点の状態 ### 本体リポジトリのv1.42.0でgen\_ai配下が非推奨になった経緯 セマンティック規約は open-telemetry/semantic-conventions で管理されてきました。その v1.42.0（2026年6月12日）の破壊的変更に、「Generative AI のセマンティック規約を専用リポジトリへ移す」という項目が入ります。対象は `model` 配下の gen-ai・openai・mcp の定義と、docs 配下の解説一式。本体側ではこれらが非推奨になり、実体は open-telemetry/semantic-conventions-genai へ移りました。 公式サイトの該当ページも「移動済みで、このリポジトリでは保守しない」という案内に置き換わりました。本体の最新は v1.44.0（2026年8月4日）で、v1.43.0 以降に gen\_ai の定義は含まれません。計装側は移動先が示す `schema_url` を参照します。3つのシグナルとOTLPの基礎は[OpenTelemetry本体の仕組みを整理した記事](https://www.issoh.co.jp/tech/details/3625/)にまとめてあります。 ### タグ付きリリースが未発行で、スキーマURLを固定できない現状 分離先は Weaver で本体規約への依存を解決する構成で、docs にMarkdown、model にYAML定義、reference にPythonの参照適合表が置かれています。ただし releases ページは空のままで、タグ付きリリースは1件も出ていません。 ここが実務に効きます。規約は main ブランチ上で動いており、「この版に準拠した」と宣言する固定点がない状態です。`schema_url` を載せる設計にしても、指す先は開発中の識別子にしかなりません。分離は体制の整理であって、安定化の宣言ではないと読むのが妥当でしょう。 ## gen\_ai属性の体系｜必須2つを起点に条件付きと任意へ広げる ### 必ず付ける2属性｜operation.nameとprovider.nameの決まり 推論スパンで Required とされるのは `gen_ai.operation.name` と `gen_ai.provider.name` の2つだけです。前者は操作の種類を表す列挙で、chat・text\_completion・embeddings・generate\_content・execute\_tool・invoke\_agent・invoke\_workflow・retrieval・plan のほか、メモリ操作系まで18種あります。 後者は提供元の識別子で、anthropic・openai・aws.bedrock・azure.ai.openai・gcp.gemini・gcp.vertex\_ai・cohere・deepseek・groq・mistral\_ai・perplexity・x\_ai・ibm.watsonx.ai などが列挙値です。自社ゲートウェイ経由でも、実際に推論した提供元を入れます。スパン名は操作名とモデル名を空白でつないだ形と決まっており、ここを守るだけで集計が揃います。 ### 条件付き必須はモデル名・会話ID・エラー種別の3系統で決まる Conditionally Required は、条件に当てはまるなら必ず出す層です。中身は `gen_ai.request.model`（要求したモデル名）、`gen_ai.conversation.id`（会話の紐づけ）、`gen_ai.output.type`（text・json・image・speech の別）、`gen_ai.request.choice.count`、失敗時の `error.type` です。 Recommended には `gen_ai.response.model`（実際に応答したモデル名）や `gen_ai.request.temperature` が並びます。要求と応答でモデル名が分かれる点は見落としがちで、提供元がエイリアスを解決して別の版で応答する構成では、費用の突き合わせが後者でしか成立しません。 ### トークン数を数える属性は入力・出力・推論出力の3本立てになる 費用と速度の分析はトークン属性で成立します。`gen_ai.usage.input_tokens` と `gen_ai.usage.output_tokens` が基本で、推論用に消費した出力を別に数える `gen_ai.usage.reasoning.output_tokens` が加わりました。この3本立てで単価を掛けます。 注意点が1つ。入力トークンにはキャッシュ済みの分も含まれます。プロンプトキャッシュを効かせた構成では、素直に単価を掛けると費用を過大に見積もるため、集計側で割り引く処理を入れます。トレースを費用と評価につなぐ全体設計は[LLMOpsの4層構成を整理した記事](https://www.issoh.co.jp/tech/details/16069/)を参照してください。 ### ツール実行とエージェントの属性は、識別子を軸に組み立てられる ツール実行のスパンには `gen_ai.tool.name`、`gen_ai.tool.call.id`、`gen_ai.tool.type`（function・extension・datastore）が付きます。エージェント側は `gen_ai.agent.id` と `gen_ai.agent.name`、検索系は `gen_ai.data_source.id` です。 いずれも識別子が軸で、同じIDでスパンをまたいで束ねられる設計です。どのスパンを親子に置くか、どこで木を切るかという階層の設計は[エージェント実行のスパン木を扱った記事](https://www.issoh.co.jp/tech/details/16332/)に譲ります。 ## トークン数と待ち時間を測るメトリクス規約の一覧と単位の決めごと 規約が定めるのはスパンだけではありません。メトリクスも名前・種別・単位・境界まで決まっています。トレースを全件残さない構成でも、メトリクスは規約どおりに出しておくと後で効きます。 ### クライアント側の4本｜トークン数と所要時間と初回到達までの時間 呼び出す側が出すのは4本です。`gen_ai.client.token.usage` は単位 {token} のヒストグラムで、`gen_ai.operation.name`・`gen_ai.provider.name`・`gen_ai.token.type`（input か output）が必須属性。所要時間は `gen_ai.client.operation.duration` で単位は秒です。 ストリーミングなら残り2本が効きます。`gen_ai.client.operation.time_to_first_chunk` が最初の断片までの時間、`gen_ai.client.operation.time_per_output_chunk` が断片あたりの時間。合計時間だけを見ていると、待たされている実感との差を説明できません。 ### サーバー側とワークフロー、エージェント、ツールのメトリクス名 推論を提供する側には `gen_ai.server.request.duration`、`gen_ai.server.time_to_first_token`、`gen_ai.server.time_per_output_token` があり、自前の推論基盤や社内ゲートウェイならこちらも出せます。 実行の構造を測る系統も定義済みです。`gen_ai.invoke_workflow.duration`、`gen_ai.invoke_agent.duration`、`gen_ai.invoke_agent.inference_calls`、`gen_ai.invoke_agent.tool_calls`、`gen_ai.execute_tool.duration`。1依頼あたり何回モデルを呼び、何回ツールを叩いたかが残るため、ループ暴走の兆候を件数の分布で捉えられます。 ### バケット境界が規約で決まっているためヒストグラムを揃えられる 見落とされやすいのが境界値の指定です。トークン数のヒストグラムは1から67108864まで4倍刻みの14段、クライアント側の所要時間は0.01秒から81.92秒まで2倍刻みの14段と決められています。推論回数とツール呼び出し回数は1から128までの8段です。 境界が揃っていれば、サービスをまたいだ分位点の比較がそのまま成立します。逆に独自の境界で出すと、後から集約したときに分位点が壊れます。規約に従って得をする度合いが最も高いのは、このメトリクスの層でしょう。 ## 入出力メッセージはOpt-In｜本文を残すときの経路と制御の方法 ### 既定では本文を記録しない設計と、Opt-Inが意味する境界線 入出力の本文は Opt-In に分類されます。`gen_ai.input.messages`（モデルへ渡した会話履歴）、`gen_ai.output.messages`（応答）、`gen_ai.system_instructions`（系の指示）、`gen_ai.tool.definitions`（ツール定義）、それにツール呼び出しの引数と結果である `gen_ai.tool.call.arguments` と `gen_ai.tool.call.result` がここに入ります。 Opt-In は「利用者が明示的に有効化しない限り出さない」という意味です。規約側も、これらの属性が個人情報を含みうると明記しています。既定で出ないのは実装の手抜きではなく、規約が要求した挙動になります。 ### 本文の記録先は環境変数の4つの値でスパンとイベントに分かれる 制御は環境変数で行います。`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` が窓口で、取りうる値は4つです。 ``` OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=EVENT_ONLY OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT ``` 既定は NO\_CONTENT。SPAN\_ONLY はスパン属性として、EVENT\_ONLY は `gen_ai.client.inference.operation.details` というイベントとして残します。イベント側はトレースIDとスパンIDで元のスパンへ紐づくため、本文だけ保存期間や保存先を分けたいときはこちらです。本文は役割（user・assistant・tool）と部品に分けた構造化形式で記録します。 ### 入出力を残すと決めたときに設計へ足す3つの取り扱いの決めごと 残す判断をしたなら、3つを同時に決めます。1つ目は伏せ字の範囲。規約は実装がフィルタや切り詰めの手段を用意してよいとしており、氏名・連絡先・口座番号の類は計装の段階で落とします。2つ目は保存期間で、本文は30〜90日、失敗した実行だけ長く残す二段構えが扱いやすい形です。 3つ目は参照権限。トレース画面に本文が出るとは、閲覧できる全員が利用者の入力を読めるということでもあります。本文を含むイベントだけ別の保存先へ送って権限を分けておくと、後から監査を求められたときに説明がつきます。 ## 属性名の改名が3度起きた｜トークン名と提供元の指定の入れ替え ### イベント方式から構造化属性へ移った2025年8月の版とその影響 安定度は表示だけでは測れません。主な変更を時系列で並べます。 | 版 | 時期 | 主な変更 | | ------- | -------- | --------------- | | v1.27.0 | 2024年 | トークン属性の改名 | | v1.37.0 | 2025年8月 | 提供元属性の改名と本文の構造化 | | v1.38.0 | 2025年10月 | 評価結果イベントの追加 | | v1.41.0 | 2026年4月 | エージェント計装の分割 | | v1.42.0 | 2026年6月 | 専用リポジトリへの移動 | 影響が大きかったのは v1.37.0 です。`gen_ai.system` が `gen_ai.provider.name` へ改名され、同時にメッセージ単位のイベント4種が非推奨になり構造化属性へ置き換わりました。v1.27.0 では `gen_ai.usage.prompt_tokens` が `input_tokens` へ、`completion_tokens` が `output_tokens` へ変わっています。日本語の解説に旧名が残るのはこのためです。 ### Development表記のまま使う前提で警報と画面を作る線引き 履歴から読めるのは、改名は名前空間の単位で起き、意味そのものは動いていないという点です。トークン数を数える概念は最初からあり、属性名だけが2度変わりました。だから警報と画面を規約の属性名で直接書くと、改名のたびに定義を触ることになります。集計クエリの中で1度だけ自社の名前へ写像し、それ以降は自社名で書く。この1枚を挟むかどうかが、規約が動く期間の運用コストを分けます。 ## 実装ライブラリごとの追随差と、規約準拠を名乗れる範囲の見分け方 ### Python参照実装の適合表が示すスパン種別ごとの対応の広がり 規約が決まっていても、実際に出る属性を決めるのはライブラリです。分離先には、Pythonの実クライアントライブラリを対象にした参照適合表が置かれています。対象は30本超で、提供元のSDK（anthropic、openai、google-genai、cohere）、クラウド側（aws-bedrock、azure-openai、vertexai）、エージェント基盤（langchain、llamaindex、crewai、pydantic-ai）、評価系（deepeval、dspy、haystack）まで含みます。 見方に癖があります。総合スコアではなく、スパン12種・イベント2種・メトリクス4種の種別ごとに対応可否が並ぶ形式です。提供元のSDKは推論とメトリクスを出すが検索系は出さない、エージェント基盤はエージェント系スパンを広く出す、といった偏りが読み取れます。 ### 規約準拠という名乗りが同じでも、既定の版が違うという食い違い もう1つの差は版です。同じ「GenAI規約に対応」という表記でも、既定で出す属性名が v1.36 世代のままで、新しい名前は明示的に有効化しないと出ない実装があります。逆に、新旧の提供元属性を両方出して互換を取る実装も存在します。新しく作られた計装なら現行の名前だけでしょう。受け取る側がどの属性をどの欄へ割り当てるかは実装ごとに異なり、Langfuseの場合は[Langfuse OpenTelemetry連携の実装](https://www.issoh.co.jp/tech/details/17009/)で対応表を整理しています。 結果として、複数のライブラリを併用する基盤では、同じ意味の値が `gen_ai.system` と `gen_ai.provider.name` に散らばります。集計側で両方拾うか、Collector で片側へ寄せるかの選択です。 ### フレームワーク側の実装を見分けるために確かめる3つの箇所と手順 判定は3か所で足ります。1つ目、実際に出たスパンの属性キーを1件そのまま見る。2つ目、版の切り替え設定を持つか。3つ目、本文記録の既定値が NO\_CONTENT 相当かどうか。開発環境でコンソール出力のエクスポーターを1度だけ挟み、1リクエスト分の生の属性を控えておけば、更新で何が変わるかの予測がつきます。 ## 自社スキーマから規約へ寄せる移行手順と、見送ってよい2つの場面 ### まず二重出力から始めて参照側を直し、新しい進め方へ寄せる進め方 安全な順序は決まっています。第一段階、旧名と新名を両方出す。属性が増えるだけなので既存の画面は壊れません。第二段階、画面・警報・課金集計の参照側を新名へ書き換える。第三段階、旧名の出力を止める。先に旧名を消すと、参照側が沈黙して気づけない不具合になります。 移行の単位は名前空間で切ります。トークン系だけ先に寄せ、次に提供元属性という進め方です。全属性を一度に切り替える計画は、途中で規約が動いたときに巻き戻せません。 ### Collectorで属性名を書き換える手は暫定にとどめる理由 Collector の変換処理で旧名を新名へ書き換える方法もあります。アプリケーションを触らずに済むため、移行期間の橋渡しには有効です。ただし恒久策にはしません。書き換え規則が増えるほど設定が計装の履歴を抱え込んで誰も消せなくなり、送信元が何を出しているかも設定を読まないと分からなくなるためです。 期限を切って使うのが前提です。「参照側の書き換えが終わるまで」という条件を設定に残し、終わったら規則ごと削除する運用にしてください。 ### 規約へ寄せずに自社の名前のまま通してよい2つの場面とその条件 寄せなくてよい場面が2つあります。1つ目は、単一の提供元・単一の基盤で完結し、テレメトリを外部のバックエンドへ持ち出す予定がない場合。共通語彙の利点は複数の出所を突き合わせるときに出るため、出所が1つなら効果は薄くなります。 2つ目は、検証段階で計装の寿命が数か月と決まっている場合。規約が動いている以上、短命な基盤に追随コストを払う理由はありません。逆に、提供元を複数併用する、バックエンドを差し替える見込みがある、費用を部門別に配賦する、のいずれかなら寄せる側に倒します。 ### 計装と移行の設計を委託するときに見積書で確かめる4項目の中身 外部へ委託する場合、見積書で確かめる項目は4つです。第一に、必須2属性に加えてどの条件付き属性まで出すかの範囲。第二に、本文記録の既定値と、有効化したときの伏せ字・保存期間・参照権限の設計。第三に、規約が改名されたときの追随の扱い（保守に含むのか、都度見積もりか）。第四に、既存スキーマからの移行を二重出力の3段階で進める前提になっているか。 この4点が曖昧なままだと、計装は動いているのに費用の按分ができない、本文が想定より広く残っていた、という形で後から表面化します。計装設計から移行までの相談は、[生成AI開発・AI受託開発](https://www.issoh.co.jp/service/ai/development/)で対応しています。 ## よくある質問 ### GenAI規約はどこを見れば最新の定義が分かりますか？ 2026年8月時点では open-telemetry/semantic-conventions-genai の docs 配下が実体です。本体リポジトリと公式サイトの旧ページは移動済みの案内に置き換わり、記述は保守されていません。定義そのものを確かめたいときは model 配下のYAMLを見ます。 ### Development のまま本番で使って問題ありませんか？ 計装が出す側は使って差し支えありません。壊れるのは参照する側です。属性名の変更で影響を受けるのは画面・警報・集計クエリなので、そこを自社の名前で受けて対応付けを1か所へ集めておけば、Development のままでも運用できます。 ### gen\_ai.system という属性名の記事を見かけますが違いますか？ v1.37.0（2025年8月）で `gen_ai.provider.name` へ改名された旧名です。それ以前の解説や旧世代の計装ライブラリが出力する場合があります。混在する基盤では集計側で片方へ寄せてください。 ### プロンプトの本文はトレースに残すべきですか？ 既定では残さない設計で、その既定に従うのが出発点です。失敗の再現に本文が要る場面はありますが、その場合も伏せ字・保存期間・参照権限の3点を決めてから有効化します。失敗した実行だけイベント側へ分けて残す構成が扱いやすいでしょう。 ### OpenAIやAnthropicごとの個別規約もあるのですか？ あります。Anthropic、OpenAI、AWS Bedrock、Azure AI Inference の4本と、MCP 向けの記述が同じリポジトリにあります。いずれも Development で、提供元固有の項目を共通規約に足す形です。まず共通側を満たし、固有の項目は必要になってから足す順番で足ります。 ## 関連記事 - [OpenTelemetryのセマンティック規約｜属性命名と安定版の見分け方](https://www.issoh.co.jp/tech/details/16568/)（命名の一般則とResource属性） - [エージェントトレーシングとは？スパン木の設計・gen\_ai属性・記録範囲を実装目線で解説【2026年版】](https://www.issoh.co.jp/tech/details/16332/)（スパン木の階層設計） - [OpenTelemetry（OTel）とは｜3つのシグナル・OTLP・Collector・Prometheusとの違いを解説](https://www.issoh.co.jp/tech/details/3625/)（本体の仕組み） - [LLMOpsとは？MLOpsとの違いとトレース・評価・コスト管理の実装を解説【2026年版】](https://www.issoh.co.jp/tech/details/16069/)（トレースと評価の全体設計） --- 出典: [OpenTelemetryのGenAIセマンティック規約｜gen\_ai属性とメトリクスの体系・移行の判断]()（株式会社一創）