提供的数据传输格式 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_name和label_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行首先（不是特定的顺序）。 除此之外，重复展示的可重复排序是优选的，但不是必需的，即不计算计算成本是否可以排序。

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

histogram和summary类型很难以文本格式表示。 适用以下约定：

  • 名为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
  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

可选文本表示 Optional Text Representation

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

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

    历史版本

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