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 等“花哨”的技术，但当时它们并未被广泛采用，并且将 gRPC 服务暴露到互联网上，并置于 AWS EC2 ELB 等负载均衡器之后是具有挑战性的。

远程写入协议提供了批处理的机会，例如，在单个请求中发送不同时间序列的多个样本。不期望在同一请求中频繁发送同一序列的多个样本，尽管协议支持此功能。

远程写入协议不适用于应用程序将指标推送到与 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 路径来接收指标。

时间戳必须是 int64，计为自 Unix 纪元以来的毫秒数。值必须是 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 Remote Write 兼容的发送方必须按时间戳顺序发送任何给定系列的样本。与 Prometheus Remote Write 兼容的发送方可以并行发送不同系列的多个请求。

重试与退避

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

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

过时标记

与 Prometheus remote write 兼容的发送方必须在时间序列不再追加时发送过时标记。

过时标记必须由特殊 NaN 值 0x7ff0000000000002 发出信号。此值不得用于其他用途。

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

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

超出范围

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

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

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

持久性 建议与 Prometheus Remote Write 兼容的发送方在接收方发生故障时应持久地缓冲样本数据。

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

远程读取 这是一个独立的接口，已经经历了一些迭代，使用频率较低。

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

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

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

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

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

未来计划

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

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

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

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

兼容的发送方和接收方

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

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

常见问题

你为什么不使用 gRPC？ 有趣的是，我们最初使用了 gRPC，但在 2016 年很难让它们通过 ELB，所以我们改用了基于 HTTP 的 Protos：https://github.com/prometheus/prometheus/issues/1982

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

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

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

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

本页内容