公开的格式
可以使用基于文本的简单展示格式将数据指标暴露给 Prometheus。有多种客户端库可以为您实现这种格式。如果您的首选语言没有客户端库,则可以创建自己的客户端库。
NOTE: Prometheus的某些早期版本除了支持当前基于文本的格式外,还支持基于Protocol Buffers(又称 Protobuf)的展示格式。但是,从2.0版开始,Prometheus 不再支持基于 Protobuf 的格式。您可以在本文档中了解此更改背后的原因
基于文本的格式
从 Prometheus 2.0 版开始,所有向 Prometheus 公开指标的程序都需要使用基于文本的格式。在本节中,您可以找到有关此格式的一些基本信息以及该格式的更详细的细节。
基本信息
Aspect | Description |
Inception | April 2014 |
Supported in | Prometheus version |
Transmission | HTTP |
Encoding | UTF-8, |
HTTP |
|
Optional HTTP |
|
Advantages |
|
Limitations |
|
Supported metric primitives |
|
文本格式详情
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
遵循常见的 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 类型的数据、字符转义等示例
历史版本
有关历史格式版本的详细信息,请参阅旧版Client Data Exposition Format文档。
最后更新于