指标与标签命名

本文档中介绍的指标和标签约定并非使用 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）不建议甚至不允许在指标名称中包含有关指标单位和类型的信息。一个常见的论点是这些信息已经在其他地方定义了（例如 schema、元数据、其他标签等）。

Prometheus 强烈建议在指标名称中包含单位和类型，即使你在其他地方存储了这些信息，原因如下：

指标使用的可靠性和用户体验：在使用现代 UI 中的 PromQL 处理此类指标时，可以显示关于指标类型和单位的丰富信息（自动补全、悬浮提示、弹出窗口）。遗憾的是，在功能强大的 UI 中进行交互式临时查询并非用户与指标交互的唯一方式。指标消费生态系统非常庞大。大部分消费以纯 YAML 配置的形式存在，用于各种可观测性工具，如告警、记录规则、自动扩缩容、仪表盘、分析、处理等。在监控/SRE 事件处理实践中，能够查看纯 YAML 中的 PromQL 表达式并理解所使用的底层指标类型和单位是至关重要的。
指标冲突：随着采用率的增长和指标随时间变化，如果指标名称中缺少单位和类型信息，可能会导致某些时间序列发生冲突（例如 process_cpu 同时用于秒和毫秒）。

基本单位

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

族	基本单位	备注
时间	seconds
温度	celsius	出于实际原因，celsius 优于 kelvin。在色温或需要绝对温度等特殊情况下，kelvin 可以作为基本单位。
长度	meters
字节	bytes
比特	bytes	为避免混合不同指标时产生混淆，即使 bits 看起来更常见，也请始终使用 bytes。
百分比	ratio	值为 0-1（而非 0-100）。`ratio` 仅作为 `disk_usage_ratio` 等名称的后缀使用。通常的指标名称遵循 `A_per_B` 模式。
电压	volts
电流	amperes
能量	joules
功率		建议导出焦耳计数器，然后使用 `rate(joules[5m])` 即可获得以瓦特为单位的功率。
质量	grams	grams 优于 kilograms，以避免 kilo 前缀带来的问题。