OpenTelemetry JS 语义约定更新方案解析

背景介绍

在 OpenTelemetry JS 项目中，语义约定(Semantic Conventions)是定义各种遥测数据属性名称和含义的重要规范。随着规范的演进，如何管理不同版本的语义约定成为了一个需要解决的问题。本文将深入分析 OpenTelemetry JS 社区讨论的几种语义约定更新方案。

方案对比分析

方案1：package.json 多入口点

这个方案通过在 package.json 中为每个语义约定版本创建单独的入口点来实现版本管理。稳定属性通过主入口导出，实验性属性则隐藏在版本特定的入口点下。

优点：

• 清晰的版本隔离
• 直观的导入方式

缺点：

• 随着版本增多，安装包体积会显著膨胀
• 长期维护成本高

方案2：每个版本独立发布包

此方案为每个语义约定版本发布独立的 npm 包，每个包只包含对应版本的生成属性。

优点：

• 完全隔离不同版本
• 版本管理明确

缺点：

• 版本命名可能不够直观
• 用户需要在 package.json 中进行特殊配置
• 依赖管理复杂度增加

方案2.1：版本号直接包含在包名中

这是方案2的变体，将语义约定版本直接包含在包名中，避免用户手动配置。

优点：

• 版本对应关系更加明确
• 用户使用更简单

缺点：

• 需要维护多个包
• 旧版本更新困难

方案3：稳定/实验性入口点

该方案使用 package.json 入口点来区分稳定和实验性属性。主入口只包含稳定属性，实验性属性通过特定路径导入。

优点：

• 安装包体积优化
• 清晰的属性分类
• 向后兼容性好
• 维护成本相对较低

缺点：

• 需要处理属性命名冲突问题

社区共识与选择

经过深入讨论，OpenTelemetry JS 社区最终选择了方案3作为实现方向。这一选择基于以下几个关键考量：

1. 用户体验：方案3提供了最直观的使用方式，开发者可以轻松区分稳定和实验性属性。

2. 维护成本：相比多版本方案，方案3的长期维护负担更小。

3. 兼容性：通过合理设计，方案3能够很好地处理向后兼容性问题。

4. 性能：避免了安装包体积的过度膨胀。

技术实现细节

在最终确定的方案3中，技术实现包含以下关键点：

1. 主入口：只导出稳定属性，确保生产环境的安全性。

2. 实验性入口：通过/experimental路径提供实验性属性的访问。

3. 弃用管理：

   • 弃用属性保留在主入口中，使用@deprecated标记
   • 同时也在新导出中标记为弃用
   • 目前没有稳定的弃用属性

4. 版本演进：

   • 采用语义化版本控制
   • 考虑未来发布2.0版本移除命名空间版本和旧SEMATTRS名称
   • 确保有适当的过渡期

开发者使用示例

开发者可以这样使用新的语义约定：

// 导入稳定属性
import { STABLE_ATTR } from '@opentelemetry/semantic-conventions';

// 导入实验性属性
import { SOME_EXPERIMENTAL_ATTR } from '@opentelemetry/semantic-conventions/experimental';

这种设计既保持了API的简洁性，又提供了足够的灵活性来支持不同稳定级别的属性。

总结

OpenTelemetry JS 社区通过深入讨论和权衡，选择了以稳定/实验性入口点为核心的语义约定更新方案。这一方案在用户体验、维护成本和性能之间取得了良好平衡，为JavaScript生态中的OpenTelemetry用户提供了清晰、可靠的语义约定管理方式。随着规范的持续演进，这一设计也将为未来的扩展提供坚实的基础。