指标与标签命名
本文档中呈现的指标单位和标签的规范并非使用 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
(用于提供运行二进制文件的元数据的伪指标)data_pipeline_last_record_processed_timestamp_seconds
(用于跟踪数据处理管道中最新记录处理时间的时间戳)
- 应代表所有标签维度下测量的同一逻辑事物。
- 请求延迟
- 数据传输字节数
- 资源使用瞬时百分比
经验法则:对于给定的指标,通过所有维度进行求和或平均的结果通常是有意义的(尽管这不一定有用)。如果计算结果没有意义,则应将数据拆分为多个指标。例如,将不同队列的容量放在一个指标中是一个不错的做法,而将队列容量与队列当前元素数量混在一起则是不好的做法。
标签
使用标签来区分所测量事物的特征:
api_http_requests_total
- 区分请求类型:operation="create|update|delete"
api_request_duration_seconds
- 区分请求阶段:stage="extract|transform|load"
不要将标签名包含在指标名称中,因为这会引入冗余并导致混淆(尤其是当相应的标签需要被聚合时)。
警告:请记住,每一种独特的键值标签组合代表一个新的时间序列,这可能会极大地增加存储的数据量。不要使用标签来存储大基数(许多不同的标签值)的维度,如用户ID、电子邮件地址或其他未定义范围的值。
基本单位
Prometheus 没有硬编码任何单位。为了提高兼容性,你应该使用基本单位。以下是一些指标族及其基本单位的列表。注意,该列表并不详尽。
族 | 基本单位 | 注释 |
---|---|---|
时间 | seconds | |
温度 | celsius | 摄氏度因实际原因而更受欢迎;开尔文在特殊情况下(如色温或温度必须绝对时)也是可以接受的基本单位。 |
长度 | meters | |
字节 | bytes | |
位(Bigs) | bytes | 为了避免混淆不同的指标单位,即使位通常看起来更常见,也应该使用字节。 |
百分比 | ratio | 值位于0-1之间(而非0-100)。比率仅用于像disk_usage_ratio 这样的名字后缀。通常的指标名称遵循A_per_B 的模式。 |
电压 | volts | |
电流 | amperes | |
能量 | joules | |
功率 | 推荐暴露单位为焦耳的 Counter,然后使用rate(joules[5m]) 就可给出以瓦特进行计量功率。 | |
质量 | grams | 克相较于千克更受欢迎,其避免与 千 前缀相关的问题。 |
该文档基于 Prometheus 官方文档翻译而成。