v2.17

公开的格式

可以使用基于文本的简单展示格式将数据指标暴露给 Prometheus。有多种客户端库可以为您实现这种格式。如果您的首选语言没有客户端库，则可以创建自己的客户端库。

NOTE: Prometheus的某些早期版本除了支持当前基于文本的格式外，还支持基于Protocol Buffers(又称 Protobuf)的展示格式。但是，从2.0版开始，Prometheus 不再支持基于 Protobuf 的格式。您可以在本文档中了解此更改背后的原因

基于文本的格式

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

基本信息

Aspect

Description

Inception

April 2014

Supported in

Prometheus version >=0.4.0

Transmission

HTTP

Encoding

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.)

Optional HTTP Content-Encoding

gzip

Advantages

  • Human-readable

  • Easy to assemble, especially for minimalistic cases (no nesting required)

  • Readable line by line (with the exception of type hints and docstrings)

Limitations

  • Verbose

  • Types and docstrings not integral part of the syntax, meaning little-to-nonexistent metric contract validation

  • Parsing cost

Supported metric primitives

  • 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。

其余各行使用以下语法(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数字(自计时开始的毫秒数，如 1970-01-01 00:00:00 UTC,不包括闰秒)，符合 Go 的ParseInt()函数要求。

分组和排序

给定指标的所有行都必须作为一个独立的组提供，并首先提供可选的HELP和TYPE行(无特定顺序)。除此之外，在重复展示中重新排序分类是优选的，但不是必需的，即，如果计算成本过高，则不要排序。

每行必须有数据指标名称和标签的唯一组合。否则，采集行为是不确定的。

Histograms and summaries

histogram和summary类型的数据指标很难用文本格式表示。以下是通用的约定:

  • 名为x的histogram或summary类型的数据指标总和以名为x_sum的独立样本给出。

  • 名为x的histogram或summary类型的数据指标计数以名为x_count的独立样本给出。

  • 名为x的summary类型的数据指标的每个分位数(quantile)以相同名称x及带有标签{quantile="y"}的独立样本给出。

  • 名为x的histogram类型的数据指标的每个存储桶计数以名为x_bucket及带有标签{le="y"}的独立样本给出(y是每个存储桶的上限)。

  • histogram类型的数据指标必须包含一个带有{le="+Inf"}标签的独立样本。其值必须与x_count的值相同

  • 名为x的histogram或summary类型的数据指标总和作为名为x_sum的单独样本给出。

  • 的数据指标的存储桶(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

# 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

历史版本

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

上一页编写数据导出器下一页告警概述

最后更新于