指标和标签命名
本文档中介绍的指标和标签约定并非使用 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]) 将为您提供以瓦特计量的功率。 | |
质量 | 克 | 首选克而非千克,以避免前缀千导致的问题。 |