Metrics 语义约定

The following semantic conventions surrounding metrics are defined:

除了metrics和 traces 的语义约定之外，OpenTelemetry还定义了使用其自己的 资源语义约定(待翻译)对 资源(待翻译) 进行总体化的概念

一般准则

Metric的名称和标签存在于一个独立的领域和一个独立的层次结构中. Metric的名称和标签必须要考虑现有的领域内的名称。 在新增Metric的名称与标签时，必须考虑现有技术的框架/仓库。

关联metrics应根据其用法嵌套在层次结构中。为常见的metric类别定义顶层层次结构： 用于系统metrics，例如CPU和网络；适用于应用运行时，例如GC内部。

metrics定义了具有层次结构的命名空间。支持OpenTelemetry工件可以为某些类别的指标定义指标结构和层次结构，这些可以帮助您在创建将来的指标时做出决策。 OpenTelemetry组件支持定义某些metric的结构和层次结构，这些可以帮助您在后续再次创建metric时做出更好的决策。

通用标签应统一命名。这有助于发现并消除相似标签与metrics名称的歧义。

正如Prometheus所建议的那样，在对所有的metric命名时都是需要具有含义的。 “METRIC 与标签命名” as

应当避免语义歧义。使用带有前缀的度量名称时，类似的度量标准在现有的度量标准中具有显著的不同。 例如，每个垃圾回收器在运行时都会存在略微不同的策略和执行方式，对于GC使用一个单一的metric名称集合， 不按照时间划分，会导致用户在使用时对于理解其metric含义时的混乱（例如，优先使用runtime.java.gc*而不是runtime.gc.*）。 某些操作系统的指标也是同样的模凌两可。

单位

常规metrics或将其单位包含在OpenTelemetry元数据metric.WithUnit中的metrics（例如go语言），不应该在度量名称中包含这些单位。 当单位为metrics名称提供其他含义时，可以包含单位。最重要的是，metrics必须是可以理解和使用的。

使用OpenMetrics展示格式构建在OpenTelemetry和系统之间可互相操作的组件时，请使用 《 OpenMetrics指南》。

多元化

度量名称不应被复数，除非所记录的值表示 可计数. 的离散实例 。通常，仅当所讨论指标的单位为非单位（如faults或operations）时，名称才应该复数。

例子：

  • system.filesystem.utilization，，http.server.duration和system.cpu.time ，即使记录了很多数据点也不应复数。
  • system.paging.faults，system.disk.operations和system.network.packets 应该被复数，即使仅记录一个数据点也是如此。

一般 Metric 语义约定

以下语义约定旨在保持命名的一致性。它们为本规范中的大多数情况提供了指南，对于本文档中未明确定义的其他工具，应遵循这些指南。

instrument 命名

  • 极限量 - 一种测量常量极限的instrument，已知总量的instrument``entity.limit。例如，system.memory.limit 用于系统上的内存总量。

  • 已使用量 - 一种用来衡量已知总数的（极限量) 数量中所已经使用数量的工具entity.usage。 例如， system.memory.usage带有标签state = used | cached | free | …的每种状态下的内存量。 在适当的情况下 ，所有标签值的使用总和应等于极限量。

    测量无限制消耗的资源量与已使用量有所区别。

  • 使用率 - instrument``entity.utilization用于测量已使用量的除以极限量的使用率。 例如，system.memory.utilization对于正在使用的内存部分的使用率，值在[0,1]的范围内。

  • 时间 - 一种测量时间流逝的工具 entity.time。例如，system.cpu.time带有label state = idle | user | system |…。 时间测量不一定是使用时间，并且可以小于或大于两次测量之间的实际使用时间。

    时间工具是使用指标的一种特殊情况，其中 极限量通常可以计算为所有标签值的时间总和。 可以使用metric事件时间戳自动导出时间工具的使用率。 例如，system.cpu.utilization定义为system.cpu.time测量值之差除以经过的时间。

  • io - 一种用于测量双向数据流的仪器应被调用entity.io并带有方向标签。例如，system.network.io。

  • 不符合以上描述的其他工具可以更自由地命名。例如system.paging.faults和system.network.packets。 无需在名称中指定单位，因为它们是在创建instrument时包含的，但是如果有歧义，可以添加单位。

instrument 单位

单位应遵循 UCUM（计量单位统一规范） (更多说明位于文档 #705(暂未翻译)).

  • 对于instruments的使用率测量，应当使用默认的1（the unity）。
  • 测量某物的整数的instruments应使用默认单位1（the unity）和 带花括号的注释来赋予其他含义。 例如{packets}，{errors}，{faults}等。