提供的数据传输格式 exposition formats


Prometheus实现了两种不同的数据传输格式,客户端可以使用检测的度量指标给Prometheus服务,第一种:是基于文本的简单格式, 第二种:更有效和更强大的协议缓冲格式。Prometheus服务和客户端通过HTTP通信获取要使用的是哪种协议。一个服务比较倾向于接收第二种更有效和更强大的协议缓冲格式。但是如果客户端不支持前者,数据传输格式会回退到第二种基于文本的简单格式

大多数用户应该使用已经存在的客户库,且这些客户库已经实现了两种数据传输格式。

Format v0.0.4

v0.0.4是当前度量指标的数据传输格式版本

到这个版本,Prometheus有两种备用的数据传输格式:基于协议缓冲的格式和文本格式。客户端必须支持这两种备用格式中的一种。

另外,客户端可选择性地提供不被Prometheus服务理解的其他数据传输文本格式。他们仅仅是为了易于理解和方便调试。强烈建议客户端库至少一种可读的格式。有一种情况: 在HTTP头部的Content-Type内容,如果客户库不能理解, 则易于理解的数据传输协议应该是候选项,v0.0.4的数据传输协议容易被理解,所以它是一个很好的数据传输格式候选者(并且也被Prometheus理解)。

格式变体比较

协议缓冲格式 文本格式
开始时间 2014.4月 2014.4月
传输协议 HTTP HTTP
编码 - 32-bit varint-encoded record length-delimited utf-9, \n行结尾
- Protocol Buffer messages of type
- io.prometheus.client.MetricFamily
HTTP Content-Type application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited 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 gzip
优点 - 跨平台 -可读性好
- Size - 易于组合,特别适用于简单情况(无需嵌套)
- 编解码代价小 - 逐行阅读(处理类型提示和文本字符串外)
- 严格的范式
- 支持链接和理论流(仅服务端行为需要更改)
限制 - 不具有可读性 - 信息不全
- 类型和文档格式不是语法的组成部分,意味着很少到不存在的度量契约验证
- 解析代价大
支持度量指标原子性 - Counter - Counter
- Gauge - Gauge
- Histogram - Histogram
- Summary - Summary
- Untyped - Untyped
兼容性 - 低于v.0.0.3无效
- v0.0.4有效

Protocol buffer format details 协议缓冲区格式详细信息

在重复数据传输协议中,协议缓冲区的可重复排序是优选的,但不是必需的,即如果计算成本过高,则不排序

同一个数据传输协议中MetricFamily的必须有一个唯一的名称。且MetricFamily中的每个度量指标都必须有一组唯一的LabelPair字段。否则,这种嵌入行为是未定义的。

Text format details 文本格式详解

协议是面向行的。换行字符(\n)分隔行。最后一行必须以换行字符结束。空行被忽略。

在一行内,令牌可以被任何数量的空格和/或制表符分开(如果它们不想和以前的token合并,则必须至少分开一个)。头尾部的空白被忽略。

具有”#”作为第一个费空格字符的行是注释。它们被忽略,除非“#”之后的一个令牌是HELP或TYPE。这些行被视为如下:如果令牌是HELP,则至少需要一个令牌,这是度量指标名称。所有剩余的令牌都被认为是该度量指标名称的docstring。HELP行可以包含任何UTF-8字符序列(度量名称后)。但反斜杠和换行字符必须分别转移为\和\n。相同的度量名称只能有一个HELP行。

如果令牌是TYPE,则预期只有两个令牌。第一个是度量名称,第二个是计数器,规格,直方图,摘要或无类型,定义该名称的度量标准的类型。相同的度量名称只能有一个TYPE行。用于度量名称的TYPE行必须出现在为该度量名称报告的第一个样本之前。如果度量名称没有TYPE行,则该类型将设置为无类型。剩余行用以下语法描述样本,每行一个(EBNF):

  1. metric_name [
  2. "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
  3. ] value [ timestamp ]

metric_namelabel_name具有普通的Prometheus表达式语言限制。 label_value可以是UTF-8字符的任何序列,但反斜杠,双引号和换行字符必须分别转义为\,\“和\ n,value为浮点数和时间戳 一个int64(从时代以来的毫秒,即1970-01-01 00:00:00 UTC,不包括闰秒),由Go strconv软件包(见函数ParseInt和ParseFloat)表示,特别是Nan,+ Inf和 -Inf是有效值。

给定度量的所有行必须作为一个不间断的组提供,可选的HELP和TYPE行首先(不是特定的顺序)。 除此之外,重复展示的可重复排序是优选的,但不是必需的,即不计算计算成本是否可以排序。

每行必须具有度量名称和标签的唯一组合。 否则,嵌入行为是未定义的。

histogramsummary类型很难以文本格式表示。 适用以下约定:

  • 名为x的摘要或直方图的样本总和作为名为x_sum的单独样本给出。
  • 名为x的摘要或直方图的样本计数作为名为x_count的单独样本给出。
  • 名为x的摘要的每个分位数作为具有相同名称x和标签{quantile =“y”}的单独样本行给出。
  • 名为x的直方图的每个桶计数作为单独的样本行(名称为x_bucket)和一个标签{le =“y”}(其中y是存储桶的上限)给出。
  • 直方图必须带有{le =“+ Inf”}的存储桶。 其值必须与x_count的值相同。
  • 直方图的桶和总结的分位数必须以其标签值的增加数字顺序(分别为le或分位数标签)出现。另见下面的例子。
  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
  5. # Escaping in label values:
  6. msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9
  7. # Minimalistic line:
  8. metric_without_timestamp_and_labels 12.47
  9. # A weird metric from before the epoch:
  10. something_weird{problem="division by zero"} +Inf -3982045
  11. # A histogram, which has a pretty complex representation in the text format:
  12. # HELP http_request_duration_seconds A histogram of the request duration.
  13. # TYPE http_request_duration_seconds histogram
  14. http_request_duration_seconds_bucket{le="0.05"} 24054
  15. http_request_duration_seconds_bucket{le="0.1"} 33444
  16. http_request_duration_seconds_bucket{le="0.2"} 100392
  17. http_request_duration_seconds_bucket{le="0.5"} 129389
  18. http_request_duration_seconds_bucket{le="1"} 133988
  19. http_request_duration_seconds_bucket{le="+Inf"} 144320
  20. http_request_duration_seconds_sum 53423
  21. http_request_duration_seconds_count 144320
  22. # Finally a summary, which has a complex representation, too:
  23. # HELP rpc_duration_seconds A summary of the RPC duration in seconds.
  24. # TYPE rpc_duration_seconds summary
  25. rpc_duration_seconds{quantile="0.01"} 3102
  26. rpc_duration_seconds{quantile="0.05"} 3272
  27. rpc_duration_seconds{quantile="0.5"} 4773
  28. rpc_duration_seconds{quantile="0.9"} 9001
  29. rpc_duration_seconds{quantile="0.99"} 76656
  30. rpc_duration_seconds_sum 1.7560473e+07
  31. rpc_duration_seconds_count 2693

可选文本表示 Optional Text Representation

以下三种可选文本格式仅供使用,且不被Prometheus理解。因此,他们的定义可能会有些随意。客户端库可能支持或可能不支持这些格式。工具不应该依赖这些格式。

  1. HTML:此格式由HTTP Content-Type头部请求,其值为text/html。在浏览器中查看的指标是一个“pretty”渲染。虽然生成客户端在技术上完全免费组装HTML,但客户端库之间的一致性应该是针对的。
  2. 协议缓冲区文本格式:与协议缓冲区格式相同,但以文本形式。它由以文本格式(也称为“调试字符串”)连接的协议消息组成,由另外的新行字符分隔(即在协议消息之间有空行)。请求格式为协议缓冲区格式,但HTTP Content-Type头文件中的编码设置为文本。
  3. 协议缓冲区紧凑文本格式:与(2)相同,但使用紧凑文本格式而不是普通文本格式。紧凑文本格式将整个协议消息放在一行上。协议消息仍然以新的行字符分隔,但是不需要“空行”来进行分离。 (每行只需一个协议消息)。格式被请求为协议缓冲区格式,但HTTP Content-Type头中的编码设置为compact-text。

    历史版本

    有关历史格式版本的详细信息,请参阅旧版客户端数据展示格式文档