指标暴露格式

Prometheus 使用基于文本的格式来暴露指标。有许多客户端库可以为你实现这种格式。如果你使用的语言没有客户端库，你也可以自行编写。

基于文本的格式

从 Prometheus 版本 2.0 起，所有向 Prometheus 暴露指标的过程都要使用基于文本的格式。在本节中，你将找到有关此格式的一些基础信息，以及其更详细的解析细节。

基础信息

属性	描述
起源	2014年4月
支持版本	Prometheus 版本 `>=0.4.0`
传输方式	HTTP
编码	UTF-8, `\n` 行结束符
HTTP `Content-Type`	`text/plain; version=0.0.4`（如果缺少 `version` 值，则默认取最新的文本格式版本。）
可选 HTTP `Content-Encoding`	`gzip`
优点	+ 易读 + 构建简单，尤其是在简洁的情况下（无需嵌套） + 逐行可读（除了类型提示和文档字符串之外）
局限性	+ 冗长 + 类型和文档字符串不是语法的一部分，这意味着几乎没有或不存在指标约定验证 + 解析成本
支持的指标原语	+ Counter + Gauge + Histogram + Summary + Untyped（未指定类型）

文本格式细节

Prometheus 的基于文本的格式是行导向的。行由换行符 (\n) 分隔。最后一行必须以换行符结尾。空行将被忽略。

行格式

在一行内，可以使用任意数量的空白字符和/或制表符来分隔 tokens（如果它们会合并，则至少需要一个分隔符）。行首尾的空白字符将被忽略。

注释、帮助文本和类型信息

带有 # 作为第一个非空白字符的行是注释。它们会被忽略，除非 # 后的第一个 token 是 HELP 或 TYPE。这些行按照以下方式处理：如果 token 是 HELP，则至少需要一个更多 token，即指标名称。所有剩余的 token 被视为该指标名称的文档字符串。HELP 行可以包含任何 UTF-8 字符（在指标名称之后），但反斜杠 (\)、双引号 (\") 和换行符 (\n) 需要分别转义为 \\、\" 和 \n。对于任何给定的指标名称，只能存在一个 HELP 行。

如果 token 是 TYPE，则需要恰好两个额外的 token。第一个是指标名称，第二个是 counter、gauge、histogram、summary 或 untyped 中的一个，定义了该名称指标的类型。对于任何给定的指标名称，只能存在一个 TYPE 行。对于给定指标名称的 TYPE 行必须出现在第一次报告该指标名称的样本之前。如果没有为指标名称提供 TYPE 行，类型将设置为 untyped。

其余的行使用以下语法描述样本（每行一个）：

metric_name [
  "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
] value [ timestamp ]

在样本的语法中：

metric_name 和 label_name 必须遵循 Prometheus 表达式语言的一般限制。
label_value 可以是任何 UTF-8 字符序列，但需要位于metric_name之后，反斜杠 (\)、双引号 (\") 和换行符 (\n) 需要分别转义为 \\、\" 和 \n。
value 是由 Go 的 ParseFloat() 函数所需的浮点数表示。除了标准数值值外，NaN、+Inf 和 -Inf 也是有效值，分别代表非数字、正无穷大和负无穷大。
timestamp 是一个 int64（自 1970 年 1 月 1 日 00:00:00 UTC 以来的毫秒数，不包括闰秒），由 Go 的 ParseInt() 函数所需表示。

分组和排序

对于给定的指标的所有行必须作为一个单个组提供，其中可选的HELP和TYPE行首先出现（无特定顺序）。此外，在重复的指标暴露中保持可重现的排序是不错的选择但这并不是必需的，也就是说，如果运算成本过高，则不要排序。

每一行都必须具有唯一的组合的指标名称和标签，否则无法定义指标的消费行为。

Histogram 和 Summary

Histogram 和 Summary 类型在文本格式中难以表示。以下约定适用：

命名为x的 Histogram 或 Summary 的样本总和作为名为x_sum的单独样本给出。
命名为x的 Histogram 或 Summary 的样本计数作为名为x_count的单独样本给出。
命名为x的 Summary 的每个分位数作为同名x的单独样本行给出，并带有标签{quantile="y"}。
命名为x的 Histogram 的每个桶计数作为同名x_bucket的单独样本行给出，带有标签{le="y"}（其中y是桶的上界）。
必须有一个桶{le="+Inf"}的 Histogram。它的值必须与x_count的值相同。
Histogram 的桶和 Summary 的分位数必须按照它们的标签值（分别对于le或quantile标签）的递增数值顺序排列。

文本格式示例

下面是包括注释、HELP和TYPE表达式、Histogram、Summary、字符转义示例和其他功能的 Prometheus 指标暴露的完整示例。

# HELP http_requests_total The total number of HTTP requests.
# TYPE http_requests_total counter
http_requests_total{method="post",code="200"} 1027 1395066363000
http_requests_total{method="post",code="400"}    3 1395066363000

# Escaping in label values:
msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9

# Minimalistic line:
metric_without_timestamp_and_labels 12.47

# A weird metric from before the epoch:
something_weird{problem="division by zero"} +Inf -3982045

# A histogram, which has a pretty complex representation in the text format:
# HELP http_request_duration_seconds A histogram of the request duration.
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 24054
http_request_duration_seconds_bucket{le="0.1"} 33444
http_request_duration_seconds_bucket{le="0.2"} 100392
http_request_duration_seconds_bucket{le="0.5"} 129389
http_request_duration_seconds_bucket{le="1"} 133988
http_request_duration_seconds_bucket{le="+Inf"} 144320
http_request_duration_seconds_sum 53423
http_request_duration_seconds_count 144320

# Finally a summary, which has a complex representation, too:
# HELP rpc_duration_seconds A summary of the RPC duration in seconds.
# TYPE rpc_duration_seconds summary
rpc_duration_seconds{quantile="0.01"} 3102
rpc_duration_seconds{quantile="0.05"} 3272
rpc_duration_seconds{quantile="0.5"} 4773
rpc_duration_seconds{quantile="0.9"} 9001
rpc_duration_seconds{quantile="0.99"} 76656
rpc_duration_seconds_sum 1.7560473e+07
rpc_duration_seconds_count 2693

OpenMetrics 文本格式

OpenMetrics 是在 Prometheus 文本格式基础上构建的一种标准化指标数据传输格式的尝试。自至少 v2.23.0 版本起，就可以通过此格式来抓取目标，并且还可以用于聚合指标。

示例（实验性）

使用 OpenMetrics 格式允许展示和查询示例。示例提供了一个与指标集合相关的特定时刻快照，对于通常被汇总的 MetricFamily 来说。此外，它们可能还附带有跟踪ID，与追踪系统一起使用时，可以提供更多关于具体服务的详细信息。

要启用这个实验性功能，你必须至少使用版本v2.26.0，并在参数中添加 --enable-feature=exemplar-storage。

Protobuf 格式

Prometheus 的早期版本支持基于 Protocol Buffers（即 Protobuf）的展示格式，除了当前的文本格式。随着 Prometheus 2.0 的发布，Protobuf 格式被标记为废弃，并停止从该格式接收指标数据样本。

然而，Prometheus 添加了实验性功能，其中考虑了 Protobuf 格式作为数据传输的可行方案，这使得 Prometheus 能够再次接受 Protocol Buffers。

以下是启用实验性功能列表，一旦启用，将配置 Prometheus 优先采用 Protobuf 格式：

特性标志	引入版本
native-histograms	2.40.0
created-timestamp-zero-ingestion	2.50.0

历史版本

有关历史格式版本的详细信息，请参阅遗留的客户端数据暴露格式文档。

当前版本的原生 Protobuf 格式（包括最近针对原生 Histogram 的扩展）在 prometheus/client_model 仓库中进行维护。

该文档基于 Prometheus 官方文档翻译而成。