文档 Grafana Alloy 参考 组件 prometheus prometheus.remote_write

prometheus.remote_write

prometheus.remote_write 组件收集来自其他组件的指标，并将它们放入预写式日志 (WAL) 中，然后通过网络将它们转发到一系列用户提供的端点。指标通过网络使用 Prometheus Remote Write 协议 发送。

可以指定多个 prometheus.remote_write 组件，方法是为它们提供不同的标签。

用法

alloy 复制

prometheus.remote_write "LABEL" {
  endpoint {
    url = REMOTE_WRITE_URL

    ...
  }

  ...
}

参数

支持以下参数

块

在 prometheus.remote_write 的定义中，支持以下块

> 符号表示更深层次的嵌套。例如，endpoint > basic_auth 指的是在 endpoint 块内定义的 basic_auth 块。

endpoint 块

endpoint 块描述了将指标发送到的单个位置。可以提供多个 endpoint 块以将指标发送到多个位置。

支持以下参数

以下项中最多只能提供一个

• bearer_token 参数.
• bearer_token_file 参数.
• basic_auth 块.
• authorization 块.
• oauth2 块.
• sigv4 块.
• azuread 块.

当提供多个 endpoint 块时，指标会并发发送到所有配置的位置。每个端点都有一个队列，用于从 WAL 读取指标并将它们排队以进行发送。可以使用 queue_config 块自定义队列的行为。

可以使用 name 参数命名端点，以便在调试指标中更易于识别。如果未提供 name 参数，则会根据端点设置的哈希值生成名称。

当 send_native_histograms 为 true 时，发送到 prometheus.remote_write 的原生 Prometheus 直方图样本将转发到配置的端点。如果端点不支持接收原生直方图样本，则推送指标将失败。

no_proxy 可以包含 IP、CIDR 表示法和域名。IP 和域名可以包含端口号。如果配置了 no_proxy，则必须配置 proxy_url。

proxy_from_environment 使用环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY（或小写版本）。请求使用环境变量中与其方案匹配的代理，除非被 NO_PROXY 排除。如果配置了 proxy_from_environment，则不得配置 proxy_url 和 no_proxy。

只有在配置了 proxy_url 或 proxy_from_environment 的情况下，才应配置 proxy_connect_header。

basic_auth 块

password 和 password_file 是互斥的，并且在一个 basic_auth 块内只能提供一个。

authorization 块

credential 和 credentials_file 是互斥的，并且在一个 authorization 块内只能提供一个。

oauth2 块

client_secret 和 client_secret_file 是互斥的，并且在一个 oauth2 块内只能提供一个。

oauth2 块也可能包含一个单独的 tls_config 子块。

no_proxy 可以包含 IP、CIDR 表示法和域名。IP 和域名可以包含端口号。如果配置了 no_proxy，则必须配置 proxy_url。

proxy_from_environment 使用环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY（或小写版本）。请求使用环境变量中与其方案匹配的代理，除非被 NO_PROXY 排除。如果配置了 proxy_from_environment，则不得配置 proxy_url 和 no_proxy。

只有在配置了 proxy_url 或 proxy_from_environment 的情况下，才应配置 proxy_connect_header。

sigv4 块

如果 region 留空，则使用来自默认凭证链的区域。

如果 access_key 留空，则使用环境变量 AWS_ACCESS_KEY_ID。

如果 secret_key 留空，则使用环境变量 AWS_SECRET_ACCESS_KEY。

azuread 块

cloud 支持的值为

• "AzurePublic"
• "AzureChina"
• "AzureGovernment"

managed_identity 块

client_id 应为有效 UUID，格式为以下受支持的格式之一

• xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Microsoft 编码：{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
• 原始十六进制编码：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

tls_config 块

以下参数对是互斥的，不能同时设置

• ca_pem 和 ca_file
• cert_pem 和 cert_file
• key_pem 和 key_file

配置客户端身份验证时，必须同时提供客户端证书（使用 cert_pem 或 cert_file）和客户端密钥（使用 key_pem 或 key_file）。

当未提供 min_version 时，最低可接受的 TLS 版本继承自 Go 的默认最低版本 TLS 1.2。如果提供了 min_version，则必须将其设置为以下字符串之一

• "TLS10" (TLS 1.0)
• "TLS11" (TLS 1.1)
• "TLS12" (TLS 1.2)
• "TLS13" (TLS 1.3)

queue_config 块

然后，每个队列管理多个并发分片，这些分片负责将其数据的一部分发送到各自的端点。如果样本未被足够快地发送到端点，则分片数量会自动增加。可以使用 min_shards 和 max_shards 参数配置允许的分片范围。有关如何配置 max_shards 的更多信息，请参阅 调整 max_shards。

每个分片都有一个样本缓冲区，它将样本保存在内存中，这由 capacity 参数控制。除非至少有一个分片未达到最大容量，否则不会从 WAL 读取新指标。

在分片达到 max_samples_per_send 指定的样本数之后，或者自该分片上次刷新以来经过了 batch_send_deadline 指定的持续时间之后，分片的缓冲区将被刷新并发送到端点。

分片会重试因可恢复错误而失败的请求。如果服务器响应 HTTP 5xx 状态代码，则错误是可恢复的。可以使用 min_backoff 和 max_backoff 参数自定义重试之间的延迟。

retry_on_http_429 参数指定是否应将 HTTP 429 状态代码响应视为可恢复的错误；其他 HTTP 4xx 状态代码响应永远不会被视为可恢复的错误。启用 retry_on_http_429 后，将遵循来自服务器的 Retry-After 响应标头。

sample_age_limit 参数指定要发送的样本的最大年龄。任何超过限制的样本都将被丢弃，并且不会发送到远程存储。默认值为 0s，这意味着将发送所有样本（禁用该功能）。

metadata_config 块

write_relabel_config 块

write_relabel_config 块包含可应用于输入指标的任何重新标记规则的定义。如果定义了多个 write_relabel_config 块，则转换将按自上而下的顺序应用。

以下参数可用于配置 write_relabel_config。所有参数都是可选的。省略的字段采用其默认值。

您可以使用以下操作

• drop - 删除 regex 与使用 source_labels 和 separator 提取的字符串匹配的指标。
• dropequal - 删除串联的 source_labels 与 target_label 匹配的目标。
• hashmod - 哈希串联的标签，计算其模数 modulus，并将结果写入 target_label。
• keep - 保留 regex 与使用 source_labels 和 separator 提取的字符串匹配的指标。
• keepequal - 删除串联的 source_labels 与 target_label 不匹配的目标。
• labeldrop - 将 regex 与所有标签名称匹配。任何匹配的标签都将从指标的标签集中删除。
• labelkeep - 将 regex 与所有标签名称匹配。任何不匹配的标签都将从指标的标签集中删除。
• labelmap - 将 regex 与所有标签名称匹配。任何匹配的标签都将根据 replacement 字段的内容重命名。
• lowercase - 将 target_label 设置为串联的 source_labels 的小写形式。
• replace - 将 regex 与串联的标签匹配。如果存在匹配项，它将使用 replacement 字段的内容替换 target_label 的内容。
• uppercase - 将 target_label 设置为串联的 source_labels 的大写形式。

wal 块

wal 块自定义预写式日志 (WAL)，用于在将指标发送到配置的端点集之前临时存储指标。

WAL 主要有两个用途

• 在发生间歇性网络问题时缓冲未发送的指标。
• 在进程重启后填充内存缓存。

WAL 位于 Alloy 配置使用的存储路径的组件特定目录中。有关如何更改存储路径，请参阅 run 文档。

truncate_frequency 参数配置清理 WAL 的频率。每次 truncate_frequency 周期过去后，WAL 中较低的三分之二的数据将被删除，并且不再可用于发送。

当 WAL 清理开始时，最低成功发送的时间戳用于确定可以从 WAL 中安全删除多少数据。min_keepalive_time 和 max_keepalive_time 控制 WAL 中允许的数据年龄范围；样本只有在至少与 min_keepalive_time 一样旧时才会被删除，如果样本早于 max_keepalive_time，则会被强制删除。

导出的字段

导出以下字段，并且可以被其他组件引用

组件健康状况

只有在 prometheus.remote_write 配置无效时，它才会被报告为不健康。在这些情况下，导出的字段将保留其上次健康的值。

调试信息

prometheus.remote_write 不公开任何组件特定的调试信息。

调试指标

• prometheus_remote_write_wal_storage_active_series (gauge)：WAL 跟踪的当前活动序列数。
• prometheus_remote_write_wal_storage_deleted_series (gauge)：当前标记为从内存中删除的序列数。
• prometheus_remote_write_wal_out_of_order_samples_total (counter)：乱序样本摄取失败尝试的总数。
• prometheus_remote_write_wal_storage_created_series_total (counter)：追加到 WAL 的已创建序列总数。
• prometheus_remote_write_wal_storage_removed_series_total (counter)：从 WAL 中删除的序列总数。
• prometheus_remote_write_wal_samples_appended_total (counter)：追加到 WAL 的样本总数。
• prometheus_remote_write_wal_exemplars_appended_total (counter)：追加到 WAL 的 Exemplars 总数。
• prometheus_remote_storage_samples_total (counter)：发送到远程存储的样本总数。
• prometheus_remote_storage_exemplars_total (counter)：发送到远程存储的 Exemplars 总数。
• prometheus_remote_storage_metadata_total (counter)：发送到远程存储的元数据条目总数。
• prometheus_remote_storage_samples_failed_total (counter)：由于不可恢复的错误而未能发送到远程存储的样本总数。
• prometheus_remote_storage_exemplars_failed_total (counter)：由于不可恢复的错误而未能发送到远程存储的 Exemplars 总数。
• prometheus_remote_storage_metadata_failed_total (counter)：由于不可恢复的错误而未能发送到远程存储的元数据条目总数。
• prometheus_remote_storage_samples_retries_total (counter)：由于可恢复的错误而未能发送到远程存储但已重试的样本总数。
• prometheus_remote_storage_exemplars_retried_total (counter)：由于可恢复的错误而未能发送到远程存储但已重试的 Exemplars 总数。
• prometheus_remote_storage_metadata_retried_total (counter)：由于可恢复的错误而未能发送到远程存储但已重试的元数据条目总数。
• prometheus_remote_storage_samples_dropped_total (counter)：由于未知引用 ID 而在从 WAL 读取后但在发送到 remote_write 之前被丢弃的样本总数。
• prometheus_remote_storage_exemplars_dropped_total (counter)：由于未知引用 ID 而在从 WAL 读取后但在发送到 remote_write 之前被丢弃的 Exemplars 总数。
• prometheus_remote_storage_enqueue_retries_total (counter)：由于分片的队列已满而导致入队失败的总次数。
• prometheus_remote_storage_sent_batch_duration_seconds (histogram)：发送到远程存储的调用的持续时间。
• prometheus_remote_storage_queue_highest_sent_timestamp_seconds (gauge)：队列成功发送的最新 WAL 样本的 Unix 时间戳。
• prometheus_remote_storage_samples_pending (gauge)：等待在分片中发送到远程存储的样本数。
• prometheus_remote_storage_exemplars_pending (gauge): 发往远程存储的碎片中待处理的 Exemplar 数量。
• prometheus_remote_storage_shard_capacity (gauge): 给定队列中碎片的容量。
• prometheus_remote_storage_shards (gauge): 用于并发交付指标到端点的碎片数量。
• prometheus_remote_storage_shards_min (gauge): 队列允许运行的最小碎片数量。
• prometheus_remote_storage_shards_max (gauge): 队列允许运行的最大碎片数量。
• prometheus_remote_storage_shards_desired (gauge): 队列为了跟上指标流入量而想要运行的碎片数量。
• prometheus_remote_storage_bytes_total (counter): 队列压缩后发送的数据总字节数。
• prometheus_remote_storage_metadata_bytes_total (counter): 队列压缩后发送的元数据总字节数。
• prometheus_remote_storage_max_samples_per_send (gauge): 每个碎片在单个请求中允许发送的最大样本数。
• prometheus_remote_storage_samples_in_total (counter): 读取到远程存储的样本数。
• prometheus_remote_storage_exemplars_in_total (counter): 读取到远程存储的 Exemplar 数量。

示例

以下示例展示了如何创建 prometheus.remote_write 组件，以将指标发送到不同的目标。

将指标发送到本地 Mimir 实例

您可以创建一个 prometheus.remote_write 组件，将您的指标发送到本地 Mimir 实例

alloy 复制

prometheus.remote_write "staging" {
  // Send metrics to a locally running Mimir.
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}

// Configure a prometheus.scrape component to send metrics to
// prometheus.remote_write component.
prometheus.scrape "demo" {
  targets = [
    // Collect metrics from the default HTTP listen address.
    {"__address__" = "127.0.0.1:12345"},
  ]
  forward_to = [prometheus.remote_write.staging.receiver]
}

将指标发送到指定租户的 Mimir 实例

您可以创建一个 prometheus.remote_write 组件，将您的指标发送到 Mimir 实例内的特定租户。当您的 Mimir 实例使用多个租户时，这非常有用

alloy 复制

prometheus.remote_write "staging" {
  // Send metrics to a Mimir instance
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    headers = {
      "X-Scope-OrgID" = "staging",
    }
  }
}

将指标发送到托管服务

您可以创建一个 prometheus.remote_write 组件，将您的指标发送到托管服务，例如 Grafana Cloud。在本示例中，Prometheus 用户名和 Grafana Cloud API 密钥通过环境变量注入。

alloy 复制

prometheus.remote_write "default" {
  endpoint {
    url = "https://prometheus-xxx.grafana.net/api/prom/push"
      basic_auth {
        username = sys.env("PROMETHEUS_USERNAME")
        password = sys.env("GRAFANA_CLOUD_API_KEY")
      }
  }
}

故障排除

乱序错误

您有时可能会在 Alloy 日志文件中看到“乱序”错误。这意味着 Alloy 发送的指标样本的时间戳比数据库已经摄取的样本的时间戳更旧。如果您的数据库是 Mimir，则 Mimir 错误的确切名称是 err-mimir-sample-out-of-order。

此错误最常见的原因是多个 Alloy 实例抓取相同的目标。要进行故障排除，请按顺序执行以下步骤

1. 如果您使用集群，请检查错误记录时 Alloy 实例的数量是否发生变化。这是唯一一种正常情况下会遇到乱序错误的情况。该错误只会持续很短的时间，直到集群稳定并且所有 Alloy 实例都有一个新的目标列表。由于集群稳定所需的时间预期远小于抓取间隔，因此这不是一个真正的问题。如果您看到的乱序错误与集群收集器的伸缩无关，则必须对其进行调查。
2. 检查是否有不应运行的活动 Alloy 实例。可能存在一个较旧的 Alloy 实例，该实例在新实例启动之前未关闭。
3. 检查配置，看看是否可能有多个 Alloy 实例抓取相同的目标。
4. 检查 WAL 以查看哪个 Alloy 实例发送了这些指标样本。WAL 位于由 run 命令 --storage.path 参数设置的目录中。您可以使用 Promtool 来检查它，并找出自上次 WAL 截断事件以来，哪个指标序列由此 Alloy 实例发送。例如
   复制

   ./promtool tsdb dump --match='{__name__="otelcol_connector_spanmetrics_duration_seconds_bucket", http_method="GET", job="ExampleJobName"}' /path/to/wal/

技术细节

prometheus.remote_write 使用 snappy 进行压缩。

任何以 __ 开头的标签都将在发送到端点之前被删除。

数据保留

prometheus.remote_write 组件使用预写日志 (WAL) 来防止网络中断期间的数据丢失。该组件为每个配置的端点将接收到的指标缓冲到 WAL 中。队列碎片可以在网络中断解决后使用 WAL，并将缓冲的指标刷新到端点。

WAL 将指标记录在 128 MB 的文件中，称为段。为了避免 WAL 在磁盘上无限增长，该组件会在设定的时间间隔截断其段。

在每次截断时，WAL 删除对不再存在的序列的引用，并检查点自上次截断期间写入它的大约最旧的三分之二的段（向下舍入到最接近的整数）。检查点意味着 WAL 仅跟踪每个现有指标序列的唯一标识符，并且不能再将样本用于远程写入。如果该数据尚未推送到远程端点，则会丢失。

此行为决定了 prometheus.remote_write 组件的数据保留。这也意味着不可能将数据保留直接与数据年龄本身相关联，因为截断逻辑作用于段，而不是样本本身。当组件接收到不一致的数据速率时，这使得数据保留变得不太可预测。

WAL 块包含一些可配置的参数，这些参数可用于控制内存使用、磁盘使用和数据保留之间的权衡。

truncate_frequency 或 wal_truncate_frequency 参数配置截断发生的间隔。较低的值会导致内存使用量减少，但也为长时间中断提供的弹性较小。

当 WAL 清理开始时，最近成功发送的时间戳将用于确定可以从 WAL 中安全删除多少数据。min_keepalive_time 或 min_wal_time 控制被认为可以删除的样本的最小年龄。不会删除比 min_keepalive_time 更新的样本。max_keepalive_time 或 max_wal_time 控制可以保留在 WAL 中的样本的最大年龄。早于 max_keepalive_time 的样本将被强制删除。

扩展的 remote_write 中断

当远程写入端点在一段时间内无法访问时，最近成功发送的时间戳不会更新。min_keepalive_time 和 max_keepalive_time 参数控制 WAL 中保留的数据的年龄范围。

如果远程写入中断时间超过 max_keepalive_time 参数，则 WAL 将被截断，并且最早的数据将丢失。

间歇性 remote_write 中断

如果远程写入端点是间歇性可访问的，则每次连接成功时都会更新最近成功发送的时间戳。成功的连接会更新与 min_keepalive_time 的系列比较，并在下一个 truncate_frequency 间隔触发截断，这将检查点自上次截断以来写入的三分之二的段（向下舍入到最接近的整数）。

落后

如果队列碎片无法足够快地刷新数据以跟上 WAL 中缓冲的最新数据，我们称该组件“落后”。组件暂时落后 2 或 3 个抓取间隔并不罕见。如果组件落后于自上次截断间隔以来写入的数据的三分之一以上，则截断循环可能会在数据被推送到 remote_write 端点之前检查点数据。

调整 max_shards

queue_config 块允许您配置 max_shards。max_shards 是并发碎片的最大数量，这些碎片将样本发送到 Prometheus 兼容的远程写入端点。对于每个碎片，单个远程写入请求最多可以发送 max_samples_per_send 个样本。

Alloy 会尽量不使用太多碎片，但如果队列落后，远程写入组件会将碎片数量增加到 max_shards 以提高吞吐量。大量的碎片可能会使远程端点不堪重负，或增加 Alloy 的内存利用率。因此，重要的是将 max_shards 调整到一个合理的值，该值足以跟上要发送到远程端点的积压数据，而又不会使其不堪重负。

Alloy 在远程写入时可以实现的最大吞吐量等于 max_shards * max_samples_per_send * <1 / 平均写入请求延迟>。例如，以默认配置 50 个 max_shards 和 2000 个 max_samples_per_send 运行 Alloy，并假设远程写入请求的平均延迟为 500 毫秒，则可实现的最大吞吐量约为 50 * 2000 * (1 秒 / 500 毫秒) = 20 万个样本/秒。

默认的 max_shards 配置适用于大多数用例，尤其是当每个 Alloy 实例抓取最多 100 万个活动序列时。但是，如果您大规模运行 Alloy 并且每个实例抓取超过 100 万个序列，我们建议增加 max_shards 的值。

Alloy 公开了一些指标，您可以使用这些指标来监控远程写入碎片

• prometheus_remote_storage_shards (gauge): 用于并发交付指标到端点的碎片数量。
• prometheus_remote_storage_shards_min (gauge): 队列允许运行的最小碎片数量。
• prometheus_remote_storage_shards_max (gauge): 队列允许运行的最大碎片数量。
• prometheus_remote_storage_shards_desired (gauge): 队列为了跟上指标流入量而想要运行的碎片数量。

如果您已经运行 Alloy，一个经验法则是将 max_shards 设置为碎片利用率的 4 倍。使用上面解释的指标，您可以运行以下 PromQL 即时查询，以计算每个远程写入端点 url 的建议 max_shards 值

复制

clamp_min(
    (
        # Calculate the 90th percentile desired shards over the last seven-day period.
        # If you're running Alloy for less than seven days, then
        # reduce the [7d] period to cover only the time range since when you deployed it.
        ceil(quantile_over_time(0.9, prometheus_remote_storage_shards_desired[7d]))

        # Add room for spikes.
        * 4
    ),
    # We recommend setting max_shards to a value of no less than 50, as in the default configuration.
    50
)

如果您尚未运行 Alloy，我们建议使用默认的 max_shards 运行它，然后使用上面提到的 PromQL 即时查询来计算建议的 max_shards。

WAL 损坏

当 Alloy 在最新的 WAL 段仍在写入磁盘时意外停止时，可能会发生 WAL 损坏。例如，主机计算机发生一般磁盘故障并在您停止 Alloy 和其他正在运行的服务之前崩溃。当您重新启动 Alloy 时，它会验证 WAL，删除它找到的任何损坏的段。有时，此修复不成功，您必须手动删除损坏的 WAL 才能继续。如果 WAL 损坏，Alloy 会将诸如 err="failed to find segment for index" 之类的错误消息写入日志文件。

要删除损坏的 WAL

1. 停止 Alloy。

2. 查找并删除 wal 目录的内容。

   默认情况下，wal 目录是位于 Alloy 工作目录中的 data-alloy 目录的子目录。WAL 数据目录可能与默认目录不同，具体取决于 命令行标志 --storage-path 指定的路径。

   注意

   每个 prometheus.remote_write 组件都有一个 wal 目录。

3. 启动 Alloy 并验证 WAL 是否正常工作。

兼容组件

prometheus.remote_write 具有可以被以下组件使用的导出

• 使用 Prometheus MetricsReceiver 的组件