Prometheus logo

Prometheus

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

Ctrl + K

GitHub Logo

抓取协议内容协商

摘要

本文档规定了 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 头构造

Prometheus 构造 Accept 头以指示其支持的格式。

基本格式

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
  • 如果禁用了压缩，则为 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-First 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

本页内容