Prometheus logo

Prometheus

文档下载社区支持与培训博客

Ctrl + K

GitHub Logo

Scrape 协议内容协商

摘要

本文档规定了 Prometheus 在抓取目标指标时使用的协议协商机制。它定义了 Accept 报头格式、支持的内容类型以及用于确定指标暴露的最佳可用格式的协商过程。

简介

Prometheus 支持多种指标抓取格式，包括文本格式和二进制 protobuf 格式。根据 Accept 报头的取值，目标将选择最佳的可用内容类型进行回复。

协议类型

支持的协议

Prometheus 支持以下协议

  1. PrometheusProto - 二进制 protobuf 格式
  2. PrometheusText0.0.4 - Prometheus 文本格式版本 0.0.4
  3. PrometheusText1.0.0 - Prometheus 文本格式版本 1.0.0
  4. OpenMetricsText0.0.1 - OpenMetrics 文本格式版本 0.0.1
  5. OpenMetricsText1.0.0 - OpenMetrics 文本格式版本 1.0.0

协议报头

每个协议都**必须**与特定的 MIME 类型和版本相关联

协议MIME 类型参数
PrometheusProtoapplication/vnd.google.protobufproto=io.prometheus.client.MetricFamily;encoding=delimited
PrometheusText0.0.4text/plainversion=0.0.4
PrometheusText1.0.0text/plainversion=1.0.0
OpenMetricsText0.0.1application/openmetrics-textversion=0.0.1
OpenMetricsText1.0.0application/openmetrics-textversion=1.0.0

Accept 报头构造

Accept 报头由 Prometheus 构建，用于指示其支持的格式。

基本格式

Accept 报头**必须**按以下方式构建

  1. 对于目标支持的每种协议
    • 协议的 MIME 类型和参数**必须**被指定。
    • 对于 protobuf 协议，**必须**指定“delimited”的编码。
    • 对于 PrometheusText1.0.0 和 OpenMetricsText1.0.0，**应该**附加转义方案参数。
    • **应该**附加一个质量值（q）参数。
  2. **应该**附加一个具有最低质量值的通配符 */*。

质量值

质量值**应该**根据协议在 Accept 报头中的位置按降序分配

  • 第一个协议：q=0.{n+1}
  • 第二个协议：q=0.{n}
  • 以此类推，其中 n 是支持的协议数

转义方案

对于 PrometheusText1.0.0 和 OpenMetricsText1.0.0 协议，Accept 报头**应该**包含一个转义方案参数：escaping=<scheme>

其中 <scheme> **必须**是以下之一

  • allow-utf-8
  • underscores
  • dots
  • values

有关转义方案工作方式的详细信息，请参阅 转义方案 规范。

压缩

如果启用了压缩，则 Accept-Encoding 报头**应**设置为

  • gzip
  • 如果禁用了压缩，则 Accept-Encoding 报头**应**设置为 identity

格式选择

抓取目标**应**使用以下过程来根据 Prometheus 生成的 Accept 报头中的协议列表选择合适的 Content-Type

  1. 它**必须**使用 Accept 报头中具有最高权重且 Prometheus 支持的协议。
  2. 如果不支持任何协议，目标**可以**使用用户配置的备用抓取协议。
  3. 如果未指定备用协议，目标**必须**将 PrometheusText0.0.4 作为最后的手段。

Content-Type 响应

目标**应**使用与接受格式之一匹配的 Content-Type 报头进行响应。Content-Type 报头**必须**包含

  1. 适当的 MIME 类型。
  2. 版本参数。
  3. 对于 1.0.0 及更高版本的文本格式，转义方案参数。

安全注意事项

  1. 目标**必须**验证 Accept 报头，以防止潜在的注入攻击
  2. 转义方案参数**必须**经过验证，以防止协议混淆
  3. Content-Type 报头**必须**进行适当的清理，以防止 MIME 类型混淆

示例

默认 Accept 报头

Accept: application/openmetrics-text;version=1.0.0;escaping=allow-utf-8;q=0.5,application/openmetrics-text;version=0.0.1;q=0.4,text/plain;version=1.0.0;escaping=allow-utf-8;q=0.3,text/plain;version=0.0.4;q=0.2,/;q=0.1

Protobuf 优先 Accept 报头

Accept: application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited;q=0.5,application/
openmetrics-text;version=1.0.0;escaping=allow-utf-8;q=0.4,application/openmetrics-text;version=0.0.1;q=0.3,text/plain;version=1.0.0;escaping=allow-utf-8;q=0.2,text/plain;version=0.0.4;q=0.1,/;q=0.0

本页内容