Prometheus指标和标签命名

完整译文请访问：http://www.coderdocument.com/docs/prometheus/v2.14/best_practices/metric_and_label_naming.html。

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

指标名称

一个指标名称：

• 必须符合有效字符的数据模型。
• 应该具有与指标所属域相关的（单个词汇）应用程序前缀。前缀有时被客户端库称为命名空间。对于特定于应用程序的指标，前缀通常是应用程序名称本身。然而，有时候指标更通用，比如客户端库导出的标准化指标。例如：
  • prometheus_notifications_total （针对Prometheus 服务器）
  • process_cpu_seconds_total （由客户端库导出）
  • http_request_duration_seconds （用于所有HTTP请求）
• 必须有一个单一的单位（即，不要把秒与毫秒，或秒与字节混用）。
• 应该使用基本单位（如秒、字节、米——而不是毫秒、兆字节、公里）。参见下面的基本单位列表。
• 应以复数形式用后缀来描述单位。请注意，累计计数以total作为后缀，附加在单位之后。
  • http_request_duration_seconds
  • node_memory_usage_bytes
  • http_requests_total （用于无单位的累计计数）
  • process_cpu_seconds_total （用于有单位的累计计数）
  • foobar_build_info （用于提供关于正在运行的二进制文件的元数据的伪指标）
• 应该在所有的标签维度中表示相同的监控逻辑。
  • 请求持久时长
  • 传输的数据字节数
  • 瞬时资源使用百分比

根据经验，指定指标的所有维度上的sum()或avg()都应该是有意义的（尽管不一定有用）。如果没有意义，则应该将数据分解为多个指标。例如，在一个指标中拥有各种队列的容量是可行的，而将队列的容量与队列中当前元素的数量混合则不合适。

标签

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

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

不要将标签名称放在指标名称中，因为这是冗余的，并且如果各自的标签被聚合掉，将导致混淆。

警告：请记住，每个键-值标签对的唯一组合都代表一个新的时间序列，它会显著增加存储的数据量。不要使用标签来存储具有高基数（许多不同的标签值）的维度，例如用户ID、电子邮件地址或其他极大值。

基本单位

普罗米修斯没有任何硬编码的单位。为了更好的兼容性，应该使用基本单元。下面列出了一些带有基本单位的指标家族。但这个清单并不详尽。

家族	基本单位	备注
Time	秒
Temperature	摄氏度	由于实际原因，摄氏温度比开尔文温度更受欢迎。
Length	米
Bytes	字节
Bits	字节	为了避免不同指标混淆，总是使用字节，即使在比特位更常见的场景也是如此。
Percent	比率	值从0 - 1 ，而不是从0 - 100。 ratio仅用作disk_usage_ratio等名称的后缀。通常的指标名称遵循模式A_per_B。
Voltage	伏特
Electric current	安培
Energy	焦耳
Mass	克	“克”是首选而不是“千克”，以避免kilo前缀的问题。

 

完整译文请访问：http://www.coderdocument.com/docs/prometheus/v2.14/best_practices/metric_and_label_naming.html。