[Prometheus最佳实践]指标和标签命名

在使用 Prometheus 时，文档中提供的指标和标签约定并不是必需的，但可以作为样式指南和最佳实践的集合。不同的组织可以对某些实践方法（例如命名约定）采取不同的方式。

指标名称

指标名称应该符合以下特征：

• 必须符合数据模型中有效字符的要求。

• 应该使用与指标所属领域相关的（单词）应用程序前缀。前缀有时被客户端库称为命名空间。对于特定应用程序的指标，前缀通常是应用程序名称本身。然而，有时指标更通用，例如由客户端库导出的标准化指标。例子：

  • prometheus_notifications_total（特定于 Prometheus 服务器）
  • process_cpu_seconds_total（由许多客户端库导出）
  • http_request_duration_seconds（用于所有 HTTP 请求）
• 必须具有单个单位（即不要将秒[seconds]与毫秒[milliseconds]混用，或将秒[seconds]与字节[bytes]混用）。
• 应该使用基本单位（例如秒[seconds]、字节[bytes]、米[meters] - 而不是毫秒[milliseconds]、兆字节[megabytes]、千米[kilometers]）。最后有一个基本单位的列表。

• 应该有一个以复数形式描述单位的后缀。注意，counter 计数器在单位适用的情况下，除了单位外还有 total 作为后缀。

  • http_request_duration_seconds
  • node_memory_usage_bytes
  • http_requests_total（无单位的 counter 计数器）
  • process_cpu_seconds_total（带有单位的 counter 计数器）
  • foobar_build_info（提供有关运行二进制文件的元数据的伪指标）
  • data_pipeline_last_record_processed_timestamp_seconds（用于跟踪数据处理流水线中最新记录处理时间的时间戳）

• 应该在所有标签维度上表示相同的逻辑测量对象。

  • 请求持续时间
  • 数据传输字节数
  • 瞬时资源使用率的百分比

作为一个经验法则，给定指标的所有维度的 sum() 或 avg() 应该是有意义的（不管对你有没有用）。如果没有意义，则应该将数据拆分成多个指标。例如，在一个指标中混合队列的容量和队列中当前元素数量是不好的，而将各种队列的容量放在一个指标中是可以的。

标签

使用标签来区分被测量对象的特性：

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

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

注意：每个唯一的键-值标签对的组合表示一个新的时间序列，这可能会大大增加存储的数据量。不要使用具有高基数（不能枚举的，许多不同标签值）的标签来存储维度，例如用户ID、电子邮件地址或其他无边界的集合。

基本单位

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

家族	基本单位	备注
Time	seconds
Temperature	celsius	摄氏度出于实际原因而被优先选择，开尔文（绝对温度）则保留给需要绝对温度值或精确温度差的专门情况使用
Length	meters
Bytes	bytes
Bits	bytes	为了避免混淆不同度量标准，即使比特看起来更常见，也应始终使用字节。
Percent	ratio	数值范围为0-1（而不是0-100）。ratio只用作像disk_usage_ratio这样的名称的后缀。通常的度量标准名称遵循A_per_B的模式。
Voltage	volts
Electric current	amperes
Energy	joules
Power		建议导出以焦耳计量的计数器(counter)，这样使用 rate(joules[5m])可以得到以瓦特为单位的功率。
Mass	grams	为了避免使用千（kilo）前缀时可能出现的问题，建议使用克而不是千克。

伪指标（pseudo-metric）在Prometheus中是指提供关于运行二进制文件的元数据或其他附加信息的指标。它们通常不参与度量或监控实际的业务指标，而是用于提供有关系统或应用程序状态的描述性信息。
例如，"foobar_build_info" 可以是一个伪指标，它提供有关正在运行的二进制文件的版本号、构建时间、构建者等信息。这些信息对于运行时的调试、故障排查和版本追踪非常有用，但不直接与业务指标相关。
伪指标可以通过在指标命名中使用 "_info" 或其他类似的后缀来区分。这样可以与其他真实的度量指标进行区分，并且在查询和可视化时可以单独处理。