抓取协议内容协商

摘要

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

简介

Prometheus 支持多种抓取指标的格式，包括基于文本的格式和二进制 protobuf 格式。基于 Accept 头的值，目标将选择最佳可用的 Content Type 进行回复。

协议类型

支持的协议

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 版本

协议头

每个协议 MUST 关联一个特定的 MIME 类型和版本：

Protocol	MIME Type	Parameters
PrometheusProto	application/vnd.google.protobuf	proto=io.prometheus.client.MetricFamily;encoding=delimited
PrometheusText0.0.4	text/plain	version=0.0.4
PrometheusText1.0.0	text/plain	version=1.0.0
OpenMetricsText0.0.1	application/openmetrics-text	version=0.0.1
OpenMetricsText1.0.0	application/openmetrics-text	version=1.0.0

Accept 头构造

Accept 头由 Prometheus 构造，用于指示它支持哪些格式。

基本格式

Accept 头 MUST 按以下方式构造：

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

质量值

质量值 SHOULD 根据协议在 Accept 头中的位置按降序分配：

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

转义方案

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

其中 <scheme> MUST 是以下之一：

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

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

压缩

Accept-Encoding 头 SHOULD 设置为：

• 如果启用了压缩则为 gzip
• 如果禁用了压缩则为 identity

格式选择

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

1. MUST 使用 Accept 头中 Prometheus 支持的权重最高的协议。
2. 如果没有支持的协议，目标 MAY 使用用户配置的备用抓取协议。
3. 如果没有指定备用协议，目标 MUST 使用 PrometheusText0.0.4 作为最后手段。

Content-Type 响应

目标 SHOULD 使用与接受格式之一匹配的 Content-Type 头进行响应。Content-Type 头 MUST 包含：

1. 适当的 MIME 类型。
2. 版本参数。
3. 对于 1.0.0 及以上版本的文本格式，需包含转义方案参数。

安全考虑

1. 目标 MUST 验证 Accept 头以防止潜在的注入攻击
2. 转义方案参数 MUST 经过验证以防止协议混淆
3. Content-Type 头 MUST 经过适当的清理以防止 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