公开的格式

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

info 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)描述样本(每行一个):

  1. metric_name [
  2.   "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
  3. ] 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 类型的数据、字符转义等示例

  1. # HELP http_requests_total The total number of HTTP requests.
  2. # TYPE http_requests_total counter
  3. http_requests_total{method="post",code="200"} 1027 1395066363000
  4. http_requests_total{method="post",code="400"}    3 1395066363000
  6. # Escaping in label values:
  7. msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9
  9. # Minimalistic line:
  10. metric_without_timestamp_and_labels 12.47
  12. # A weird metric from before the epoch:
  13. something_weird{problem="division by zero"} +Inf -3982045
  15. # A histogram, which has a pretty complex representation in the text format:
  16. # HELP http_request_duration_seconds A histogram of the request duration.
  17. # TYPE http_request_duration_seconds histogram
  18. http_request_duration_seconds_bucket{le="0.05"} 24054
  19. http_request_duration_seconds_bucket{le="0.1"} 33444
  20. http_request_duration_seconds_bucket{le="0.2"} 100392
  21. http_request_duration_seconds_bucket{le="0.5"} 129389
  22. http_request_duration_seconds_bucket{le="1"} 133988
  23. http_request_duration_seconds_bucket{le="+Inf"} 144320
  24. http_request_duration_seconds_sum 53423
  25. http_request_duration_seconds_count 144320
  27. # Finally a summary, which has a complex representation, too:
  28. # HELP rpc_duration_seconds A summary of the RPC duration in seconds.
  29. # TYPE rpc_duration_seconds summary
  30. rpc_duration_seconds{quantile="0.01"} 3102
  31. rpc_duration_seconds{quantile="0.05"} 3272
  32. rpc_duration_seconds{quantile="0.5"} 4773
  33. rpc_duration_seconds{quantile="0.9"} 9001
  34. rpc_duration_seconds{quantile="0.99"} 76656
  35. rpc_duration_seconds_sum 1.7560473e+07
  36. rpc_duration_seconds_count 2693

历史版本

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