HTTP 语义约定稳定性迁移

由于修改数量巨大，且受影响的用户众多，OpenTelemetry 发布的原有 HTTP 遥测需要实施一个迁移计划，以帮助用户过渡到稳定的 HTTP 语义约定。

具体来说，当 OpenTelemetry 发布的原有 HTTP 遥测更新到稳定的 HTTP 语义约定后，它们将

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

OTEL_SEMCONV_STABILITY_OPT_IN 仅用于从实验性语义约定迁移到其初始稳定版本。

更改摘要

本节总结了从 v1.20.0 到 v1.23.1 (稳定版) 的 HTTP 语义约定所做的更改。

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

更改注释
http.method → http.request.method现在默认（可配置）只捕获 9 种常见的 HTTP 方法，加上 _OTHER
http.status_code → http.response.status_code
http.request.header.<key>• <key> 中的连字符（"-"）到下划线（"_"）的规范化已删除
• 在 HTTP 服务器 span 上：现在必须提供给采样器
http.response.header.<key><key> 中的连字符（"-"）到下划线（"_"）的规范化已删除
http.request_content_length → http.request.body.size• 推荐 → 可选加入
• 尚未标记为稳定
http.response_content_length → http.response.body.size• 推荐 → 可选加入
• 尚未标记为稳定
user_agent.original• 在 HTTP 客户端 span 上：推荐 → 可选加入
• 在 HTTP 服务器 span 上：现在必须提供给采样器
• 如果 从 <= 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 服务器 span 上：如果 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 标头
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 标头
• 现在即使与 scheme 的默认端口相同也已捕获
net.sock.host.addr → network.local.address
net.sock.host.port → network.local.port当设置了 network.local.address 时，不再默认为 server.port。

参考

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 outbound HTTP requests. → Duration of HTTP client 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现在即使与 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.
  • 直方图桶: 边界已更新，以反映从毫秒到秒的更改，并移除了零桶边界
  • 属性：见下表
属性变更注释
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推荐 → 如果不是 http 且设置了 network.protocol.version，则为有条件必需
net.protocol.version → network.protocol.version示例已修复：2.0 → 2 和 3.0 → 3；如果 从 <= v1.19.0 迁移，请参见注释
net.host.name → server.address• 推荐 → 可选加入（由于基于 HTTP 标头的高基数漏洞）
• 现在仅基于 Host span、:authority span、X-Forwarded-Host span、Forwarded#host span 标头
net.host.port → server.port• 推荐 → 可选加入（由于基于 HTTP 标头的高基数漏洞）
• 现在仅基于 Host span、:authority span、X-Forwarded-Host span、Forwarded#host span 标头
新增：error.type

参考

从 v1.20.0 之前的版本迁移？

除了从 v1.20.0 到 v1.23.1 (稳定版) 的 HTTP 语义约定所做的更改之外，如果您从 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 服务器 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}

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

从 <= v1.16.0 迁移

此页面不涵盖这些版本。