指标和标签命名

本文档中介绍的指标和标签约定不是使用 Prometheus 的必要条件，但可以作为风格指南和最佳实践的集合。各个组织可能希望以不同的方式处理其中一些实践，例如命名约定。

指标名称

指标名称...

  • ...必须符合数据模型中关于有效字符的规定。
  • ...应该有一个（单字）应用程序前缀，该前缀与指标所属的域相关。前缀有时被客户端库称为命名空间。对于特定于应用程序的指标，前缀通常是应用程序名称本身。然而，有时指标更通用，例如客户端库导出的标准化指标。示例
    • 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() 应该是有意义的（尽管不一定有用）。如果它没有意义，请将数据拆分为多个指标。例如，在一个指标中包含各种队列的容量是好的，而将队列的容量与队列中当前元素的数量混合在一起则不好。

标签

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

  • 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 来帮助改进它。