指标和标签命名

本文档中提出的指标和标签约定在使用 Prometheus 时并非强制要求，但可以作为风格指南和最佳实践的集合。各个组织可能希望以不同的方式处理其中一些实践，例如命名约定。

指标名称

指标名称...

  • ...必须符合 数据模型 中关于有效字符的要求。
  • ...应具有一个与其所属领域相关的（单词）应用前缀。客户端库有时将此前缀称为 namespace。对于特定于应用的指标，前缀通常是应用本身的名称。然而，有时指标更通用，例如由客户端库导出的标准化指标。示例
    • prometheus_notifications_total (特定于 Prometheus 服务器)
    • process_cpu_seconds_total (由许多客户端库导出)
    • http_request_duration_seconds (针对所有 HTTP 请求)
  • ...必须具有单一单位（即不要将秒与毫秒或秒与字节混用）。
  • ...应使用基本单位（例如秒、字节、米，而不是毫秒、兆字节、千米）。请参阅下方的基本单位列表。
  • ...应具有描述单位的后缀，使用复数形式。请注意，累积计数除了单位（如果适用）之外，还具有 total 后缀。另请注意，这适用于狭义的单位（如下表中所示的单位），但不适用于一般的可计数事物。例如，connections 或 notifications 不被视为此规则下的单位，无需放在指标名称的末尾。（另请参阅下一段中的示例。）
    • http_request_duration_seconds
    • node_memory_usage_bytes
    • http_requests_total (用于无单位的累积计数)
    • process_cpu_seconds_total (用于带有单位的累积计数)
    • foobar_build_info (用于提供运行二进制文件元数据的伪指标)
    • data_pipeline_last_record_processed_timestamp_seconds (用于跟踪数据处理管道中最新记录处理时间的 时间戳)
  • ...可以按照一种方式排列其名称组件，以便在按字典顺序排序指标名称列表时方便分组，前提是遵循所有其他规则。以下示例将共同的名称组件放在前面，以便所有相关指标可以排序在一起
    • prometheus_tsdb_head_truncations_closed_total
    • prometheus_tsdb_head_truncations_established_total
    • prometheus_tsdb_head_truncations_failed_total
    • prometheus_tsdb_head_truncations_total
      以下示例也有效，但遵循不同的权衡。它们单独更容易阅读，但像 prometheus_tsdb_head_series 这样不相关的指标可能会被排序到中间。
    • prometheus_tsdb_head_closed_truncations_total
    • prometheus_tsdb_head_established_truncations_total
    • prometheus_tsdb_head_failed_truncations_total
    • prometheus_tsdb_head_truncations_total
  • ...应在所有标签维度上表示相同的逻辑测量对象。
    • 请求持续时间
    • 数据传输字节数
    • 瞬时资源使用百分比

根据经验法则，对给定指标的所有维度进行 sum() 或 avg() 计算应具有意义（尽管不一定有用）。如果它没有意义，则将数据拆分为多个指标。例如，将各种队列的容量放在一个指标中是好的，而将队列的容量与队列中当前元素数量混在一起则不是。

为什么要在指标名称中包含单位和类型后缀？

一些指标命名约定（例如 OpenTelemetry）不推荐甚至不允许在指标名称中包含关于指标单位和类型的信息。一个常见的论点是这些信息已经在其他地方（例如模式、元数据、其他标签等）定义了。

Prometheus 强烈建议在指标名称中包含单位和类型，即使您在其他地方存储了这些信息，原因如下：

  • 指标消费的可靠性和用户体验：当与现代 UI 交互并在 PromQL 中使用此类指标时，可以显示关于指标类型和单位的丰富信息（自动补全、覆盖层、弹出窗口）。不幸的是，在强大的 UI 中进行交互式、即时查询并不是用户与指标交互的唯一方式。指标消费生态系统非常庞大。大部分消费以各种可观测性工具（如报警、记录、自动伸缩、仪表盘、分析、处理等）的纯 YAML 配置形式出现。尤其在监控/SRE 事件处理实践中，查看纯 YAML 中的 PromQL 表达式并理解您正在使用的底层指标类型和单位是至关重要的。
  • 指标冲突：随着采用率的增长和指标随时间的变化，在某些情况下，指标名称中缺乏单位和类型信息会导致某些时间序列冲突（例如用于秒和毫秒的 process_cpu）。

标签

使用标签来区分被测量事物的特征

  • api_http_requests_total - 区分请求类型：operation="create|update|delete"
  • api_request_duration_seconds - 区分请求阶段：stage="extract|transform|load"

不要将标签名称放在指标名称中，这会引入冗余，并且如果在聚合时相应的标签被移除，会导致混淆。

注意：请记住，每个唯一的键值标签对组合代表一个新的时间序列，这会极大地增加存储的数据量。不要使用标签来存储高基数（许多不同的标签值）维度，例如用户 ID、电子邮件地址或其他无限制的值集合。

基本单位

Prometheus 没有硬编码任何单位。为了更好的兼容性，应使用基本单位。以下列出了一些指标族及其基本单位。该列表并非详尽无遗。

族 基本单位 备注
时间 秒
温度 摄氏度 出于实际原因，摄氏度优先于开尔文。在特殊情况下，如色温或温度必须为绝对值时，开尔文可以作为基本单位。
长度 米
字节 字节
比特 字节 为避免混用不同指标引起混淆，即使 比特 看起来更常见，也始终使用 字节。
百分比 比率 值范围是 0-1（而不是 0-100）。ratio 仅用作诸如 disk_usage_ratio 等名称的后缀。通常的指标名称遵循 A_per_B 模式。
电压 伏特
电流 安培
能量 焦耳
功率 优先导出焦耳计数器，然后 rate(joules[5m]) 会得到以瓦特为单位的功率。
质量 克 克优先于千克，以避免前缀 kilo 带来的问题。

这篇文档是开源的。请通过提交 issue 或 pull request 帮助改进它。