HTTP语义约定已宣布稳定

作者：Trask Stalnaker (Microsoft) | 2023 年 11 月 06 日，星期一

博客文章在发布后不会更新。这篇文章已经发布一年多了，其内容可能已过时，部分链接可能无效。在依赖任何信息之前，请务必核实。

今年早些时候，我们启动了一项稳定 HTTP 语义约定工作的努力。今天，我们自豪地宣布，HTTP 语义约定是第一个被声明为稳定的 OpenTelemetry 语义约定！ inaugural stable v1.23.0 版本标志着比早期版本有了实质性进展，其特点是

由于与 Elastic Common Schema 的融合而产生的增强功能，例如
- url.* 命名空间，将来可以被非 HTTP 语义约定重用
- 用 client.* 和 server.* 替换 net.peer.* 和 net.host.* 命名空间，这
  - 对于日志来说效果更好，因为没有 span kind 来指示哪一方是对端，哪一方是主机
  - 简化了客户端和服务器遥测之间的一致性（例如，因为您可以直接通过 server.address 进行连接，而不是通过 net.peer.addr == net.host.addr 进行连接）
  - 与 network.* 命名空间实现了清晰的分离，该命名空间现在仅用于低级网络属性
- 在重用 http.request.* 和 http.response.* 命名空间方面更加一致
通过标准化指标单位为秒，与 Prometheus 保持了更好的兼容性。
通过省略不那么有用的属性来简化属性捕获，从而降低了遥测捕获、处理和存储成本。
明确了默认值的定义，消除了属性缺失时的歧义。
HTTP 指标不再容易受到基数爆炸的影响
- http.request.method 被限制在一个（可配置的）已知方法集合中
- server.address 和 server.port（受 Host header 影响）现在是 HTTP 指标的 Opt-In

迁移计划

由于进行了大量修改，并且受影响的用户众多，因此要求 OpenTelemetry 发布现有的 HTTP 仪器化实现一个迁移计划，以帮助用户过渡到稳定的 HTTP 语义约定。我们打算在稳定其他语义约定使用类似的策略。

具体来说，当 OpenTelemetry 发布现有的 HTTP 仪器化更新到稳定的 HTTP 语义约定后，它们

需要在其现有主版本中引入一个环境变量 OTEL_SEMCONV_STABILITY_OPT_IN，该变量接受
- http - 发射稳定的 HTTP 和网络约定，并停止发射仪器化先前发出的旧 HTTP 和网络约定。
- http/dup - 同时发射旧的和稳定的 HTTP 和网络约定，允许分阶段推出稳定的语义约定。
- 默认行为（在没有这些值的情况下）是继续发出仪器化先前发出的任何版本的旧 HTTP 和网络约定。
需要维护（至少包括安全修补）其现有主版本，自开始同时发出两套约定之日起至少六个月。
可以在其下一个主版本中删除环境变量，并且仅发出稳定的 HTTP 和网络约定。

更改摘要

在本节中，我们总结了从 v1.20.0 到 v1.23.0 (stable) 的 HTTP 语义约定所做的更改。

HTTP 客户端和服务器 spans 中的通用属性

更改	注释
`http.method` → `http.request.method`	默认（可配置）仅捕获 9 个常用 HTTP 方法以及 `_OTHER`
`http.status_code` → `http.response.status_code`
`http.request.header.<key>`	• 移除了 `<key>` 中的破折号 (`"-"`) 到下划线 (`"_"`) 的标准化 • 在 HTTP 服务器 spans 上：现在必须提供给采样器
`http.response.header.<key>`	移除了 `<key>` 中的破折号 (`"-"`) 到下划线 (`"_"`) 的标准化
`http.request_content_length` → `http.request.body.size`	• 推荐 → Opt-In • 尚未标记为稳定
`http.response_content_length` → `http.response.body.size`	• 推荐 → Opt-In • 尚未标记为稳定
`user_agent.original`	• 在 HTTP 客户端 spans 上：推荐 → Opt-In • 在 HTTP 服务器 spans 上：现在必须提供给采样器 • 如果从 <= v1.18.0 迁移，请参见注释
`net.protocol.name` → `network.protocol.name`	推荐 → 有条件要求，如果不是 `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 服务器 spans 上：如果 `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 客户端 span 属性

更改	注释
`http.url` → `url.full`
`http.resend_count` → `http.request.resend_count`
`net.peer.name` → `server.address`
`net.peer.port` → `server.port`	现在即使与 scheme 的默认端口相同也已捕获

参考

HTTP 服务器 span 属性

更改	注释
`http.route`	无变化
`http.target` → `url.path` 和 `url.query`	拆分为两个单独的属性
`http.scheme` → `url.scheme`	现在会考虑 X-Forwarded-Proto、Forwarded#proto header
`http.client_ip` → `client.address`	如果 `http.client_ip` 未知（即，没有 X-Forwarded-For、Forwarded#for header），则 `net.sock.peer.addr` → `client.address`；现在必须提供给采样器
`net.host.name` → `server.address`	现在仅基于 Host、:authority、X-Forwarded-Host、Forwarded#host header
`net.host.port` → `server.port`	现在仅基于 Host、:authority、X-Forwarded-Host、Forwarded#host header

参考

HTTP 客户端和服务器 span 名称

当 {http.method} 为 _OTHER 时，span 名称中的 {http.method} 部分将被 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.
Histogram buckets: boundaries updated to reflect change from milliseconds to seconds, and zero bucket boundary removed
属性：见下表

属性变更	注释
`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`	现在即使与 scheme 的默认端口相同也已捕获
`net.sock.peer.addr`	已移除
`net.protocol.name` → `network.protocol.name`	推荐 → 有条件要求，如果不是 `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.
Histogram buckets: boundaries updated to reflect change from milliseconds to seconds, and zero bucket boundary removed
属性：见下表

属性变更	注释
`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 header
`net.protocol.name` → `network.protocol.name`	推荐 → 有条件要求，如果不是 `http` 且设置了 `network.protocol.version`
`net.protocol.version` → `network.protocol.version`	修复了示例：`2.0` → `2` 和 `3.0` → `3`；如果从 `<= v1.19.0` 迁移，请参见注释
`net.host.name` → `server.address`	• 推荐 → Opt-In（由于基于 HTTP header 存在高基数漏洞） • 现在仅基于 `Host` span、`:authority` span、`X-Forwarded-Host` span、`Forwarded#host` span header
`net.host.port` → `server.port`	• 推荐 → Opt-In（由于基于 HTTP header 存在高基数漏洞） • 现在仅基于 `Host` span、`:authority` span、`X-Forwarded-Host` span、`Forwarded#host` span header
新增：`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 服务器 span 名称

当 http.route 可用时
{http.route} → {summary} {http.route}
当 http.route 不可用时
HTTP {http.method} → {summary}

其中 {summary} 是 {http.method}，除非 {http.method} 是 _OTHER，在这种情况下 {summary} 是 HTTP。

HTTP 客户端 span 名称

HTTP {http.method} → {summary}