OpenTelemetry JavaScript 语义约定 v1.31.0 版本解析

OpenTelemetry 作为云原生时代可观测性领域的重要标准，其语义约定（Semantic Conventions）为各类遥测数据提供了统一的命名和结构规范。本文重点分析 OpenTelemetry JavaScript 实现中最新发布的语义约定 v1.31.0 版本带来的重要变化。

核心变更概述

本次 v1.31.0 版本更新主要围绕三个方面展开：CPU 监控指标的标准化重构、新增硬件主机监控指标，以及对 Kubernetes 资源指标的完善。这些变更体现了 OpenTelemetry 在系统监控领域的持续演进。

CPU 监控指标重构

本次版本对 CPU 相关指标进行了重要重构，将原先以 system.cpu 为前缀的指标统一迁移到新的 cpu 命名空间下：

• 原 system.cpu.frequency 变更为 cpu.frequency
• 原 system.cpu.time 变更为 cpu.time
• 原 system.cpu.utilization 变更为 cpu.utilization

这种重构使得指标命名更加简洁，同时与其他技术栈的命名保持更好的一致性。开发者需要注意及时更新代码中对这些指标的引用。

新增硬件主机监控指标

v1.31.0 引入了以 hw.host 为前缀的一系列新指标，用于监控主机硬件状态：

• hw.host.ambient_temperature：主机环境温度
• hw.host.energy：主机能耗
• hw.host.heating_margin：主机加热余量
• hw.host.power：主机功率

这些指标特别适用于需要监控物理服务器或边缘设备硬件状态的场景，为基础设施监控提供了更丰富的维度。

Kubernetes 资源指标完善

在 Kubernetes 监控方面，本次更新主要涉及：

1. 复制控制器(ReplicationController)相关指标的命名规范化：

   • 原 k8s.replication_controller.available_pods 变更为 k8s.replicationcontroller.available_pods
   • 原 k8s.replication_controller.desired_pods 变更为 k8s.replicationcontroller.desired_pods

2. 新增多个 Kubernetes 资源属性：

   • HPA(Horizontal Pod Autoscaler)相关属性：k8s.hpa.name 和 k8s.hpa.uid
   • ResourceQuota 相关属性：k8s.resourcequota.name 和 k8s.resourcequota.uid
   • ReplicationController 标识属性：k8s.replicationcontroller.name 和 k8s.replicationcontroller.uid

这些变更使得 Kubernetes 监控数据的结构更加完整和一致。

OpenTelemetry SDK 监控指标

本次更新还新增了多个用于监控 OpenTelemetry SDK 本身运行状态的指标：

• 导出相关指标：otel.sdk.exporter.span.exported.count、otel.sdk.exporter.span.inflight.count
• 处理相关指标：otel.sdk.processor.span.processed.count、otel.sdk.processor.span.queue.capacity、otel.sdk.processor.span.queue.size
• Span 相关指标：otel.sdk.span.ended.count、otel.sdk.span.live.count

这些指标为诊断和优化 OpenTelemetry SDK 的性能提供了有力工具。

移动端应用监控增强

针对移动应用场景，新增了以下属性：

• Android 应用状态：android.app.state，包含 background/created/foreground 等状态值
• iOS 应用状态：ios.app.state，包含 active/background/foreground/inactive/terminate 等状态值

这些属性使得移动应用的性能监控能够更准确地反映应用的实际运行状态。

其他重要变更

1. 终端用户相关属性：

   • 重新启用了 enduser.id 属性
   • 新增 enduser.pseudo.id 用于匿名用户标识

2. 代码追踪相关：

   • 废弃了 code.namespace 属性，建议将其内容合并到 code.function.name 中
   • 将 code.filepath 重命名为 code.file.path

3. 生成式 AI 相关：

   • 新增了多个 Agent 和 Tool 相关属性
   • 将 gen_ai.openai.request.response_format 替换为更通用的 gen_ai.output.type

升级建议

对于正在使用 OpenTelemetry JavaScript 实现的开发者，建议：

1. 检查项目中是否使用了本次变更中废弃的属性，及时更新为新的命名
2. 评估新增指标和属性是否适用于当前监控场景，考虑纳入监控体系
3. 特别关注 CPU 指标的变化，确保指标采集和展示不受影响

OpenTelemetry 语义约定的持续演进体现了其在统一可观测性标准方面的努力，开发者及时跟进这些变化将有助于构建更加标准化和可维护的监控系统。