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
优点
  • 人类可读
  • 易于构建，特别是对于极简场景（无需嵌套）
  • 可逐行读取（除类型提示和文档字符串外）
局限性
  • 冗长
  • 类型和文档字符串不是语法的核心部分，这意味着指标合同验证几乎不存在
  • 解析成本
支持的指标基元
  • 计数器 (Counter)
  • 仪表盘 (Gauge)
  • 直方图
  • 摘要
  • 未定义类型 (Untyped)

文本格式详细信息

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

行格式

在一行中，标记可以用任意数量的空格和/或制表符分隔（如果它们会与前一个标记合并，则必须至少用一个分隔）。开头和结尾的空格将被忽略。

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

以 # 作为第一个非空白字符开头的行是注释。除非 # 之后的第一个标记是 HELP 或 TYPE，否则它们将被忽略。这些行处理方式如下：如果标记是 HELP，则至少需要一个附加标记，即指标名称。所有剩余的标记都被视为该指标名称的文档字符串。HELP 行可以包含任何 UTF-8 字符序列（在指标名称之后），但反斜杠和换行符必须分别转义为 \\ 和 \n。对于任何给定的指标名称，最多只能存在一个 HELP 行。

如果标记是 TYPE，则需要恰好两个附加标记。第一个是指标名称，第二个是 counter、gauge、histogram、summary 或 untyped 中的一个，用于定义该指标名称的类型。对于给定的指标名称，最多只能存在一个 TYPE 行。指标名称的 TYPE 行必须出现在报告该指标名称的第一个样本之前。如果指标名称没有 TYPE 行，则类型设置为 untyped。与传统的 Prometheus 指标名称字符集不匹配的指标名称必须被引用并转义。

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

metric_name_or_labels value [ timestamp ]

metric_name_or_labels = metric_name [ "{" labels "}" ] | "{" quoted_metric_name [ "," labels ] "}"

metric_name = identifier

quoted_metric_name = `"` escaped_string `"`

labels = [ label_pairs ]

label_pairs = label_pair { "," label_pair } [ "," ]

label_pair = label_name "=" `"` escaped_string `"`

label_name = identifier | `"` escaped_string `"`

在样本语法中

  • identifier 遵循 Prometheus 表达式语言的常规限制。
  • escaped_string 由任何 UTF-8 字符组成，但反斜杠、双引号和换行符必须转义。
  • 当 metric_name 用双引号引用时，它会出现在花括号内部而不是外部。
  • label_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() 函数的要求。

分组和排序

给定指标的所有行必须作为单个组提供，可选的 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

# UTF-8 metric and label names:
{"my.dotted.metric", "error.message"="Not Found"}

# 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 格式可以暴露和查询 示例 (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。

当通过功能标志 (--enable-feature=created-timestamp-zero-ingestion) 或通过设置适当的配置选项 (scrape_native_histograms: true) 启用此类功能时，Protobuf 将优先于其他暴露格式。

HTTP Content-Type 要求

从 Prometheus 3.0 开始，抓取目标 *必须* 为指标端点返回有效的 Content-Type 标头。如果 Content-Type 缺失、无法解析或不是支持的媒体类型，*抓取将失败*。有关详细信息，请参阅迁移指南中的 抓取协议。

请参阅每个暴露格式部分的准确 HTTP 内容类型。

ScrapeProtocols 与 Content-Type

Prometheus 抓取配置提供基于 content-type 的抓取协议协商，使用 scrape_protocols 配置。为了方便 Prometheus 用户，抓取协议由一个唯一的名称引用，该名称映射到具体的 content-type。有关详细信息，请参阅 协议标头。

但是，目标应以绝对的响应内容类型（例如 application/openmetrics-text;version=1.0.0）暴露指标，并且只能有一种。

历史版本

有关历史版本格式的详细信息，请参阅旧版 客户端数据暴露格式 (Client Data Exposition Format)  文档。

原始 Protobuf 格式的当前版本（包括用于原生直方图的最新扩展）维护在 prometheus/client_model 仓库  中。

本页内容