HTTPセマンティック規約の安定性に関する移行

変更点の量が多く、影響を受けるユーザー基盤も広範であることから、OpenTelemetryが公開している既存のHTTP計装は、安定版のHTTPセマンティック規約への移行をユーザーが行いやすくする移行計画を実装する必要があります。

具体的には、OpenTelemetryが公開している既存のHTTP計装が安定版のHTTPセマンティック規約に更新される際には、次のようにします。

既存のメジャーバージョンにおいて、環境変数OTEL_SEMCONV_STABILITY_OPT_INを導入すべきです（SHOULD）。この変数は次の値を受け付けます。
- http - 安定版のHTTPとネットワーキングの規約を発行し、それまで計装が発行していた古いHTTPとネットワーキングの規約の発行を停止します。
- http/dup - 古い規約と安定版の規約の両方を発行し、安定版セマンティック規約への段階的な移行を可能にします。
- これらの値がいずれも指定されていない場合のデフォルトの動作は、その計装がそれまで発行していた古いHTTPとネットワーキングの規約のバージョンをそのまま発行し続けることです。
両方の規約セットを発行し始めてから少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチの適用という形で）維持する必要があります。
次のメジャーバージョンでは、この環境変数を削除し、安定版のHTTPとネットワーキングの規約のみを発行してもかまいません（MAY）。

[!NOTE] OTEL_SEMCONV_STABILITY_OPT_INは、実験的なセマンティック規約から最初の安定版への移行時にのみ使用することを意図しています。

変更点のまとめ

この節では、HTTPセマンティック規約について、v1.20.0からv1.23.1（安定版）への変更をまとめます。

HTTPクライアントとサーバーのスパンに共通する属性

Change	Comments
`http.method` → `http.request.method`	デフォルトでは、9種類の共通HTTPメソッドと`_OTHER`のみを取得するようになった（設定可能）
`http.status_code` → `http.response.status_code`
`http.request.header.<key>`	• `<key>`内でのダッシュ（`"-"`）からアンダースコア（`"_"`）への正規化を廃止 • HTTPサーバーのスパンでは、サンプラーに提供することが必須になった
`http.response.header.<key>`	`<key>`内でのダッシュ（`"-"`）からアンダースコア（`"_"`）への正規化を廃止
`http.request_content_length` → `http.request.body.size`	• Recommended → Opt-In • まだ安定版としてマークされていない
`http.response_content_length` → `http.response.body.size`	• Recommended → Opt-In • まだ安定版としてマークされていない
`user_agent.original`	• HTTPクライアントのスパンでは: Recommended → Opt-In • HTTPサーバーのスパンでは、サンプラーに提供することが必須になった • v1.18.0以前からの移行の場合は注記を参照
`net.protocol.name` → `network.protocol.name`	Recommended → `http`ではなく`network.protocol.version`が設定されている場合はConditionally required
`net.protocol.version` → `network.protocol.version`	• 例を修正: `2.0` → `2`、`3.0` → `3` • v1.19.0以前からの移行の場合は注記を参照
`net.sock.family`	削除
`net.sock.peer.addr` → `network.peer.address`	HTTPサーバーのスパンでは: `http.client_ip`が不明であった場合、`net.sock.peer.addr` → `client.address`にもなる。`client.address`はサンプラーに提供しなければならない
`net.sock.peer.port` → `network.peer.port`	`server.port`と同じ場合でも取得するようになった
`net.sock.peer.name`	削除
新規: `http.request.method_original`	`http.request.method`が`_OTHER`の場合にのみ取得される
新規: `error.type`

参考:

HTTPクライアントのスパン属性

Change	Comments
`http.url` → `url.full`
`http.resend_count` → `http.request.resend_count`
`net.peer.name` → `server.address`
`net.peer.port` → `server.port`	スキームのデフォルトポートと同じ場合でも取得するようになった

参考:

HTTPサーバーのスパン属性

Change	Comments
`http.route`	変更なし
`http.target` → `url.path`と`url.query`	2つの別々の属性に分割
`http.scheme` → `url.scheme`	X-Forwarded-Proto、Forwarded#protoヘッダーを考慮するようになった
`http.client_ip` → `client.address`	`http.client_ip`が不明であった場合（すなわちX-Forwarded-For、Forwarded#forヘッダーがない場合）、`net.sock.peer.addr` → `client.address`となる。サンプラーに提供することが必須になった
`net.host.name` → `server.address`	Host、:authority、X-Forwarded-Host、Forwarded#hostヘッダーのみに基づくようになった
`net.host.port` → `server.port`	• Host、:authority、X-Forwarded-Host、Forwarded#hostヘッダーのみに基づくようになった • スキームのデフォルトポートと同じ場合でも取得するようになった
`net.sock.host.addr` → `network.local.address`
`net.sock.host.port` → `network.local.port`	`network.local.address`が設定されている場合に`server.port`をデフォルト値としなくなった

参考:

HTTPクライアントとサーバーのスパン名

{http.method}が_OTHERの場合、スパン名内の{http.method}部分はHTTPに置き換えられます。

v1.17.0以前からの移行の場合は注記を参照してください。

参考:

HTTPクライアントの処理時間メトリクス

メトリクスの変更点:

名前: http.client.duration → http.client.request.duration
単位: ms → s
説明: Measures the duration of outbound HTTP requests. → Duration of HTTP client requests.
ヒストグラムのバケット: ミリ秒から秒への変更を反映して境界値を更新し、ゼロバケットの境界を削除
属性: 以下の表を参照

Attribute change	Comments
`http.method` → `http.request.method`	デフォルトでは、9種類の共通HTTPメソッドと`_OTHER`のみを取得するようになった
`http.status_code` → `http.response.status_code`
`net.peer.name` → `server.address`
`net.peer.port` → `server.port`	スキームのデフォルトポートと同じ場合でも取得するようになった
`net.sock.peer.addr`	削除
`net.protocol.name` → `network.protocol.name`	Recommended → `http`ではなく`network.protocol.version`が設定されている場合はConditionally required
`net.protocol.version` → `network.protocol.version`	例を修正: `2.0` → `2`、`3.0` → `3`。v1.19.0以前からの移行の場合は注記を参照
新規: `error.type`

参考:

HTTPサーバーの処理時間メトリクス

メトリクスの変更点:

名前: http.server.duration → http.server.request.duration
単位: ms → s
説明: Measures the duration of inbound HTTP requests. → Duration of HTTP server requests.
ヒストグラムのバケット: ミリ秒から秒への変更を反映して境界値を更新し、ゼロバケットの境界を削除
属性: 以下の表を参照

Attribute change	Comments
`http.route`	変更なし
`http.method` → `http.request.method`	デフォルトでは、9種類の共通HTTPメソッドと`_OTHER`のみを取得するようになった
`http.status_code` → `http.response.status_code`
`http.scheme` → `url.scheme`	`X-Forwarded-Proto`ヘッダー、`Forwarded#proto`ヘッダーを考慮するようになった
`net.protocol.name` → `network.protocol.name`	Recommended → `http`ではなく`network.protocol.version`が設定されている場合はConditionally required
`net.protocol.version` → `network.protocol.version`	例を修正: `2.0` → `2`、`3.0` → `3`。v1.19.0以前からの移行の場合は注記を参照
`net.host.name` → `server.address`	• Recommended → Opt-In（HTTPヘッダーに基づくため高カーディナリティになる脆弱性があることによる） • `Host`ヘッダー、`:authority`、`X-Forwarded-Host`ヘッダー、`Forwarded#host`ヘッダーのみに基づくようになった
`net.host.port` → `server.port`	• Recommended → Opt-In（HTTPヘッダーに基づくため高カーディナリティになる脆弱性があることによる） • `Host`ヘッダー、`:authority`、`X-Forwarded-Host`ヘッダー、`Forwarded#host`ヘッダーのみに基づくようになった
新規: `error.type`

参考:

v1.20.0より前のバージョンからの移行

HTTPセマンティック規約のv1.20.0からv1.23.1（安定版）への変更に加えて、v1.20.0より前のバージョンからv1.23.1へ移行する場合には、さらに追加の変更があります。

v1.19.0以前からの移行

http.flavor → network.protocol.version
- 例を修正: 2.0 → 2、3.0 → 3

v1.18.0以前からの移行

http.user_agent → user_agent.original

v1.17.0以前からの移行

HTTPサーバーのスパン名

http.routeが利用可能な場合:
{http.route} → {summary} {http.route}
http.routeが利用可能でない場合:
HTTP {http.method} → {summary}

{summary}は{http.method}ですが、{http.method}が_OTHERの場合は{summary}はHTTPになります。

HTTPクライアントのスパン名

HTTP {http.method} → {summary}

{summary}は{http.method}ですが、{http.method}が_OTHERの場合は{summary}はHTTPになります。

v1.16.0以前からの移行

このページではこれらのバージョンは対象としていません。