请参与 Prometheus 用户调研(2026 年 3 月版) ,帮助社区确定未来开发工作的优先级!

数据模型

Prometheus 基础从根本上将所有数据存储为 时间序列:属于相同指标和相同标签维度集合的时间戳数据流。除了存储的时间序列外,Prometheus 还可能在查询结果中生成临时的派生时间序列。

指标名称和标签

每个时间序列由其指标名称和可选的键值对(称为标签)唯一标识。

指标名称

  • 指标名称应该 (SHOULD) 指定被测系统的通用功能(例如,http_requests_total - 接收到的 HTTP 请求总数)。
  • 指标名称可以使用任何 UTF-8 字符。
  • 为了获得最佳体验和兼容性,指标名称应该 (SHOULD) 符合正则表达式 [a-zA-Z_:][a-zA-Z0-9_:]*(参见下方的警告)。超出此范围的指标名称(例如在 PromQL 中使用时)将需要引号(参见 UTF-8 指南)。
注意冒号 (':') 保留给用户定义的记录规则。Exporter 或直接埋点不应该 (SHOULD NOT) 使用它们。

指标标签

标签让您可以捕获同一指标名称下的不同实例。例如:所有使用 POST 方法访问 /api/tracks 处理程序的 HTTP 请求。我们将其称为 Prometheus 的“多维数据模型”。查询语言允许基于这些维度进行过滤和聚合。任何标签值的更改,包括添加或删除标签,都会创建一个新的时间序列。

  • 标签名称可以使用任何 UTF-8 字符。
  • __(两个下划线)开头的标签名称必须 (MUST) 保留供 Prometheus 内部使用。
  • 为了获得最佳体验和兼容性,标签名称应该 (SHOULD) 符合正则表达式 [a-zA-Z_][a-zA-Z0-9_]*(参见下方的警告)。超出此正则范围的标签名称(例如在 PromQL 中使用时)将需要引号(参见 UTF-8 指南)。
  • 标签值可以包含任何 UTF-8 字符。
  • 标签值为空的标签被视为与不存在的标签等效。

警告:Prometheus v3.0.0 最近才添加了对指标和标签名称的 UTF-8 支持。更广泛的生态系统(下游兼容 PromQL 的项目和供应商、工具、第三方埋点、采集器等)采用新的引用机制和放宽的验证规则可能需要一些时间。为了获得最佳兼容性,建议遵循推荐的(“应该/SHOULD”)字符集。

信息:另请参阅指标和标签命名的最佳实践

样本

样本构成了实际的时间序列数据。每个样本由以下部分组成:

符号表示法

给定指标名称和一组标签,时间序列通常使用以下符号进行标识:

<metric name>{<label name>="<label value>", ...}

例如,一个指标名称为 api_http_requests_total 且标签为 method="POST"handler="/messages" 的时间序列可以写成这样:

api_http_requests_total{method="POST", handler="/messages"}

这与 OpenTSDB  使用的符号相同。

对于包含推荐字符集之外的 UTF-8 字符的名称,必须使用以下符号加引号:

{"<metric name>", <label name>="<label value>", ...}

由于指标名称在内部表示为带有特殊标签名称(__name__="<指标名称>")的标签对,因此也可以使用以下符号:

{__name__="<metric name>", <label name>="<label value>", ...}

本页内容