指标和标签命名

本文档中提出的指标和标签规范并非使用 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 中显示关于指标类型和单位的丰富信息（自动补全、覆盖层、弹出框）。不幸的是，交互式的即席查询并不是用户与指标交互的唯一方式。指标消费生态系统非常庞大。大部分消费以各种可观测性工具的简单 YAML 配置形式出现，例如告警、记录、自动扩缩容、仪表盘、分析、处理等。特别是在监控/SRE 事件实践中，查看简单 YAML 中的 PromQL 表达式并理解你所使用的底层指标类型和单位是至关重要的。
• 指标冲突：随着应用的增长和指标随时间的推移而变化，在某些情况下，如果指标名称中缺乏单位和类型信息，会导致某些序列发生冲突（例如，用于秒和毫秒的 process_cpu）。

标签

使用标签来区分测量对象的特性

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

不要将标签名称放入指标名称中，因为这会引入冗余，如果相应的标签被聚合移除，会造成混淆。

注意请记住，键值标签对的每一个唯一组合都代表一个新的时间序列，这会显著增加存储的数据量。不要使用标签存储高基数维度（即拥有大量不同标签值的维度），例如用户 ID、电子邮件地址或其他无界的集合值。

基本单位

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

分类	基本单位	备注
时间	seconds（秒）
温度	celsius（摄氏度）	出于实际原因，celsius 优于 kelvin。在特殊情况下（如色温或必须使用绝对温度时），kelvin 作为基本单位是可以接受的。
长度	meters（米）
字节	bytes（字节）
比特	bytes（字节）	为了避免混淆不同指标，请始终使用 bytes，即使在看起来更常用 bits 的地方也是如此。
百分比	ratio（比例）	值为 0–1（而不是 0–100）。ratio 仅用作类似 disk_usage_ratio 的名称后缀。通常的指标名称遵循 A_per_B 的模式。
电压	volts（伏特）
电流	amperes（安培）
能量	joules（焦耳）
功率		建议导出焦耳的计数器，然后 rate(joules[5m]) 会给出以瓦特为单位的功率。
质量	grams（克）	grams 优于 kilograms，以避免 kilo 前缀带来的问题。