# 公开的格式 可以使用[基于文本](/prometheus/v2.18/instrumenting/exposition_formats.md#text-based-format)的简单展示格式将数据指标暴露给 Prometheus。有多种[客户端库](/prometheus/v2.18/instrumenting/clientlibs.md)可以为您实现这种格式。如果您的首选语言没有客户端库，则可以[创建自己的客户端库](/prometheus/v2.18/instrumenting/writing_clientlibs.md)。 {% hint style="info" %} NOTE: Prometheus的某些早期版本除了支持当前基于文本的格式外，还支持基于[Protocol Buffers](https://developers.google.com/protocol-buffers/)(又称 Protobuf)的展示格式。但是，从2.0版开始，Prometheus 不再支持基于 Protobuf 的格式。您可以在[本文档](https://github.com/OpenObservability/OpenMetrics/blob/master/markdown/protobuf_vs_text.md)中了解此更改背后的原因 {% endhint %} ## 基于文本的格式 从 Prometheus 2.0 版开始，所有向 Prometheus 公开指标的程序都需要使用基于文本的格式。在本节中，您可以找到有关此格式的一些[基本信息](/prometheus/v2.18/instrumenting/exposition_formats.md#basic-info)以及该格式的[更详细的细节](/prometheus/v2.18/instrumenting/exposition_formats.md#text-format-details)。 ### 基本信息 | 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** | | | **Limitations** | | | **Supported metric primitives** | | ### 文本格式详情 Prometheus 基于文本的格式是面向行的。行由换行符(`\n`)分隔。最后一行必须以换行符结尾。空行将被忽略。 #### 行的格式 在一行中，标记可以用任意数量的空格和/或制表符分隔(如果不与先前的标记合并，则必须至少用一个空格分隔)。行首和行尾的空格将被忽略。 #### 注释，帮助和类型信息 以`#`作为第一个非空白字符的行是注释。除非`#`之后的第一个标记为`HELP`或`TYPE`，否则将忽略它们。这些行的处理方式如下：如果标记为`HELP`，则至少应再有一个是数据指标名称的标记。所有其余标记都被视为该数据指标名称的文档字符串。`HELP`行可以包含任何的 UTF-8 字符(在数据指标名称之后)，但是反斜杠和换行符必须分别转义为`\\`和`\n`。对于任何给定的度量标准名称，只能存在一个`HELP`行。 如果标记是`TYPE`，则应该刚好再有两个标记。第一个是数据指标名称，第二个是`counter`, `gauge`, `histogram`, `summary`或`untyped`，用于定义该数据指标的类型。对于给定的数据指标名称，只能存在一个`TYPE`行。 数据指标名称的`TYPE`行必须出现在的第一个报告的数据指标样本之前。如果数据指标名称没有`TYPE`行，则将类型设置为`untyped`。 其余各行使用以下语法([EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form))描述样本(每行一个): ``` metric_name [ "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}" ] value [ timestamp ] ``` 在示例语法中: * `metric_name`和`label_name`遵循常见的 Prometheus 表达式语言限制 * `label_value`可以是任意 UTF-8 字符, 但是反斜线(`\`), 双引号(`"`)和换行符(`\n`)必须分别被转义为`\\`, `\"`和`\n`。 * `value`是按 Go 的[`ParseFloat()`](https://golang.org/pkg/strconv/#ParseFloat)函数要求的浮点数。除标准数值外，`Nan`,`+Inf`和`-Inf`是有效值，分别代表不是数字，正无穷大和负无穷大。 * `timestamp`是一个`int64`数字(自计时开始的毫秒数，如 1970-01-01 00:00:00 UTC,不包括闰秒)，符合 Go 的[`ParseInt()`](https://golang.org/pkg/strconv/#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 类型的数据、字符转义等示例 ``` # HELP http_requests_total The total number of HTTP requests. # TYPE http_requests_total counter http_requests_total{method="post",code="200"} 1027 1395066363000 http_requests_total{method="post",code="400"} 3 1395066363000 # Escaping in label values: msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9 # Minimalistic line: metric_without_timestamp_and_labels 12.47 # A weird metric from before the epoch: something_weird{problem="division by zero"} +Inf -3982045 # A histogram, which has a pretty complex representation in the text format: # HELP http_request_duration_seconds A histogram of the request duration. # TYPE http_request_duration_seconds histogram http_request_duration_seconds_bucket{le="0.05"} 24054 http_request_duration_seconds_bucket{le="0.1"} 33444 http_request_duration_seconds_bucket{le="0.2"} 100392 http_request_duration_seconds_bucket{le="0.5"} 129389 http_request_duration_seconds_bucket{le="1"} 133988 http_request_duration_seconds_bucket{le="+Inf"} 144320 http_request_duration_seconds_sum 53423 http_request_duration_seconds_count 144320 # Finally a summary, which has a complex representation, too: # HELP rpc_duration_seconds A summary of the RPC duration in seconds. # TYPE rpc_duration_seconds summary rpc_duration_seconds{quantile="0.01"} 3102 rpc_duration_seconds{quantile="0.05"} 3272 rpc_duration_seconds{quantile="0.5"} 4773 rpc_duration_seconds{quantile="0.9"} 9001 rpc_duration_seconds{quantile="0.99"} 76656 rpc_duration_seconds_sum 1.7560473e+07 rpc_duration_seconds_count 2693 ``` ## 历史版本 有关历史格式版本的详细信息，请参阅旧版[Client Data Exposition Format](https://docs.google.com/document/d/1ZjyKiKxZV83VI9ZKAXRGKaUKK2BIWCT7oiGBKDBpjEY/edit?usp=sharing)文档。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://hulining.gitbook.io/prometheus/v2.18/instrumenting/exposition_formats.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.