Prometheus logo

Prometheus

文档下载社区支持 & 培训博客

Ctrl + K

GitHub Logo

暴露格式

可以使用简单的基于文本的暴露格式将指标暴露给 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
优点
  • 人类可读
  • 易于组装，特别是对于极简情况（无需嵌套）
  • 逐行可读（类型提示和文档字符串除外）
限制
  • 冗长
  • 类型和文档字符串并非语法不可或缺的部分，意味着指标契约验证很少或根本不存在
  • 解析成本
支持的指标原语
  • 计数器
  • 仪表
  • 直方图
  • 摘要
  • 无类型

文本格式详情

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（自 Unix 纪元，即 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 文本格式

OpenMetrics 是一项旨在标准化指标线格式的努力，它基于 Prometheus 文本格式构建。从 v2.23.0 版本起，可以抓取目标，并且也可用于联邦指标。

Exemplar（实验性）

利用 OpenMetrics 格式可以暴露和查询Exemplar。Exemplar 提供了与某个指标集相关的瞬时快照，用于否则被汇总的 MetricFamily。此外，它们可能附带 Trace 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 仓库 中维护。

本页内容