指标语义约定
状态: 混合
定义了以下指标相关的语义约定
- 通用指南: 通用指标指南。
- 数据库: 用于 SQL 和 NoSQL 客户端指标。
- FaaS: 用于 服务函数 指标。
- GenAI: 用于生成式 AI 指标。
- HTTP: 用于 HTTP 客户端和服务器指标。
- 消息: 用于消息系统（队列、发布/订阅等）指标。
- RPC: 用于 RPC 客户端和服务器指标。
- .NET: 用于 .NET 运行时组件发出的网络相关指标。
- 系统指标
- OTel SDK 遥测: OpenTelemetry SDK 组件发出的指标。
除了指标的语义约定，OpenTelemetry 还定义了 跟踪、日志 和 事件 的语义约定，以及具有自身 资源语义约定 的 资源 的概念。
通用指南
状态: 开发中
在定义新的指标名称和属性时，请考虑现有标准指标以及来自框架/库的指标的先例。
相关的指标应根据其使用情况嵌套在一个层次结构中。为通用指标类别定义顶级层次结构：例如，OS 指标（如 CPU 和网络）；应用运行时指标，如 GC 内部。库和框架也应将其指标嵌套在层次结构中。这有助于发现和临时比较。它允许用户在给定某个指标时找到相似的指标。
指标的层次结构定义了命名空间。支持 OpenTelemetry 的工件为某些类别的指标定义了指标结构和层次结构，这些可以帮助在创建未来指标时做出决策。
通用属性应命名一致。这有助于发现并消歧化相似属性与指标名称。
“经验法则，一个给定指标所有属性的聚合应有意义，” 如 Prometheus 所建议。
应避免语义歧义。当相似指标在现有指标的广度中具有显著不同的实现时，请使用带前缀的指标名称。例如，每个垃圾回收的运行时都有略微不同的策略和度量。使用一组单一的 GC 指标名称，而不按运行时划分，可能会造成不相似的比较和用户混淆。（例如，优先使用 jvm.gc* 而不是 gc.*。）许多操作系统指标的度量同样具有歧义。
指标名称和属性应遵循通用的 命名指南。
单位
约定指标或在其 OpenTelemetry 元数据中包含单位的指标（例如 Go 中的 metric.WithUnit）不应在指标名称中包含单位。当单位为指标名称提供附加含义时，可以包含单位。指标必须，最重要的是，易于理解和使用。
在构建在 OpenTelemetry 和使用 OpenMetrics 暴露格式的系统之间进行互操作的组件时，请使用 OpenMetrics 指南。
Instrument 单位
状态: 稳定
单位应遵循 统一度量代码。
- 用于利用率指标（测量总数的比例）的 Instrument 是无量纲的，应使用默认单位
1（单位）。 - 所有使用花括号注释数量的非单位都必须与它所代表的数量的语法数匹配。例如，如果测量对进程的单个请求数，单位应为
{request}，而不是{requests}。 - 测量某个整数计数的 Instrument 应仅使用花括号的 注释 来提供附加含义，不带前导默认单位 (
1)。例如，使用{packet}、{error}、{fault}等。 - 除
1外的 Instrument 单位以及使用 注释 的单位应使用 UCUM 区分大小写的（“c/s”）变体指定。例如，“Cel”代表单位全称为“摄氏度”。 - Instrument 应使用非前缀单位（即
By而不是MiBy），除非有充分的技术原因不这样做。 - 当 Instrument 测量持续时间时，应使用秒（即
s）。
Instrument 类型
状态: 稳定
指标语义约定规范是使用同步 Instrument 类型（如 Counter 或 UpDownCounter）的名称编写的。但是，符合规范的实现可以使用异步等效项，如 Asynchronous Counter 或 Asynchronous UpDownCounter。实现选择同步类型还是异步等效项被视为实现细节。这两种选择都符合本规范。
一致的 UpDownCounter 时间序列
状态: 开发中
在记录 UpDownCounter 指标时，用于记录增量的相同属性值也应被用于记录任何相关的减量，否则这些增量和减量将成为不同的时间序列。
例如，如果您正在使用 UpDownCounter 跟踪 active_requests，并且每次请求开始时增加它，每次请求结束时减少它，那么在请求开始时增加计数器时不可用的任何属性都不应在请求结束时减少计数器时使用。