HTTP语义约定已稳定

今年年初，我们启动了一个稳定HTTP语义约定的工作。今天，我们自豪地宣布HTTP语义约定是第一个被宣布为**稳定**的OpenTelemetry语义约定！这个首个稳定版本的v1.23.0在以前的版本基础上做了重大改进，包括：

• 与Elastic Common Schema一致性带来的增强，例如：
  • 可用于非HTTP语义约定的url.*命名空间，以供将来复用
  • 将net.peer.*和net.host.*命名空间替换为client.*和server.*，这样做的原因是：
    • 对于日志来说更好用，在日志中没有范围类型可以表明那一边是对等方，而那一边是主机
    • 简化了客户端和服务器遥测的关联（例如，可以直接使用server.address进行关联，而不必在net.peer.addr等于net.host.addr的位置进行关联）
    • 与network.*命名空间保持清晰分离，该命名空间仅用于低级网络属性
  • 更一致地使用http.request.*和http.response.*命名空间
• 与Prometheus的一致性改进，通过标准化以秒为单位的度量单位
• 精简了属性捕获，省略了一些不太有用的属性，减少了遥测捕获、处理和存储成本
• 澄清了默认值的定义，在属性缺失时消除了歧义
• HTTP度量指标不再容易出现基数膨胀
  • http.request.method对已知方法集合进行了限制（可配置）
  • 受Host标头影响的server.address和server.port现在对HTTP度量指标是可选的

迁移计划

由于修改数量众多且广泛影响了现有用户群体，我们要求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（稳定版）对HTTP语义约定所做的更改。

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	• 推荐改为可选（Opt-In） • 尚未稳定
http.response_content_length → http.response.body.size	• 推荐改为可选（Opt-In） • 尚未稳定
user_agent.original	• 在HTTP客户端跨度上推荐改为可选（Opt-In） • 在HTTP服务器跨度上现在必须提供给采样器 • 如果要迁移自<= v1.18.0，请参阅说明
net.protocol.name → network.protocol.name	推荐的条件必需值（Conditionally Required）；如果不是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未知，则也改为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

参考资料：

• v1.20.0常见属性
• v1.23.0（稳定版）常见属性

HTTP客户端跨度属性

更改	注释
http.url → url.full	无
http.resend_count → http.request.resend_count	无
net.peer.name → server.address	无
net.peer.port → server.port	即使与该协议的默认端口相同，也会捕获

参考资料：

• v1.20.0的HTTP客户端跨度属性
• v1.23.0（稳定版）的HTTP客户端跨度属性

HTTP服务器跨度属性

更改	注释
http.route	无变化
http.target → url.path 和 url.query	拆分为两个独立的属性
http.scheme → url.scheme	现在考虑[X-Forwarded-Proto][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头][Host header]、[:authority头][HTTP/2 authority][X-Forwarded-Host头][X-Forwarded-Host]、[Forwarded#host]头
net.host.port → server.port	仅基于[Host头][Host header]、[:authority头][HTTP/2 authority]、[X-Forwarded-Host头][X-Forwarded-Host]、[Forwarded#host]头

参考资料：

• v1.20.0的HTTP服务器跨度属性
• v1.23.0（稳定版）的HTTP服务器跨度属性

HTTP客户端和服务器的跨度名称

当{http.method}为_OTHER时，跨度名称的{http.method}部分被替换为HTTP。

如果从<= v1.17.0进行迁移，请参阅说明。

参考资料：

• v1.20.0的HTTP客户端和服务器跨度名称
• v1.23.0（稳定版）的HTTP客户端和服务器跨度名称

HTTP客户端持续时间度量指标

度量指标更改：

• 名称：http.client.duration → http.client.request.duration
• 单位：ms → s
• 描述：测量传入HTTP请求的持续时间 → HTTP服务器请求的持续时间
• 直方图桶：边界更新以反映从毫秒到秒的更改，并移除了零桶边界
• 属性：见下表

属性更改	注释
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	推荐的条件必需值，如果不是http并且设置了network.protocol.version则必需
net.protocol.version → network.protocol.version	示例修正：2.0 → 2 和 3 → 3；如果要迁移自<= v1.19.0，请参阅说明
新增：error.type

参考资料：

• v1.20.0度量指标http.client.duration
• v1.23.0（稳定版）度量指标http.client.request.duration

HTTP服务器持续时间度量指标

度量指标更改：

• 名称：http.server.duration → http.server.request.duration
• 单位：ms → s
• 描述：测量传入HTTP请求的持续时间 → HTTP服务器请求的持续时间
• 直方图桶：边界更新以反映从毫秒到秒的更改，并移除了零桶边界
• 属性：见下表

属性更改	注释
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][X-Forwarded-Proto]、[Forwarded#proto span][Forwarded#proto]头
net.protocol.name → network.protocol.name	推荐的条件必需值，如果不是http并且设置了network.protocol.version则必需
net.protocol.version → network.protocol.version	示例修正：2.0 → 2 和 3.0 → 3；如果要进行迁移，请参阅说明
net.host.name → server.address	• 推荐改为可选（Opt-In）（由于基于HTTP头信息，具有高基数容易受到漏洞） • 仅基于[Host头][Host header]、[:authority头][HTTP/2 authority]、[X-Forwarded-Host头][X-Forwarded-Host]、[Forwarded#host头][Forwarded#host]
net.host.port → server.port	• 推荐改为可选（Opt-In）（由于基于HTTP头信息，具有高基数容易受到漏洞） • 仅基于[Host头][Host header]、[:authority头][HTTP/2 authority]、[X-Forwarded-Host头][X-Forwarded-Host]、[Forwarded#host头][Forwarded#host]
新增：error.type

参考资料：

• v1.20.0度量指标http.server.duration
• v1.23.0（稳定版）度量指标http.server.request.duration

从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。

[Host头][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

社区致谢

这是一个大规模的社区努力：感谢所有参与其中的人！特别感谢Liudmila Molkova分享她HTTP领域的专业知识，这在整个过程中起到了关键作用。

• ←上一页
• 下一页→