可以使用简单的基于文本的暴露格式向 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 |
优点 |
|
局限性 |
|
支持的指标基本类型 |
|
Prometheus 的基于文本的格式是面向行的。行之间用换行符 (\n
) 分隔。最后一行必须以换行符结尾。空行会被忽略。
在一行中,标记可以通过任意数量的空格和/或制表符分隔(如果它们与前一个标记合并,则必须至少有一个分隔符)。行首和行尾的空白字符会被忽略。
以 #
作为第一个非空白字符开头的行是注释。除非 #
后面的第一个标记是 HELP
或 TYPE
,否则它们会被忽略。这些行处理如下:如果标记是 HELP
,则期望至少再有一个标记,即指标名称。所有剩余的标记都被视为该指标名称的文档字符串。HELP
行可以包含任何 UTF-8 字符序列(在指标名称之后),但反斜杠和换行符必须分别转义为 \\
和 \n
。对于任何给定的指标名称,只能有一行 HELP
。
如果标记是 TYPE
,则期望正好有两个附加标记。第一个是指标名称,第二个是 counter
、gauge
、histogram
、summary
或 untyped
,定义了该名称指标的类型。对于任何给定的指标名称,只能有一行 TYPE
。指标名称的 TYPE
行必须出现在该指标名称的第一个样本报告之前。如果指标名称没有 TYPE
行,则类型设置为 untyped
。
其余行描述样本(每行一个)使用以下语法(EBNF)
metric_name [
"{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
] value [ timestamp ]
在样本语法中
metric_name
和 label_name
遵循通常的 Prometheus 表达式语言限制。label_value
可以是任何 UTF-8 字符序列,但反斜杠 (\
)、双引号 ("
) 和换行符 (\n
) 必须分别转义为 \\
、\"
和 \n
。value
是一个浮点数,表示方式符合 Go 的 ParseFloat()
函数要求。除了标准的数值外,NaN
、+Inf
和 -Inf
也是有效值,分别表示非数字、正无穷和负无穷。timestamp
是一个 int64
值(自 epoch 以来的毫秒数,即 1970-01-01 00:00:00 UTC,不包括闰秒),表示方式符合 Go 的 ParseInt()
函数要求。给定指标的所有行必须作为单个组提供,可选的 HELP
和 TYPE
行在前(无特定顺序)。此外,在重复暴露中可重现的排序是首选的,但并非必需的,即如果计算成本过高,则不要排序。
每行必须具有指标名称和标签的唯一组合。否则,摄取行为是未定义的。
histogram
和 summary
类型在文本格式中难以表示。以下约定适用
x
的摘要或直方图的样本总和以名为 x_sum
的单独样本给出。x
的摘要或直方图的样本计数以名为 x_count
的单独样本给出。x
的摘要的每个分位数都以相同的名称 x
和标签 {quantile="y"}
作为单独的样本行给出。x
的直方图的每个桶计数都以名称 x_bucket
和标签 {le="y"}
(其中 y
是桶的上限)作为单独的样本行给出。{le="+Inf"}
的桶。其值必须与 x_count
的值相同。le
或 quantile
标签)的数值递增顺序出现。下面是一个完整的 Prometheus 指标暴露示例,包括注释、HELP
和 TYPE
表达式、直方图、摘要、字符转义示例等。
# 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 是一个基于 Prometheus 文本格式构建的标准化指标传输格式的工作。自 v2.23.0 起,它可用于抓取目标,也可用于联邦指标。
利用 OpenMetrics 格式可以暴露和查询 Exemplars。Exemplars 为本已汇总的 MetricFamily 提供与一组指标相关的某个时间点快照。此外,它们可能附加 Trace ID,与追踪系统一起使用时,可以提供与特定服务相关的更详细信息。
要启用此实验性功能,您必须至少具有 v2.26.0 版本,并在参数中添加 --enable-feature=exemplar-storage
。
Prometheus 的早期版本除了当前的基于文本的格式外,还支持基于 Protocol Buffers(也称为 Protobuf)的暴露格式。在 Prometheus 2.0 中,Protobuf 格式被标记为已弃用,Prometheus 停止从该暴露格式摄取样本。
然而,Prometheus 添加了新的实验性功能,其中 Protobuf 格式被认为是最佳选择。使得 Prometheus 再次接受 Protocol Buffers。
以下是启用后将配置 Prometheus 首选 Protobuf 暴露格式的实验性功能列表
特性标志 | 引入版本 |
---|---|
native-histograms | 2.40.0 |
created-timestamp-zero-ingestion | 2.50.0 |
有关历史格式版本的详细信息,请参阅旧版 客户端数据暴露格式 文档。
原始 Protobuf 格式的当前版本(包含原生直方图的最新扩展)在 prometheus/client_model 仓库中维护。
本文档是开源的。请通过提交问题或拉取请求来帮助改进它。