> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/non-normative/http-migration/


# 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](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)から[v1.23.1（安定版）](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/README.md)への変更をまとめます。

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

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

参考:

- [共通属性 v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#common-attributes)
- [共通属性 v1.23.1（安定版）](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-spans.md#common-attributes)

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

<!-- prettier-ignore-start -->
| Change | Comments |
| --- | --- |
| `http.url` &rarr; `url.full` | |
| `http.resend_count` &rarr; `http.request.resend_count` | |
| `net.peer.name` &rarr; `server.address` | |
| `net.peer.port` &rarr; `server.port` | スキームのデフォルトポートと同じ場合でも取得するようになった |
<!-- prettier-ignore-end -->

参考:

- [HTTPクライアントのスパン属性 v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#http-client)
- [HTTPクライアントのスパン属性 v1.23.1（安定版）](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration)

### HTTPサーバーのスパン属性

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

参考:

- [HTTPサーバーのスパン属性 v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#http-server)
- [HTTPサーバーのスパン属性 v1.23.1（安定版）](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration)

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

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

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

参考:

- [HTTPクライアントとサーバーのスパン名 v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md#name)
- [HTTPクライアントとサーバーのスパン名 v1.23.1（安定版）](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration)

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

メトリクスの変更点:

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

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

参考:

- [メトリクス`http.client.duration` v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md#metric-httpclientduration)
- [メトリクス`http.client.request.duration` v1.23.1（安定版）](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration)

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

メトリクスの変更点:

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

<!-- prettier-ignore-start -->
| 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`ヘッダー][X-Forwarded-Proto]、[`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以前からの移行](#v1190以前からの移行)の場合は注記を参照 |
| `net.host.name` → `server.address` | &bullet; Recommended → Opt-In（HTTPヘッダーに基づくため高カーディナリティになる脆弱性があることによる）<br>&bullet; [`Host`ヘッダー][Host header]、[`:authority`][HTTP/2 authority]、[`X-Forwarded-Host`ヘッダー][X-Forwarded-Host]、[`Forwarded#host`ヘッダー][Forwarded#host]のみに基づくようになった |
| `net.host.port` → `server.port` | &bullet; Recommended → Opt-In（HTTPヘッダーに基づくため高カーディナリティになる脆弱性があることによる）<br>&bullet; [`Host`ヘッダー][Host header]、[`:authority`][HTTP/2 authority]、[`X-Forwarded-Host`ヘッダー][X-Forwarded-Host]、[`Forwarded#host`ヘッダー][Forwarded#host]のみに基づくようになった |
| 新規: `error.type` | |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`http.server.duration` v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md#metric-httpserverduration)
- [メトリクス`http.server.request.duration` v1.23.1（安定版）](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/docs/http/http-metrics.md#metric-httpserverrequestduration)

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

HTTPセマンティック規約の[v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)から[v1.23.1（安定版）](https://github.com/open-telemetry/semantic-conventions/blob/v1.23.1/README.md)への変更に加えて、v1.20.0より前のバージョンからv1.23.1へ移行する場合には、さらに追加の変更があります。

### v1.19.0以前からの移行

- `http.flavor` &rarr; `network.protocol.version`
  - 例を修正: `2.0` &rarr; `2`、`3.0` &rarr; `3`

### v1.18.0以前からの移行

- `http.user_agent` &rarr; `user_agent.original`

### v1.17.0以前からの移行

#### HTTPサーバーのスパン名

- `http.route`が利用可能な場合:<br> `{http.route}` &rarr;
  `{summary} {http.route}`
- `http.route`が利用可能でない場合:<br> `HTTP {http.method}` &rarr;
  `{summary}`

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

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

- `HTTP {http.method}` &rarr; `{summary}`

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

### v1.16.0以前からの移行

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

[Host header]: https://tools.ietf.org/html/rfc7230#section-5.4
[HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1
[Forwarded#for]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for
[Forwarded#proto]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto
[Forwarded#host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#host
[X-Forwarded-For]: https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For
[X-Forwarded-Proto]: https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto
[X-Forwarded-Host]: https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Host