指标和标签命名

本文档中介绍的指标和标签约定并非使用 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 没有任何硬编码的单位。为了更好的兼容性，应该使用基本单位。以下列出了一些指标族及其基本单位。该列表并不详尽。

族	基本单位	备注
时间	秒 (seconds)
温度	摄氏度 (celsius)	出于实际原因，celsius 优于 kelvin。在特殊情况下，如色温或温度必须是绝对值时，kelvin 作为基本单位是可接受的。
长度	米 (meters)
字节	字节 (bytes)
比特	字节 (bytes)	为避免混合不同指标时产生混淆，请始终使用 bytes，即使在 bits 看起来更常见的情况下也是如此。
百分比	比率 (ratio)	值为 0–1（而不是 0–100）。ratio 仅用作像 disk_usage_ratio 这样的名称的后缀。通常的指标名称遵循 A_per_B 的模式。
电压	伏特 (volts)
电流	安培 (amperes)
能量	焦耳 (joules)
功率		优先导出焦耳的计数器，然后 rate(joules[5m]) 就可以得到以瓦特为单位的功率。
质量	克 (grams)	为避免 kilo 前缀带来的问题，grams 优于 kilograms。