Prometheus 远程写入规范

  • 版本：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 进行编码，并且必须使用上面定义的 schema。请注意，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 兼容性。

标签

必须随每个样本发送完整的标签集。更重要的是，与样本关联的标签集

  • 应包含 __name__ 标签。
  • 不得包含重复的标签名称。
  • 必须使标签名称按字典顺序排序。
  • 不得包含任何空标签名称或值。

发送器必须仅发送有效的指标名称、标签名称和标签值

  • 指标名称必须符合正则表达式 [a-zA-Z_:]([a-zA-Z0-9_:])*。
  • 标签名称必须符合正则表达式 [a-zA-Z_]([a-zA-Z0-9_])*。
  • 标签值可以是任何 UTF-8 字符序列。

接收器可以对标签的数量和长度施加限制，但这将是接收器特定的，并且超出本文档的范围。

以“__”开头的标签名称保留供系统使用，不应使用，请参阅 Prometheus 数据模型。

远程写入接收器可以摄取写入请求中的有效样本，该请求在其他方面包含无效样本。对于包含任何无效样本的写入请求，接收器必须返回 HTTP 400 状态代码（“错误请求”）。接收器应在响应正文中提供人类可读的错误消息。发送器不得尝试解释错误消息，而应按原样记录它。

排序

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

重试 & 退避

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

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

过时标记

当时间序列将不再追加时，Prometheus 远程写入兼容的发送器必须发送过时标记。

过时标记必须由特殊的 NaN 值 0x7ff0000000000002 指示。此值不得以其他方式使用。

通常，发送器可以使用以下技术检测到时间序列将不再追加到

  1. 使用服务发现检测到暴露序列的目标已消失
  2. 注意到目标在连续抓取之间不再暴露时间序列
  3. 未能抓取最初暴露时间序列的目标
  4. 跟踪记录和告警规则的配置和评估

范围外

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

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

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

持久性 建议 Prometheus 远程写入兼容的发送器在接收器发生中断时应持久缓冲样本数据。

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

远程读取 这是一个单独的接口，已经过多次迭代，并且使用较少。

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

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

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

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

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

未来计划

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

事务性 Prometheus 的目标是“事务性” - 即，永远不要向查询公开部分抓取的目标。我们打算对远程写入执行相同的操作 - 例如，将来我们希望将远程写入与抓取“对齐”，也许这样，单个抓取的所有样本、元数据和范例都将在单个远程写入请求中发送。这还有待设计。

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

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

兼容的发送器和接收器

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

常见问题解答

为什么不使用 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-agents”和不能写入的 prometheus-agents。

本文档是开源的。请提交问题或拉取请求，以帮助改进它。