Prometheus Remote-Write 1.0 规范

版本：1.0
状态：已发布
日期：2023 年 4 月

本文档旨在定义和标准化现有已广泛且自发采纳的协议的 API、传输格式、协议和语义，而非提出任何新内容。

远程写入规范旨在记录 Prometheus 和兼容 Prometheus 远程写入的代理如何将数据发送到 Prometheus 或兼容 Prometheus 远程写入的接收器的标准。

本文档中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”应按照 RFC 2119 中的描述进行解释。

注意本规范有一个 2.0 版本可用，请参见此处。

简介

背景

远程写入协议旨在实现将样本从发送方可靠地实时传播到接收方，且不发生数据丢失。

远程写入协议设计为无状态的；消息之间严格没有通信。因此，该协议不被视为“流式”。为实现流式效果，应通过同一连接（例如使用 HTTP/1.1 或 HTTP/2）发送多个消息。曾考虑过如 gRPC 这样的“高级”技术，但当时并未广泛采用，并且在负载均衡器（如 AWS EC2 ELB）后暴露 gRPC 服务具有挑战性。

远程写入协议提供了批处理的机会，例如，在单个请求中为不同的序列发送多个样本。虽然协议支持，但不期望在同一请求中普遍为同一序列发送多个样本。

远程写入协议不适用于应用程序将指标推送到兼容 Prometheus 远程写入的接收器。其意图是让兼容 Prometheus 远程写入的发送方抓取已插桩的应用程序或导出器，并将远程写入消息发送到服务器。

测试套件可在 https://github.com/prometheus/compliance/tree/main/remotewrite/sender 找到。

术语表

为本文档之目的，必须遵循以下定义：

“发送方”是发送 Prometheus 远程写入数据的实体。
“接收方”是接收 Prometheus 远程写入数据的实体。
“样本”是一对（时间戳，值）。
“标签”是一对（键，值）。
“序列”是由一组唯一标签标识的样本列表。

定义

协议

远程写入协议必须由具有以下签名的 RPC 组成：

func Send(WriteRequest)

message WriteRequest {
  repeated TimeSeries timeseries = 1;
  // Cortex uses this field to determine the source of the write request.
  // We reserve it to avoid any compatibility issues.
  reserved  2;

  // Prometheus uses this field to send metadata, but this is
  // omitted from v1 of the spec as it is experimental.
  reserved  3;
}

message TimeSeries {
  repeated Label labels   = 1;
  repeated Sample samples = 2;
}

message Label {
  string name  = 1;
  string value = 2;
}

message Sample {
  double value    = 1;
  int64 timestamp = 2;
}

远程写入发送方必须将写入请求编码在 HTTP POST 请求的主体中，并通过 HTTP 发送到接收方提供的 URL 路径。接收方可以指定任何 HTTP URL 路径来接收指标。

时间戳必须是自 Unix 纪元以来的毫秒数，类型为 int64。值必须是 float64。

HTTP 请求中必须发送以下标头：

Content-Encoding: snappy
Content-Type: application/x-protobuf
User-Agent: <发送方的名称和版本>
X-Prometheus-Remote-Write-Version: 0.1.0

客户端可以允许用户发送自定义 HTTP 标头；它们不得允许用户配置以发送保留的标头。更多信息请参见 https://github.com/prometheus/prometheus/pull/8416。

HTTP POST 主体中的远程写入请求必须使用 Google 的 Snappy 进行压缩。必须使用块格式——不得使用帧格式。

远程写入请求必须使用 Google Protobuf 3 进行编码，并且必须使用上面定义的模式。请注意，Prometheus 的实现使用了 gogoproto 优化——对于非 Golang 编写的接收器，gogoproto 类型可以替换为等效的逐行类型。

远程写入接收方的响应主体应为空；客户端必须忽略响应主体。响应主体保留供将来使用。

向后和向前兼容性

该协议遵循语义化版本 2.0：任何兼容 1.x 的接收器必须能够读取任何兼容 1.x 的发送方，依此类推。破坏性/向后不兼容的更改将导致规范的 2.x 版本。

proto 格式本身在某些方面是向前/向后兼容的：

从 proto 中删除字段将意味着主版本号的提升。
添加（可选）字段将是次要版本号的提升。

协商

发送方必须在标头中发送版本号。
接收方可以在响应头（“X-Prometheus-Remote-Write-Version”）中返回其支持的最高版本号。
希望以 >1.x 格式发送的发送方必须首先发送一个空的 1.x 请求，并查看响应是否表明接收方支持其他版本。发送方可以使用任何受支持的版本。如果响应中没有版本头，发送方必须假定仅兼容 1.x。

排序

兼容 Prometheus 远程写入的发送方必须按时间戳顺序发送任何给定序列的样本。兼容 Prometheus 远程写入的发送方可以并行发送不同序列的多个请求。

重试与退避

兼容 Prometheus 远程写入的发送方必须在收到 HTTP 5xx 响应时重试写入请求，并且必须使用退避算法以防止压垮服务器。它们不得在收到 HTTP 2xx 和 4xx 响应时重试，但 429 除外。它们可以在收到 HTTP 429 响应时重试，如果服务器跟不上，这可能导致发送方“落后”。这样做是为了确保在服务器端出现错误时数据不会丢失，在客户端出现错误时能够取得进展。

兼容 Prometheus 远程写入的接收方必须在写入成功时响应 HTTP 2xx 状态码。当写入失败且应重试时，它们必须响应 HTTP 状态码 5xx。当请求无效、永远无法成功且不应重试时，它们必须响应 HTTP 状态码 4xx。

过时标记

当一个时间序列不再被追加数据时，兼容 Prometheus 远程写入的发送方必须发送过时标记。

过时标记必须通过特殊的 NaN 值 0x7ff0000000000002 来表示。此值不得用于其他目的。

通常，发送方可以通过以下技术检测时间序列何时不再被追加数据：

通过服务发现检测到暴露该序列的目标已经消失
注意到目标在连续的抓取之间不再暴露该时间序列
无法抓取最初暴露该时间序列的目标
跟踪记录和告警规则的配置和评估

范围之外

本文档不打算解释一个完全兼容 Prometheus 的监控系统所需的所有功能。特别是，以下领域超出了规范第一版的范围：

"up" 指标 "up" 指标的定义和语义超出了远程写入协议的范围，应单独记录。

HTTP 路径 HTTP 处理程序的路径可以是任何东西——并且必须由发送方提供。通常我们期望整个 URL 在配置中指定。

持久化 建议兼容 Prometheus 远程写入的发送方应在接收方发生故障时持久化缓冲样本数据。

认证与加密 由于远程写入使用 HTTP，我们认为认证与加密是传输层的问题。发送方和接收方应支持所有常见的选项（基本认证、TLS 等），并可自由添加潜在的自定义认证选项。不应假定 Prometheus 远程写入发送方和最终代理支持自定义认证，但我们将努力支持常见且广泛使用的认证协议，在可行的情况下。

远程读取 这是一个独立的接口，已经进行了一些迭代，使用范围较小。

分片 Prometheus 中用于远程写入并行化的当前分片方案很大程度上是实现细节，不属于规范的一部分。当发送方确实实现并行化时，它们必须保留每个序列的样本顺序。

回填规范没有对可以推送多旧的序列设置限制，但可能存在特定于服务器/实现的约束。

限制对标签数量和长度、批处理大小等的限制超出了本文档的范围，但预计实现将施加合理的限制。

基于推送的 Prometheus 应用程序将指标推送到兼容 Prometheus 远程写入的接收方不是该系统的设计目标，应在单独的文档中探讨。

标签每个序列可以包含一个“job”和/或“instance”标签，因为这些通常由发送方的服务发现添加。这些不是强制性的。

未来计划

本节包含推测性计划，不被视为协议规范的一部分，但在此提及以求完整。

事务性 Prometheus 旨在实现“事务性”——即从不向查询暴露部分抓取的目标。我们打算在远程写入中也这样做——例如，将来我们希望将远程写入与抓取“对齐”，也许使得单个抓取的所有样本、元数据和范例都在单个远程写入请求中发送。这还有待设计。

元数据和范例与上述一致，我们还随抓取的样本一起发送元数据（类型信息、帮助文本）和范例。我们计划将这些打包到单个远程写入请求中——规范的未来版本可能会坚持这一点。Prometheus 目前对发送元数据和范例有实验性支持。

优化我们希望研究各种优化，通过消除标签名称和值的重复来减少消息大小。

兼容的发送方和接收方

该规范旨在描述以下组件如何交互（截至 2023 年 4 月）：

Prometheus (作为“发送方”和“接收方”)
Avalanche（作为“发送方”）- 一种 Prometheus 指标的负载测试工具。
Cortex (作为“接收方”)
Elastic Agent (作为“接收方”)
Grafana Agent (作为“发送方”和“接收方”)
GreptimeDB（作为“接收方”）
InfluxData 的 Telegraf 代理。（作为发送方，和作为接收方）
M3 (作为“接收方”)
Mimir (作为“接收方”)
OpenTelemetry Collector（作为“发送方”并最终作为“接收方”）
Thanos (作为“接收方”)
Vector（作为“发送方”和“接收方”）
VictoriaMetrics（作为“接收方”）

常见问题

为什么不使用 gRPC？ 有趣的是，我们最初确实使用了 gRPC，但后来切换到基于 HTTP 的 Protos，因为在 2016 年很难让它们通过 ELB： https://github.com/prometheus/prometheus/issues/1982

为什么不是流式 protobuf 消息？ 如果你使用持久的 HTTP/1.1 连接，它们非常接近流式… 当然，头部必须重新发送，但这比新的 TCP 建立开销要小。

为什么我们按顺序发送样本？ 顺序约束来自于我们在 Prometheus 中用于时间序列数据的编码方式，该实现是只追加的。可以移除此约束，例如通过缓冲样本并在编码前重新排序。我们可以在协议的未来版本中研究这一点。

如何在顺序约束下并行化请求？ 样本必须是按顺序的，但仅限于给定的序列。只要它们是针对不同序列的，远程写入请求就可以并行发送。在 Prometheus 中，我们通过标签将样本分片到不同的队列中，然后在每个队列中顺序进行写入。这保证了同一序列的样本按顺序交付，但不同序列的样本是并行发送的——并且可能在不同序列之间是“乱序”的。

我们认为这是必要的，因为即使接收方可以支持乱序样本，我们也不能让代理发送乱序，因为它们将永远无法发送到 Prometheus、Cortex 和 Thanos。我们这样做是为了确保生态系统的完整性，并防止社区混淆/分裂成“可以写入 Prometheus 的 prometheus 代理”和那些不能的代理。

本页内容