2026.08.15 インフラ

OpenTelemetryのセマンティック規約｜属性命名と安定版の見分け方

計装を始めたチームが最初につまずくのは、SDKの入れ方ではなく属性名です。あるサービスは http.method、別のサービスは request_method。どれも間違いではないのに、横断クエリを書こうとした瞬間に破綻する。OpenTelemetryのセマンティック規約（semantic conventions、通称semconv）は、この属性名の語彙をあらかじめ決めておく仕様群です。2026年8月15日時点の最新は v1.44.0（2026-08-04リリース）。

本記事では、Resource属性とSpan属性の命名体系、安定版と開発中ステータスの見分け方、HTTP規約の名称変更でダッシュボードを壊さない移行手順、自前の属性を足すときの命名ルールを一次情報から整理します。規約に沿うかどうかの判断も、採用条件と見送る場面を分けて言い切る。

まとめ：OpenTelemetryセマンティック規約の要点

  • セマンティック規約は、属性名・メトリクス名・span名の共通語彙を定めた仕様群。最新は v1.44.0（2026-08-04）で、月1回程度で版が上がる
  • 対象は Resource・Span・Metric・Log・Event・Profile。Resource属性はプロセス単位、Span属性は操作単位の素性を持たせる
  • 命名は小文字・ドット区切りの入れ子namespace・複合語はsnake_case。単一実体は単数形、配列型は複数形
  • 要件レベルは Required・Conditionally Required・Recommended・Opt-In の四段階。全部埋める必要はなく、Requiredから順に埋める
  • 安定度は Stable と Development に大別される。Stableは後方非互換の変更をメジャー番号の増加なしに行わない保証
  • HTTP規約は v1.23.0 で最初の安定版として宣言され、http.method は http.request.method へ、http.url は url.full へ改名された
  • 移行は OTEL_SEMCONV_STABILITY_OPT_IN に http/dup を与えて新旧を二重出力し、参照側を直してから新規約へ片寄せする
  • 自前の属性は逆ドメイン形式（com.example.tenant_id）で名前空間を切る。otel. 始まりは予約済みで使えない
  • 規約準拠が効くのは複数チーム・複数言語・複数バックエンドをまたぐとき。単一サービス単一チームなら無理に寄せる価値は薄い

セマンティック規約とは何か｜属性名の共通語彙がテレメトリで解く問題

OpenTelemetryはトレース・メトリクス・ログを言語やベンダを問わない形で出すための仕様とSDKの集まりです。ただし「出せる」ことと「読める」ことは別物で、属性の名前がばらばらなら集めた先で突き合わせられない。セマンティック規約は、その名前を決める側の仕様にあたります。全体構成やOTLPの役割はOpenTelemetry（OTel）とは｜3つのシグナル・OTLP・Collector・Prometheusとの違いを解説で確認できます。

規約が定義するのは属性名・メトリクス名・span名の三層である

規約が触れる範囲は属性名だけではありません。仕様のトップページを実測すると、対象シグナルとして Resource・Span・Metric・Log・Event・Profile が並び、領域別には General、Database、HTTP、Messaging、RPC、System などが定義されています。「spanを何という名前にするか」「所要時間メトリクスは何という名前と単位か」「そこに付ける属性は何か」までが一続きで決まっている。

実装者が触るのは主に三層です。第一にResource属性で、サービス名やデプロイ環境などプロセス全体に共通する素性を持つ。第二にSpan属性とメトリクス属性で、操作ごとの素性を持ちます。第三にspan名やメトリクス名そのもので、属性ではなく識別子として規約に従う。

規約に沿うと何が変わるか｜バックエンド側の自動相関が成立する

直接の見返りは、バックエンド側の機能が前提を持てる点にあります。多くの製品は service.name でサービス一覧を、http.response.status_code でエラー率を自動的に組み立てる。属性名が規約どおりなら、手作りしなくても最初の画面が埋まります。自前の名前で出していると製品側の自動機能は空振りし、手作りのクエリで代替し続けることになる。

もうひとつの見返りは載せ替えのときに現れます。属性名が規約準拠なら、送り先を別の製品へ変えてもクエリの書き換えは接続部分だけで済む。送信経路の選択肢はDatadog OpenTelemetry連携の4方式｜OTLP送信とDDOTの選び分けで扱いましたが、経路を変えても語彙が変わらないことが移行コストを下げます。

Resource属性とSpan属性の命名体系｜namespaceと単数複数の規則

命名体系は明文化されています。仕様の Naming ページを実測すると、守るべき決まりは次の形に整理できる。

Resource属性はプロセス単位、Span属性は操作単位で持たせる

Resource属性は、そのプロセスが何者かを表します。サービス名、バージョン、デプロイ環境、ホスト、リージョンが該当し、生存期間中は変わらないためSDKの初期化時に一度だけ設定する。対してSpan属性は、その1回の操作が何をしたかを表します。HTTPメソッド、パス、ステータスコードなどです。

resource:
  service.name: checkout-api
  service.version: 2026.8.0
  deployment.environment.name: production
  cloud.region: ap-northeast-1

span:
  http.request.method: POST
  url.path: /api/v1/orders
  server.address: checkout-api.example.com
  http.response.status_code: 201

この分け方を守らないと実害が2つ出ます。ひとつは容量で、プロセス不変の値をspanごとに複製すればペイロードが膨らむ。もうひとつは検索性で、サービス名がResource側に無いとサービス単位の集計が組めません。系列数の論点はOpenTelemetryのメトリクス実装｜計器選定とカーディナリティ設計で扱っています。

属性名の綴りは小文字とドット区切り、複合語はsnake_caseで書く

綴りの規則は4点です。名前は小文字で書く。namespaceはドットで区切り、入れ子にしてよい（telemetry.sdk.name）。1要素が複数語なら snake_case でつなぎます（http.response.status_code）。そして曖昧さを残さない粒度にし、仕様は file.owner.name の例でプロパティ名まで含めることを求めています。

単数形と複数形の使い分けも明文化されています。単一の実体を表す属性は単数形（host.name）、複数の実体は配列型にしたうえで複数形にします（process.command_args）。ここを揺らすと、同じ意味の属性が二本立てで増殖していく。

要件レベルはRequiredからOpt-Inまで四段階で読み分ける

規約の各属性には要件レベルが付いています。「全部埋めろ」と読むと過剰になるため、四段階の意味を押さえておきたい。

要件レベル 計装側に求められること 例
Required すべての計装が必ず設定する http.request.method
Conditionally Required 条件が成立するときは必ず設定 http.route
Recommended 容易に取れるなら既定で付与 server.address
Opt-In 利用者が明示的に有効化した時のみ 逆引きを伴う属性

Conditionally Required の条件は規約側に明記されます。http.route なら、フレームワークがルート情報を提供する場合に限る、という具合。Recommended は既定で付けるべきものですが、性能やセキュリティ上の懸念があれば設定で切れます。Opt-In は逆引きのようにコストや情報漏れを伴うため既定では出さない。自前の計装では Required から先に満たすのが手堅い順序です。

安定版と実験的ステータスの見分け方｜Stableは何を保証するのか

セマンティック規約は領域ごとに成熟度が違います。ここを見誤ると、ダッシュボードを作った翌月に属性名が変わって壊れる。

StableとDevelopmentの差は破壊的変更が起き得るかどうかにある

仕様の Versioning and Stability を実測すると、区分は Development・Stable・Deprecated・Removed です。Development は破壊的変更や性能上の問題が起き得る段階で、長期的な依存は推奨されていない。Stable は後方非互換の変更をメジャー番号の増加なしには行えません。Deprecated は代替が安定版になった場合にのみ指定でき、Stableと同じ保証が適用される。

運用側の読み替えは単純です。Stable な属性はアラート条件やSLOの分母に据えてよい。Development な属性は探索的に見るのは構いませんが、それを根拠に呼び出しを鳴らす設計にはしない。この線引きだけで、版上げのたびに監視が壊れる事故は減ります。

テレメトリ安定性が守るのは属性キーの名前であって値の中身ではない

見落としやすいのが保証の範囲です。テレメトリ安定性が守るのは、リソース属性のキー、span名とspan kindと属性キー、メトリクス名と型と単位、ログレコードの属性キー。属性の値そのものと、新しい属性が追加されることは保証の対象外とされています。

つまりキーが消えないことは保証されますが、そこに入る値の集合が将来増えないことは保証されない。ダッシュボードでは、キーの存在を前提にしてよく、値の網羅を前提にしてはいけません。「未知の値はその他へ落ちる」形で集計を組んでおくと版上げに耐えます。

どこまで安定かはRegistryのステータス表記で個別に確かめる

領域単位で「HTTPは安定」と覚えるのは近似に過ぎません。仕様サイトの属性レジストリには各属性のステータスが並び、同じHTTP領域でもStableとDevelopmentが混在する。版を上げる前に、依存している属性だけ抜き出して確認してください。

HTTP規約の移行手順｜ダッシュボードとアラートを壊さない切り替え

セマンティック規約で最も広く影響が出たのがHTTP領域の安定化です。HTTP規約は v1.23.0 で、最初の安定版セマンティック規約として宣言されました。このとき属性名がまとまって変わり、既存のダッシュボードの参照先がずれる事態が起きています。

旧属性から新属性への対応表は名前空間の単位でまとめて把握する

移行ガイドを実測した対応は次のとおりです。個別に覚えるより「入出力は http.request.* と http.response.* へ、URL要素は url.* へ、通信相手は server.* と client.* へ、下位プロトコルは network.* へ」という名前空間の再編として捉えると迷いません。

旧属性名 新属性名 変更の要点
http.method http.request.method request配下へ移動
http.status_code http.response.status_code response配下へ移動
http.url url.full URL要素はurl配下へ
http.target url.path と url.query 2つの属性へ分割
http.flavor network.protocol.version 下位層はnetwork配下へ
http.user_agent user_agent.original 独立した名前空間へ
net.peer.name server.address 役割で名前空間を分離
http.client_ip client.address client配下へ統合

属性名だけでなくメトリクスの単位も変わりました。HTTPの所要時間はミリ秒から秒へ揃えられています。閾値をベタ書きしたアラートは1000倍ずれるため、対応表の確認と同時に単位も見直す。

移行は二重出力から始め、参照側を直してから新規約へ片寄せする

移行を安全に進める仕組みが環境変数 OTEL_SEMCONV_STABILITY_OPT_IN です。取り得る値は3通り。http を指定すると新しい安定規約のみを発行して旧規約を止め、http/dup なら新旧の両方を同時に発行します。未設定なら従来の旧規約を発行し続ける。

# 段階1: 新旧を二重に出す（ダッシュボードは旧のまま動く）
OTEL_SEMCONV_STABILITY_OPT_IN=http/dup

# 段階3: 参照側の修正が終わったら新規約のみへ
OTEL_SEMCONV_STABILITY_OPT_IN=http

実務の手順は3段階です。段階1で二重出力へ切り替え、既存のダッシュボードを動かしたまま新属性が届いていることを確かめる。段階2で、クエリ・ダッシュボード・アラート・記録ルールを新属性名へ書き換えます。抜けを防ぐには旧属性名の文字列で全ダッシュボード定義を横断検索するやり方が確実。段階3で新規約のみへ切り替え、旧属性が消えても壊れないことを確認します。

期間の目安も仕様側の方針から読めます。ライブラリの保守者には、二重出力の開始から最低6か月は既存メジャー版を維持し、次のメジャー版で新規約へ統一する方針が示されている。利用側もこれに準じ、段階1と段階3の間を数週間から数か月とると見落としが炙り出されます。

Collector側で属性を書き換える手もあるが恒久策にはしない

アプリ側のSDK版を上げられない事情があるとき、OpenTelemetry Collector の transform プロセッサで属性名を差し替える回避策があります。

processors:
  transform/semconv:
    error_mode: ignore
    trace_statements:
      - set(attributes["http.request.method"], attributes["http.method"])
      - delete_key(attributes, "http.method")

緊急避難としては機能しますが、恒久策には向きません。理由は3つ。第一に書き換えルールが規約の版上げに追随しない。第二にアプリ側が正しい属性を出すようになったとき、二重に書き換えて壊れます。第三に、書き換えを知らない担当者がデータの出所を追えなくなる。SDK側を直すまでの橋渡しと割り切ってください。

独自属性を足すときの命名ルール｜逆ドメイン接頭辞と名前の再利用禁止

規約は業務ドメインの語彙までは決めません。テナントIDや契約プランといった属性は自分たちで名付けます。ここにも明文の規則がある。

社名を接頭辞にした逆ドメイン形式で自前の名前空間を切っておく

仕様は、企業固有の属性には逆ドメイン名を接頭辞にすることを推奨しています（例 com.acme.shopname）。アプリ固有ならアプリ名を接頭辞にする。規約が使っている名前空間を自前属性の接頭辞に流用することは推奨されていません。http.tenant_id のような名付けは、将来 http. 配下に同名の属性が定義されたときに衝突する。

実務では社内で1つの接頭辞を決め切ってしまうのが早い方法です。jp.co.example. のように決め、その配下だけを自由領域とする。接頭辞と属性の一覧をリポジトリで差分管理すれば、語彙の分裂を抑えられます。

otel.で始まる名前は予約済みで、勝手に定義してはいけない

もうひとつの禁止事項が予約名前空間です。otel. で始まる属性名はOpenTelemetry仕様が定義するために予約されており、追加には仕様側の承認が必要とされている。SDK内部の状態を表すために使われる領域なので、自前の属性をここに置いてはいけません。

加えて Name Reuse Prohibition があります。2つの属性、2つのメトリクス、2つのイベントが同名を持つことは禁止です（種別が違えば同名でも構いません）。不要になった名前は削除ではなく非推奨化して残す。消して同じ名前を別の意味で再利用するやり方は、過去の集計を静かに壊すため避けてください。ログ側を同時に整えるなら、構造化ログとは｜JSONでログを機械可読にする仕組みとslog/structlog実装のフィールド設計と語彙を揃えておくと突き合わせが後から効きます。

規約準拠が後から効く場面と、過剰適用になって手間だけ増える場面

規約準拠は投資であり、効く場面と効かない場面があります。判断軸を言い切っておく。

後から効くのは、担当者が入れ替わっても同じ問い合わせが通る点

規約準拠が確実に効くのは、次の3条件のいずれかに当てはまるときです。第一に、サービス数が概ね5本を超え、実装言語が2つ以上に分かれているとき。人手の申し合わせで属性名を保つのは、この規模で限界を迎える。第二に、製品を将来変える可能性があるとき。第三に、ライブラリの自動計装に任せているとき。自動計装は規約準拠の名前で出すため、自前の名前と混ぜると二重管理になります。

逆説的ですが、規約準拠の見返りが最も大きいのは書いた本人がいなくなった後です。3年後に別の担当者が決済APIのエラー率を求められたとき、http.response.status_code で引ける状態と、サービスごとに違う名前を調べ直す状態とでは、到達までの時間が桁で変わる。

過剰適用になるのは、社内固有の値まで無理に規約へ寄せに行くとき

一方で、過剰適用になる場面もはっきりしています。典型は業務ドメインの概念を無理やり既存の規約属性へ押し込むケース。社内の「加盟店区分」を service.namespace に入れる、業務IDを http.route に混ぜる。名前は規約準拠に見えますが、意味が食い違うため製品側の自動機能はかえって誤作動します。逆ドメイン接頭辞で自前属性を切るほうが安全。

もうひとつは、単一サービス・単一チーム・単一バックエンドで内部指標だけを見ている段階です。この規模なら統制コストのほうが上回る。Requiredの属性だけ揃え、残りは自分たちの都合で名付けても実害は出ません。ただし service.name と deployment.environment.name は規模を問わず規約どおりにしておく。ここが揃っていないと、サービスが増えたときに全件を書き直す羽目になります。

採用の線引き｜まずRequired属性、次に自社の判断軸を足す

実務で迷ったときの順序は次のとおりです。第一段階は、service.name・service.version・deployment.environment.name と、使っている領域のRequired属性を規約どおりに揃えること。ここまでは規模を問わず投資回収できます。第二段階で自動計装のRecommended属性はそのまま通し、問題が出たものだけ個別に切る。第三段階で、業務判断に必要な自前属性を逆ドメイン接頭辞で足します。

属性を足すほど系列とペイロードは膨らむため、サンプリングの設計と併せて考えると無駄が出ません。トレース側の絞り方はトレースサンプリングとは？ヘッドベースとテールベースの仕組み・OpenTelemetry実装で整理しています。計装がOpenTracing世代のまま残っている場合は、属性名の移行より先にOpenTracingとOpenTelemetryの違い｜shim移行の手順と載せ替え判断で載せ替えを判断してください。

属性の統制は、決めることより決めた状態を保つことのほうが難しい領域です。システム保守運用・内製化支援では、既存環境の計装状況を実測したうえで、属性設計と監視移行の手順づくりから運用の引き継ぎまでを支援しています。

よくある質問

セマンティック規約に従わないと動かないのですか？

いいえ、従わなくてもテレメトリの送受信自体は動きます。規約は語彙の取り決めであって、プロトコルの必須要件ではありません。ただし製品側の自動的なサービス一覧やエラー率の集計は規約どおりの属性名を前提に組まれており、従わない場合は空振りする。

規約はどのくらいの頻度で変わりますか？

GitHubのリリースを実測すると、2026年8月15日時点で v1.44.0（2026-08-04）、v1.43.0（2026-07-03）、v1.42.0（2026-06-12）と、概ね月1回のペースで版が上がっています。ただし版が上がるたびにStableな属性名が変わるわけではなく、多くは新領域の追加やDevelopment段階の定義変更。依存している属性がStableなら、月次の版上げに一喜一憂する必要はありません。

既存のダッシュボードを壊さずに移行できますか？

できます。環境変数 OTEL_SEMCONV_STABILITY_OPT_IN に http/dup を与えると新旧の属性が同時に出るため、既存のダッシュボードを動かしたまま新属性へクエリを書き換えられます。書き換えが済んでから http に切り替えて旧属性を止める。二重出力の期間はデータ量が増える点だけ織り込んでください。

独自の属性を足しても規約準拠と言えますか？

言えます。規約は業務ドメインの語彙までは定めておらず、自前の属性を足すこと自体を想定しています。守るべきは名前空間の切り方で、逆ドメイン形式の接頭辞を使い、otel. 始まりを避け、既存の規約namespaceを流用しないこと。この3点を守れば、規約準拠の属性と自前属性は共存します。

生成AI関連の属性はどの規約を見ればよいですか？

LLM呼び出しやエージェント実行には gen_ai. 名前空間の規約が別途定義されています。本記事の一般規約とは対象領域が異なり、トークン数やモデル名の扱いなど固有の論点があるため、生成AI基盤の計装ではそちらを個別に確認してください。ステータスが動いている属性も含まれます。

関連記事

資料請求

RELATED POSTS 関連記事

一覧へ戻る