Prometheus Exporter 呈现格式

可以使用简单的基于文本的说明格式向 Prometheus 公开度量指标。有多种客户端库可以为你实现这种格式。如果您的首选语言没有客户端库，您可以创建自己的客户端库。

基于文本的格式

从 Prometheus 2.0 版开始，所有向 Prometheus 公开度量指标的进程都需要使用基于文本的格式。在本节中，您可以找到有关该格式的一些基本信息以及更详细的格式说明。

基本信息

信息项	描述
开始	April 2014
支持版本	Prometheus version >=0.4.0
传输方式	HTTP
编码	UTF-8, \n line endings
HTTP Content-Type	text/plain; version=0.0.4 (A missing version value will lead to a fall-back to the most recent text format version.)
可选的 HTTP Content-Encoding	gzip
优势	Human-readable Easy to assemble, especially for minimalistic cases (no nesting required) Readable line by line (with the exception of type hints and docstrings)
限制	Verbose Types and docstrings not integral part of the syntax, meaning little-to-nonexistent metric contract validation Parsing cost
支持的指标原始类型	Counter Gauge Histogram Summary Untyped

文本格式详情

Prometheus 的文本格式以行为导向。每行之间用换行符 (\n) 分隔。最后一行必须以换行符结束。空行将被忽略。

行格式

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

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

以 # 作为第一个非空格字符的行是注释。除非 # 后面的第一个字符是 HELP 或 TYPE，否则这些行将被忽略。这些行的处理方法如下：如果标记为 HELP，则至少还需要一个标记，即指标名称。其余所有标记均视为该指标名称的文档字符串。HELP 行可以包含任何 UTF-8 字符序列（在度量名称之后），但反斜杠和换行符必须分别转义为 \ 和 \n。任何给定的度量衡名称只能有一个 HELP 行。

如果标记为 TYPE，则会出现另外两个标记。第一个是指标名称，第二个是 counter, gauge, histogram, summary, 或 untyped，定义了该名称的指标类型。一个给定的度量衡名称只能有一个 TYPE 行。度量名称的类型行必须在报告该度量名称的第一个样本之前出现。如果某个度量名称没有 TYPE 行，则类型将设为无类型。

其余各行使用以下语法（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 也是有效值，分别代表非数字、正无穷大和负无穷大。
时间戳是 int64（自纪元起的毫秒数，即 1970-01-01 00:00:00 UTC，不包括闰秒），用 Go 的ParseInt() 函数表示。

分组和排序

给定指标的所有行必须作为一组提供，并将可选的 "HELP" 和 "TYPE" 行放在首位（顺序不限）。除此以外，最好能在重复阐述中进行可重现的排序，但不是必需的，也就是说，如果计算成本过高，就不要排序。

每一行都必须有唯一的度量名称和标签组合。否则，摄取行为将无法定义。

直方图和摘要

直方图和摘要类型难以用文本格式表示。以下约定适用：

名为 x 的汇总或直方图的样本总和以名为 x_sum 的单独样本给出。
名为 x 的汇总或直方图的样本计数作为名为 x_count 的单独样本给出。
名为 x 的汇总的每个分位数都会作为单独的样本行给出，样本行的名称与 x 相同，标签为 {quantile="y"}。
以 x 命名的直方图的每个桶计数作为单独的样本行给出，其名称为 x_bucket，标签为 {le="y"}（其中 y 是桶的上限）。
直方图必须有一个带有 {le="+Inf"} 的桶。其值必须与 x_count 的值相同。
直方图的数据桶和摘要的量化值必须按其标签值（分别为 le 或量化值标签）的数字递增顺序排列。

文本格式示例

下面是一个完整的 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