暴露格式

从 Prometheus 2.0 版本开始，默认情况下，所有向 Prometheus 暴露指标的进程都必须使用文本格式。在 HTTP 内容协商的支持下，也可以使用替代的 Protobuf 格式。

有各种客户端库可以为您实现这些格式。如果您偏好的语言没有客户端库，您可以自行创建。

本文概述了官方支持的暴露格式。

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) 直方图 摘要 无类型 (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 文本格式标准化指标线路格式的努力。自 Prometheus v2.23.0 以来，它不仅可以采集目标，还可用于联邦指标。

目前有两个版本的 OpenMetrics

• 1.0
• 2.0（草案）

基本信息

维度	描述
创立时间	2020 年 11 月
支持版本	Prometheus 版本 >=2.5.0
传输	HTTP
编码	UTF-8，\n 行尾，以 # EOF 结尾。
HTTP Content-Type	application/openmetrics-text，带参数 version=1.0.0（缺失 version 值将回退到最近的 OpenMetrics 文本版本。）
可选的 HTTP Content-Encoding	gzip
优势	人类可读 易于组装，特别是在极简情况下（无需嵌套） 可逐行读取（元数据除外）
局限性	冗长 类型和文档字符串不是语法的组成部分，这意味着指标契约验证很少或根本不存在 解析开销
支持的指标原语	计数器 (Counter) 仪表 (Gauge) 直方图 GaugeHistogram 摘要 Info StateSet 无类型 (Untyped)
支持的高级特性	单位元数据 样本 (Exemplars)（计数器、直方图、GaugeHistogram） 创建/开始时间戳（计数器、直方图、GaugeHistogram、摘要） UTF-8 指标名称和标签名称

样本 (Exemplars) (实验性)

利用 OpenMetrics 格式可以暴露和查询 样本 (Exemplars) 。样本为 MetricFamily 提供了一个时间点快照，这在原本是汇总形式的情况下非常有用。此外，它们还可以附带一个追踪 ID，与追踪系统结合使用时，可以提供有关特定服务的更详细信息。

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

Prometheus Protobuf 格式

除了文本表示外，Prometheus 官方还支持 Protobuf 暴露格式 。

有效载荷必须编码为一组表示 MetricFamily 的 Protobuf 消息。消息必须以二进制形式编码，并在前面加上其变长无符号整数编码的大小，作为分隔符。这种以变长整数编码大小分隔的编码方式提供了流式处理能力，这对大型采集目标尤为重要。

所有字符串字段必须进行 UTF-8 编码。

Prometheus 3.0 默认首选基于文本的协议，除非

• 通过 Prometheus 配置中的 scrape_protocols 设置手动设置偏好。
• 优先使用 Protobuf 格式，当启用特定功能时（例如：
  • --enable-feature=created-timestamp-zero-ingestion 或 --enable-feature=st-storage
  • 适当的配置选项 (scrape_native_histograms: true)

在 Prometheus 2.0 中，Protobuf 格式曾被标记为已弃用，但此后该决定已被撤销。从 Prometheus 3.0 开始，Prometheus Proto 被积极使用和维护，作为文本格式的补充。

基本信息

维度	描述
创立时间	2014 年 4 月
支持版本	Prometheus 版本 >=0.4.0
传输	HTTP
编码	32 位变长编码记录长度分隔的 io.prometheus.client.MetricFamily 协议缓冲区消息
HTTP Content-Type	application/vnd.google.protobuf，带参数 proto=io.prometheus.client.MetricFamily encoding=delimited
可选的 HTTP Content-Encoding	gzip
优势	跨平台 尺寸 向前/向后兼容性 严格架构 支持连接和流式传输 复合值
局限性	不可读（人类不可读）
支持的指标原语	计数器 (Counter) 仪表 (Gauge) 直方图 GaugeHistogram 摘要 无类型 (Untyped)
支持的高级特性	单位元数据 样本 (Exemplars)（计数器、直方图、GaugeHistogram） 创建/开始时间戳（计数器、直方图、GaugeHistogram、摘要） 原生（稀疏和指数）直方图、GaugeHistogram UTF-8 指标名称和标签名称

何时使用 Proto 而不是文本？

文本格式是人类可读的，压缩效果好，且对于编程使用足够高效，但 Prometheus 社区也维护 Protobuf 格式，因为

• 它提高了新功能的质量和迭代速度，这些功能可以以向后/向前兼容的方式安全测试。
• 得益于代码生成和灵活性，Protobuf 有助于暴露者/摄取者的实现。
• 在（令人惊讶的罕见）情况下，二进制编码可以更高效地编码/解码。

您可以在 PromCon 2025 演讲  中了解更多。

版本控制

目前 Prometheus Protobuf 是稳定的，但没有显式版本控制。相反，它遵循 Prometheus 版本控制作为参考。

架构

标识为 io.prometheus.client 的 Protobuf 架构维护在 Prometheus 仓库中，位于此处 。该架构也可在 buf 注册表  中获取。

HTTP Content-Type 要求

从 Prometheus 3.0 开始，采集目标必须为指标端点返回一个有效的 Content-Type 标头。如果 Content-Type 缺失、不可解析或不是支持的媒体类型，采集将失败。详情请参阅迁移指南中关于采集协议的更改。

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

ScrapeProtocols 与 Content-Type

Prometheus 采集配置提供基于内容类型的采集协议协商，使用 scrape_protocols 配置。为了方便用户，采集协议由映射到具体内容类型的唯一名称引用。详情请参见协议标头。

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

历史版本

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

原始 Protobuf 格式（带有最近的原生直方图扩展）的当前版本维护在 prometheus/client_model 仓库  中。