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

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

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

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

    格式变体比较

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

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

    Text format details 文本格式详解

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

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

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

    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. # Minimalistic line:
    7. metric_without_timestamp_and_labels 12.47
    8. # A weird metric from before the epoch:
    9. something_weird{problem="division by zero"} +Inf -3982045
    10. # A histogram, which has a pretty complex representation in the text format:
    11. # HELP http_request_duration_seconds A histogram of the request duration.
    12. # TYPE http_request_duration_seconds histogram
    13. http_request_duration_seconds_bucket{le="0.05"} 24054
    14. http_request_duration_seconds_bucket{le="0.1"} 33444
    15. http_request_duration_seconds_bucket{le="0.2"} 100392
    16. http_request_duration_seconds_bucket{le="+Inf"} 144320
    17. http_request_duration_seconds_sum 53423
    18. http_request_duration_seconds_count 144320
    19. # Finally a summary, which has a complex representation, too:
    20. # HELP rpc_duration_seconds A summary of the RPC duration in seconds.
    21. # TYPE rpc_duration_seconds summary
    22. rpc_duration_seconds{quantile="0.01"} 3102
    23. rpc_duration_seconds{quantile="0.05"} 3272
    24. rpc_duration_seconds{quantile="0.5"} 4773
    25. rpc_duration_seconds{quantile="0.9"} 9001
    26. rpc_duration_seconds{quantile="0.99"} 76656
    27. rpc_duration_seconds_count 2693

    可选文本表示 Optional Text Representation

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