Prometheus logo

Prometheus

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

Ctrl + K

GitHub Logo

抓取协议内容协商

摘要

本文档规定了 Prometheus 在从目标抓取指标时所使用的协议协商机制。它定义了 Accept 请求头格式、支持的内容类型 (Content Types) 以及确定最佳指标展示格式的协商过程。

简介

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 的 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

本页内容