暴露格式

指标可以使用简单的基于文本的暴露格式向 Prometheus 暴露。有各种实现了这种格式的客户端库。如果您偏好的语言没有客户端库,您可以创建自己的

基于文本的格式

自 Prometheus 2.0 版起,所有向 Prometheus 暴露指标的进程都需要使用基于文本的格式。在本节中,您可以找到关于此格式的一些基本信息,以及更详细的格式分解

基本信息

方面描述
初始版本2014 年 4 月
支持版本Prometheus 版本 >=0.4.0
传输HTTP
编码UTF-8,\n 换行符
HTTP Content-Typetext/plain; version=0.0.4 (缺少 version 值将导致回退到最新的文本格式版本。)
可选的 HTTP Content-Encodinggzip
优点
  • 人类可读
  • 易于组装,尤其适用于极简情况(无需嵌套)
  • 逐行可读(类型提示和文档字符串除外)
局限性
  • 冗长
  • 类型和文档字符串不是语法的组成部分,这意味着指标契约验证很少或不存在
  • 解析成本
支持的指标原语
  • Counter (计数器)
  • Gauge (仪表盘)
  • 直方图
  • 摘要
  • Untyped (无类型)

文本格式详情

Prometheus 的基于文本的格式是面向行的。行之间通过换行符(\n)分隔。最后一行必须以换行符结束。空行将被忽略。

行格式

在一行内,标记(token)可以用任意数量的空格和/或制表符分隔(如果它们会与前一个标记合并,则必须至少用一个分隔)。行首和行尾的空白字符将被忽略。

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

# 作为第一个非空白字符的行是注释。它们会被忽略,除非 # 后的第一个标记是 HELPTYPE。这些行将按如下方式处理:如果标记是 HELP,则预期至少还有一个标记,即指标名称。所有剩余的标记都被视为该指标名称的文档字符串。HELP 行可以包含任何 UTF-8 字符序列(在指标名称之后),但反斜杠和换行符必须分别转义为 \\\n。对于任何给定的指标名称,只能存在一个 HELP 行。

如果标记是 TYPE,则预期正好有两个标记。第一个是指标名称,第二个是 countergaugehistogramsummaryuntyped 之一,定义了该名称指标的类型。对于给定的指标名称,只能存在一个 TYPE 行。指标名称的 TYPE 行必须出现在报告该指标名称的第一个样本之前。如果一个指标名称没有 TYPE 行,其类型将被设置为 untyped

其余的行使用以下语法描述样本(每行一个)(EBNF

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

在样本语法中

  • metric_namelabel_name 遵循通常的 Prometheus 表达式语言限制。
  • label_value 可以是任何 UTF-8 字符序列,但反斜杠(\)、双引号(")和换行符(\n)必须分别转义为 \\\"\n
  • value 是一个浮点数,表示方式遵循 Go 语言的 ParseFloat() 函数的要求。除了标准的数值外,NaN+Inf-Inf 也是有效值,分别表示非数字、正无穷大和负无穷大。
  • timestamp 是一个 int64(自纪元以来的毫秒数,即 1970-01-01 00:00:00 UTC,不包括闰秒),表示方式遵循 Go 语言的 ParseInt() 函数的要求。

分组和排序

对于给定的指标,所有行必须作为一个单独的组提供,可选的 HELPTYPE 行在前(顺序不限)。除此之外,在重复的暴露中,可重现的排序是首选但非必需,即如果计算成本过高,则不要排序。

每一行必须有唯一的指标名称和标签组合。否则,摄取行为是未定义的。

直方图和摘要

histogramsummary 类型在文本格式中表示起来比较复杂。适用以下约定

  • 名为 x 的摘要或直方图的样本总和,以一个名为 x_sum 的单独样本给出。
  • 名为 x 的摘要或直方图的样本计数,以一个名为 x_count 的单独样本给出。
  • 名为 x 的摘要的每个分位数,都以一个具有相同名称 x 和标签 {quantile="y"} 的单独样本行给出。
  • 名为 x 的直方图的每个桶计数,都以一个名为 x_bucket 和标签 {le="y"}(其中 y 是桶的上限)的单独样本行给出。
  • 直方图必须有一个带有 {le="+Inf"} 的桶。它的值必须x_count 的值相同。
  • 直方图的桶和摘要的分位数必须按照其标签值(分别为 lequantile 标签)的数值升序排列。

文本格式示例

下面是一个完整的 Prometheus 指标暴露示例,包括注释、HELPTYPE 表达式、一个直方图、一个摘要、字符转义示例等等。

# 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 或更高版本起,它也可用于联邦指标。

Exemplars (范例) (实验性)

利用 OpenMetrics 格式可以暴露和查询 Exemplars (范例)。Exemplars 为其他情况下汇总的 MetricFamily 提供了一个与指标集相关的某个时间点的快照。此外,它们可能附加一个跟踪 ID,当与跟踪系统一起使用时,可以提供与特定服务相关的更详细信息。

要启用此实验性功能,您必须拥有至少 v2.26.0 版本,并在您的参数中添加 --enable-feature=exemplar-storage

Protobuf 格式

早期版本的 Prometheus 除了当前的基于文本的格式外,还支持一种基于 Protocol Buffers(又称 Protobuf)的暴露格式。随着 Prometheus 2.0 的发布,Protobuf 格式被标记为已弃用,并且 Prometheus 停止从该暴露格式中摄取样本。

然而,Prometheus 增加了一些新的实验性功能,其中 Protobuf 格式被认为是最佳选择。这使得 Prometheus 再次接受 Protocol Buffers。

以下是实验性功能的列表,一旦启用,将配置 Prometheus 优先使用 Protobuf 暴露格式

功能标志引入版本
native-histograms2.40.0
created-timestamp-zero-ingestion2.50.0

历史版本

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

原始 Protobuf 格式的当前版本(包含最近对原生直方图的扩展)维护在 prometheus/client_model 仓库中。

本页内容