指标和标签命名

本文档中介绍的指标和标签约定并非使用 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() 应该是有意义的（虽然不一定有用）。如果它没有意义，请将数据拆分为多个指标。例如，在一个指标中包含各种队列的容量是好的，而将队列的容量与队列中当前元素的数量混合在一起则不好。

标签

使用标签来区分被测量事物的特征

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

不要将标签名称放在指标名称中，因为这会引入冗余，并且如果聚合掉相应的标签，则会造成混淆。

基本单位

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

本文档是开源的。请提交 issue 或 pull request 以帮助改进它。