OpenTelemetry-JS项目中HTTP语义规范的稳定化实现

背景介绍

OpenTelemetry-JS项目近期正在推进HTTP语义规范的稳定化工作。语义规范(Semantic Conventions)是OpenTelemetry中定义的标准属性集合，用于确保不同组件和语言产生的遥测数据具有一致的命名和含义。HTTP作为最常用的协议之一，其语义规范的稳定化对整个可观测性体系具有重要意义。

稳定化方案设计

项目团队设计了一个分阶段迁移方案，核心思路是：

1. 环境变量控制：通过OTEL_SEMCONV_STABILITY_OPT_IN环境变量提供灵活的过渡选项

   • http值表示仅使用稳定的HTTP属性
   • http/dup值表示同时输出实验性和稳定的HTTP属性(双写模式)

2. 版本演进策略：

   • 当前版本默认保持现有实验性HTTP属性
   • 允许通过配置选择稳定属性或双写模式
   • 下个主版本将完全切换到稳定HTTP属性

技术实现细节

实现工作分为多个关键部分：

HTTP客户端跨度实现

已完成对HTTP客户端跨度的改造，主要包括：

• 新增环境变量解析逻辑
• 实现属性双写机制
• 确保向后兼容性

HTTP服务端跨度实现

服务端跨度改造工作正在进行中，重点考虑：

• 请求/响应头处理
• 状态码映射
• 协议版本识别

其他相关组件

计划中的改造还包括：

• Fetch API集成
• XMLHttpRequest处理
• 其他HTTP相关组件

实际应用建议

对于使用者而言，建议采取以下迁移策略：

1. 测试阶段：设置http/dup模式，验证新旧属性同时存在时的系统表现
2. 过渡阶段：逐步将仪表板和告警规则迁移到使用稳定属性
3. 完成迁移：最终切换到仅使用稳定属性的模式

未来展望

随着HTTP语义规范的稳定化完成，OpenTelemetry-JS将提供更可靠、长期兼容的观测数据。这也为其他语义规范的稳定化工作提供了参考模板，有助于提升整个OpenTelemetry生态的成熟度。

项目团队将持续优化实现细节，确保从实验性到稳定性的平滑过渡，同时保持对现有用户的最小影响。