本文档中提出的指标和标签约定在使用 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 强烈建议在指标名称中包含单位和类型,即使您在其他地方存储了这些信息,原因如下:
process_cpu
)。使用标签来区分被测量事物的特征
api_http_requests_total
- 区分请求类型:operation="create|update|delete"
api_request_duration_seconds
- 区分请求阶段:stage="extract|transform|load"
不要将标签名称放在指标名称中,这会引入冗余,并且如果在聚合时相应的标签被移除,会导致混淆。
Prometheus 没有硬编码任何单位。为了更好的兼容性,应使用基本单位。以下列出了一些指标族及其基本单位。该列表并非详尽无遗。
族 | 基本单位 | 备注 |
---|---|---|
时间 | 秒 | |
温度 | 摄氏度 | 出于实际原因,摄氏度优先于开尔文。在特殊情况下,如色温或温度必须为绝对值时,开尔文可以作为基本单位。 |
长度 | 米 | |
字节 | 字节 | |
比特 | 字节 | 为避免混用不同指标引起混淆,即使 比特 看起来更常见,也始终使用 字节。 |
百分比 | 比率 | 值范围是 0-1(而不是 0-100)。ratio 仅用作诸如 disk_usage_ratio 等名称的后缀。通常的指标名称遵循 A_per_B 模式。 |
电压 | 伏特 | |
电流 | 安培 | |
能量 | 焦耳 | |
功率 | 优先导出焦耳计数器,然后 rate(joules[5m]) 会得到以瓦特为单位的功率。 |
|
质量 | 克 | 克优先于千克,以避免前缀 kilo 带来的问题。 |
这篇文档是开源的。请通过提交 issue 或 pull request 帮助改进它。