HTTPセマンティック規約の安定版宣言
Blog posts are not updated after publication. This post is more than a year old, so its content may be outdated, and some links may be invalid. Cross-verify any information before relying on it.
今年の初め、HTTPセマンティック規約の安定化に向けた取り組みを開始しました。 本日、HTTPセマンティック規約がOpenTelemetryセマンティック規約として 初めて 安定版 と宣言されたことを誇りを持って発表します！ この最初の安定版 v1.23.0 リリースは、以前のバージョンからの大幅な進歩であり、以下の特長があります。
- Elastic Common Schema との統合による改善点。
たとえば以下のようなものがあります。
url.*名前空間。 将来、HTTP以外のセマンティック規約でも再利用可能です。net.peer.*およびnet.host.*名前空間をclient.*およびserver.*に置き換え。 これにより以下のメリットがあります。- ログにおいて、スパンの種類でどちら側がピアでどちら側がホストかを示す必要がなく、より適切に機能します。
- クライアントとサーバーのテレメトリー間の相関を簡素化します（たとえば、
net.peer.addr==net.host.addrを結合するかわりに、server.addressで直接結合できます）。 network.*名前空間からの明確な分離を提供します。network.*は現在、低レベルのネットワーク属性専用です。
http.request.*およびhttp.response.*名前空間の使用に関するより高い一貫性。
- Prometheus との一貫性の向上。 メトリクス単位を秒に標準化しました。
- あまり有用でない属性を省略することで属性のキャプチャを合理化し、テレメトリーのキャプチャ、処理、ストレージのコストを削減しました。
- デフォルト値の定義を明確化し、属性が存在しない場合のあいまいさを排除しました。
- HTTPメトリクスがカーディナリティの爆発に対して脆弱でなくなりました。
http.request.methodは（設定可能な）既知のメソッドの集合に制限されます。server.addressとserver.portはHostヘッダーの影響を受けるため、HTTPメトリクスではオプトインになりました。
移行計画
変更が多数あり、影響を受けるユーザーベースも広いため、OpenTelemetryが公開している既存のHTTP計装には、ユーザーが安定版HTTPセマンティック規約に移行するのを支援する移行計画を実装することを求めています。 他のセマンティック規約を安定化する際にも、同様の戦略を使用する予定です。
具体的には、OpenTelemetryが公開している既存のHTTP計装を安定版HTTPセマンティック規約に更新する場合、以下を行う必要があります。
- 既存のメジャーバージョンに環境変数
OTEL_SEMCONV_STABILITY_OPT_INを導入する必要があります。 この環境変数は以下の値を受け付けます。http- 安定版のHTTPおよびネットワーク規約を出力し、以前の計装が出力していた古いHTTPおよびネットワーク規約の出力を停止します。http/dup- 古い規約と安定版のHTTPおよびネットワーク規約の両方を出力し、安定版セマンティック規約の段階的な展開を可能にします。- デフォルトの動作（これらの値が指定されていない場合）は、計装が以前出力していたバージョンの古いHTTPおよびネットワーク規約を引き続き出力することです。
- 両方の規約の出力を開始してから少なくとも6か月間は、既存のメジャーバージョンのメンテナンス（最低限セキュリティパッチ）を行う必要があります。
- 次のメジャーバージョンで環境変数を廃止し、安定版のHTTPおよびネットワーク規約のみを出力することができます。
変更の概要
このセクションでは、HTTPセマンティック規約における v1.20.0 から v1.23.0（安定版） への変更をまとめます。
HTTPクライアントおよびサーバースパンの共通属性
| 変更 | コメント |
|---|---|
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 が設定されている場合に条件付きで必須 |
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クライアントスパン属性
| 変更 | コメント |
|---|---|
http.url → url.full | |
http.resend_count → http.request.resend_count | |
net.peer.name → server.address | |
net.peer.port → server.port | スキームのデフォルトポートと同じ場合でもキャプチャされるようになりました |
参考資料：
HTTPサーバースパン属性
| 変更 | コメント |
|---|---|
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 ヘッダーのみに基づくようになりました |
参考資料：
HTTPクライアントおよびサーバーのスパン名
スパン名の {http.method} 部分は、{http.method} が _OTHER の場合に HTTP に置き換えられます。
<= v1.17.0 からの移行の場合は注記を参照してください。
参考資料：
HTTPクライアント持続時間メトリクス
メトリクスの変更：
- 名前：
http.client.duration→http.client.request.duration - 単位：
ms→s - 説明：
Measures the duration of inbound HTTP requests.→Duration of HTTP server requests. - ヒストグラムバケット：ミリ秒から秒への変更を反映してバケット境界が更新され、ゼロバケット境界が削除されました
- 属性：以下の表を参照
| 属性の変更 | コメント |
|---|---|
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 が設定されている場合に条件付きで必須 |
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. - ヒストグラムバケット：ミリ秒から秒への変更を反映してバケット境界が更新され、ゼロバケット境界が削除されました
- 属性：以下の表を参照
| 属性の変更 | コメント |
|---|---|
http.route | 変更なし |
http.method → http.request.method | デフォルトで9つの一般的なHTTPメソッドのみをキャプチャするようになりました。加えて _OTHER もキャプチャされます |
http.status_code → http.response.status_code | |
http.scheme → url.scheme | X-Forwarded-Proto span、Forwarded#proto span ヘッダーを考慮するようになりました |
net.protocol.name → network.protocol.name | Recommended → http ではなく、network.protocol.version が設定されている場合に条件付きで必須 |
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 span、:authority span、X-Forwarded-Host span、Forwarded#host span ヘッダーのみに基づくようになりました |
net.host.port → server.port | • Recommended → Opt-In（HTTPヘッダーに基づくため、高カーディナリティの脆弱性があります） • Host span、:authority span、X-Forwarded-Host span、Forwarded#host span ヘッダーのみに基づくようになりました |
新規：error.type | 新規 |
参考資料：
v1.20.0 より前のバージョンからの移行
<= 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 になります。
コミュニティへの称賛
これは大規模なコミュニティの取り組みでした。 関わってくださった全員に感謝します！ 特に Liudmila Molkova には、HTTPドメインの専門知識を共有し、この取り組みのすべてのステップを推進する上で大きな力となっていただきました。