• 公开的格式
    • " level="2">基于文本的格式
      • " level="3">基本信息
      • " level="3">文本格式详情
        • " level="4">行的格式
        • " level="4">注释，帮助和类型信息
        • " level="4">分组和排序
        • Histograms and summaries
      • " level="3">文本格式的示例
    • " level="2">历史版本

    公开的格式

    可以使用基于文本的简单展示格式将数据指标暴露给 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文档。