暴露格式 | Prometheus

从 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 Histogram Summary 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

histogram 和 summary 类型在文本格式中的表示较为复杂。以下约定适用：

名为 x 的 Summary 或 Histogram 的样本总和通过名为 x_sum 的单独样本给出。
名为 x 的 Summary 或 Histogram 的样本计数通过名为 x_count 的单独样本给出。
名为 x 的 Summary 的每个分位数通过具有相同名称 x 和标签 {quantile="y"} 的单独样本行给出。
名为 x 的 Histogram 的每个桶计数通过名为 x_bucket 并带有标签 {le="y"}（其中 y 是桶的上界）的单独样本行给出。
Histogram _必须_有一个 {le="+Inf"} 的桶。其值_必须_与 x_count 的值相同。
Histogram 的桶和 Summary 的分位数必须按照其标签值的数字递增顺序出现（分别对应 le 或 quantile 标签）。

示例

以下是一个完整的 Prometheus 指标暴露示例，包含注释、HELP 和 TYPE 表达式、Histogram、Summary、字符转义示例等。

# 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：

基本信息

方面	描述
起始时间	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 Histogram GaugeHistogram Summary Info StateSet Untyped
支持的高级特性	单位元数据 Exemplar（Counter、Histogram、GaugeHistogram）创建/开始时间戳（Counter、Histogram、GaugeHistogram、Summary） UTF-8 指标名称和标签名称

Exemplar（实验性）

使用 OpenMetrics 格式允许暴露和查询 Exemplar。Exemplar 提供了与指标集相关的时间点快照，用于其他情况下被汇总的 MetricFamily。此外，它们可能附带 Trace ID，当与追踪系统一起使用时，可以提供与特定服务相关的更详细信息。

要启用此实验性功能，你必须至少使用 v2.26.0 版本，并在参数中添加 --enable-feature=exemplar-storage。

Prometheus Protobuf 格式

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

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

所有字符串字段必须是 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 位 Varint 编码的记录长度分隔的 `io.prometheus.client.MetricFamily` Protocol Buffer 消息
HTTP `Content-Type`	`application/vnd.google.protobuf`，带参数： `proto=io.prometheus.client.MetricFamily` `encoding=delimited`
可选的 HTTP `Content-Encoding`	`gzip`
优势	跨平台体积小向前/向后兼容严格的 Schema 支持拼接和流式处理复合值
局限性	非人类可读
支持的指标原语	Counter Gauge Histogram GaugeHistogram Summary Untyped
支持的高级特性	单位元数据 Exemplar（Counter、Histogram、GaugeHistogram）创建/开始时间戳（Counter、Histogram、GaugeHistogram、Summary）原生（稀疏和指数）Histogram、GaugeHistogram UTF-8 指标名称和标签名称

何时使用 Proto 而非文本？

文本格式人类可读、压缩效果好且在编程使用中足够高效，但 Prometheus 社区也维护 protobuf 格式，因为：

它提高了新功能的质量和速度，使其能够以向后/向前兼容的方式安全测试。
Protobuf 凭借代码生成和灵活性特性，帮助暴露器/摄取器的实现。
在（令人惊讶的少见）情况下，二进制编码可以更高效地编码/解码。

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

版本控制

目前 Prometheus protobuf 是稳定的，但明确没有版本号。相反，它以 Prometheus 版本作为参考。

Schema

Protobuf schema，标识为 io.prometheus.client，维护在 Prometheus 仓库这里。Schema 也可以在 buf registry 中找到。

HTTP Content-Type 要求

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

有关准确的 HTTP content type，请参阅各暴露格式部分。

ScrapeProtocols 与 Content-Type

Prometheus 抓取配置通过 scrape_protocols 配置提供基于 content-type 的抓取协议协商。为了 Prometheus 用户的便利，抓取协议通过唯一的名称引用，该名称映射到具体的 content-type。有关详情，请参阅 Protocol Headers。

但是，目标应以绝对的响应 content-type（例如 application/openmetrics-text;version=1.0.0）暴露指标，且只能使用一种。

历史版本

有关历史格式版本的详情，请参阅旧版 Client Data Exposition Format 文档。

原始 Protobuf 格式的当前版本（包含原生 Histogram 的最新扩展）维护在 prometheus/client_model 仓库中。

从 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 Histogram Summary Untyped
支持的高级特性

详细说明

Prometheus 的基于文本的格式是面向行的。行由换行符（\n）分隔。最后一行必须以换行符结束。空行被忽略。

行格式

在一行内，标记可以由任意数量的空格和/或制表符分隔（如果两个标记相邻会合并则必须至少用一个分隔）。行首和行尾的空白被忽略。

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

剩余的行使用以下语法描述样本（每行一个）（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() 函数的要求。

分组和排序

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

Histogram 和 Summary

histogram 和 summary 类型在文本格式中的表示较为复杂。以下约定适用：

名为 x 的 Summary 或 Histogram 的样本总和通过名为 x_sum 的单独样本给出。
名为 x 的 Summary 或 Histogram 的样本计数通过名为 x_count 的单独样本给出。
名为 x 的 Summary 的每个分位数通过具有相同名称 x 和标签 {quantile="y"} 的单独样本行给出。
名为 x 的 Histogram 的每个桶计数通过名为 x_bucket 并带有标签 {le="y"}（其中 y 是桶的上界）的单独样本行给出。
Histogram _必须_有一个 {le="+Inf"} 的桶。其值_必须_与 x_count 的值相同。
Histogram 的桶和 Summary 的分位数必须按照其标签值的数字递增顺序出现（分别对应 le 或 quantile 标签）。

示例

以下是一个完整的 Prometheus 指标暴露示例，包含注释、HELP 和 TYPE 表达式、Histogram、Summary、字符转义示例等。

# 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：

基本信息

方面	描述
起始时间	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 Histogram GaugeHistogram Summary Info StateSet Untyped
支持的高级特性	单位元数据 Exemplar（Counter、Histogram、GaugeHistogram）创建/开始时间戳（Counter、Histogram、GaugeHistogram、Summary） UTF-8 指标名称和标签名称

Exemplar（实验性）

要启用此实验性功能，你必须至少使用 v2.26.0 版本，并在参数中添加 --enable-feature=exemplar-storage。

Prometheus Protobuf 格式

Prometheus 除了文本表示外，还官方支持 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 位 Varint 编码的记录长度分隔的 `io.prometheus.client.MetricFamily` Protocol Buffer 消息
HTTP `Content-Type`	`application/vnd.google.protobuf`，带参数： `proto=io.prometheus.client.MetricFamily` `encoding=delimited`
可选的 HTTP `Content-Encoding`	`gzip`
优势	跨平台体积小向前/向后兼容严格的 Schema 支持拼接和流式处理复合值
局限性	非人类可读
支持的指标原语	Counter Gauge Histogram GaugeHistogram Summary Untyped
支持的高级特性	单位元数据 Exemplar（Counter、Histogram、GaugeHistogram）创建/开始时间戳（Counter、Histogram、GaugeHistogram、Summary）原生（稀疏和指数）Histogram、GaugeHistogram UTF-8 指标名称和标签名称

何时使用 Proto 而非文本？

文本格式人类可读、压缩效果好且在编程使用中足够高效，但 Prometheus 社区也维护 protobuf 格式，因为：

它提高了新功能的质量和速度，使其能够以向后/向前兼容的方式安全测试。
Protobuf 凭借代码生成和灵活性特性，帮助暴露器/摄取器的实现。
在（令人惊讶的少见）情况下，二进制编码可以更高效地编码/解码。

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

版本控制

目前 Prometheus protobuf 是稳定的，但明确没有版本号。相反，它以 Prometheus 版本作为参考。

Schema

Protobuf schema，标识为 io.prometheus.client，维护在 Prometheus 仓库这里。Schema 也可以在 buf registry 中找到。

HTTP Content-Type 要求

有关准确的 HTTP content type，请参阅各暴露格式部分。

ScrapeProtocols 与 Content-Type

但是，目标应以绝对的响应 content-type（例如 application/openmetrics-text;version=1.0.0）暴露指标，且只能使用一种。

历史版本

有关历史格式版本的详情，请参阅旧版 Client Data Exposition Format 文档。

原始 Protobuf 格式的当前版本（包含原生 Histogram 的最新扩展）维护在 prometheus/client_model 仓库中。