文档 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

块

您可以使用以下块配置 prometheus.remote_write

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

endpoint

endpoint 块描述了一个用于发送指标的单一位置。您可以定义多个 endpoint 块将指标发送到多个位置。

支持以下参数

最多可提供以下其中一项

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

当提供了多个 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（或其小写版本）。请求使用与其 scheme 匹配的环境变量中的代理，除非被 NO_PROXY 排除。如果配置了 proxy_from_environment，则不得配置 proxy_url 和 no_proxy。

proxy_connect_header 仅在配置了 proxy_url 或 proxy_from_environment 时才应配置。

authorization

credential 和 credentials_file 是互斥的，authorization 块中只能提供其中一个。

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

oauth

必需

sdk

必需

此块配置 Azure SDK 身份验证。

basic_auth

password 和 password_file 是互斥的，basic_auth 块中只能提供其中一个。

metadata_config

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（或其小写版本）。请求使用与其 scheme 匹配的环境变量中的代理，除非被 NO_PROXY 排除。如果配置了 proxy_from_environment，则不得配置 proxy_url 和 no_proxy。

proxy_connect_header 仅在配置了 proxy_url 或 proxy_from_environment 时才应配置。

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

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

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

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

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

retry_on_http_429 参数指定是否应将 HTTP 429 状态码响应视为可恢复错误。其他 HTTP 4xx 状态码响应绝不被视为可恢复错误。启用 retry_on_http_429 后，将遵循服务器返回的 Retry-After 响应头部。

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

sigv4

如果 region 留空，将使用默认凭证链中的区域。

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

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

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_storage_bytes_total (counter): 队列压缩后发送的数据总字节数。
• prometheus_remote_storage_enqueue_retries_total (counter): 由于 shard 队列已满而导致入队失败的总次数。
• prometheus_remote_storage_exemplars_dropped_total (counter): 在从 WAL 读取后、发送到 remote_write 之前因未知引用 ID而被丢弃的 exemplars 总数。
• prometheus_remote_storage_exemplars_failed_total (counter): 因不可恢复错误而未能发送到远程存储的 exemplars 总数。
• prometheus_remote_storage_exemplars_in_total (counter): 读取到远程存储的 exemplars 数量。
• prometheus_remote_storage_exemplars_pending (gauge): 正在 shard 中等待发送到远程存储的 exemplars 数量。
• prometheus_remote_storage_exemplars_retried_total (counter): 未能发送到远程存储但因可恢复错误而重试的 exemplars 总数。
• prometheus_remote_storage_exemplars_total (counter): 发送到远程存储的 exemplars 总数。
• prometheus_remote_storage_max_samples_per_send (gauge): 每个 shard 在单个请求中允许发送的最大样本数。
• prometheus_remote_storage_metadata_bytes_total (counter): 队列压缩后发送的元数据总字节数。
• prometheus_remote_storage_metadata_failed_total (counter): 因不可恢复错误而未能发送到远程存储的元数据条目总数。
• prometheus_remote_storage_metadata_retried_total (counter): 未能发送到远程存储但因可恢复错误而重试的元数据条目总数。
• prometheus_remote_storage_metadata_total (counter): 发送到远程存储的元数据条目总数。
• prometheus_remote_storage_queue_highest_sent_timestamp_seconds (gauge): 队列成功发送的最新 WAL 样本的 Unix 时间戳（秒）。
• prometheus_remote_storage_samples_dropped_total (counter): 在从 WAL 读取后、发送到 remote_write 之前因未知引用 ID而被丢弃的样本总数。
• prometheus_remote_storage_samples_failed_total (counter): 因不可恢复错误而未能发送到远程存储的样本总数。
• prometheus_remote_storage_samples_in_total (counter): 读取到远程存储的样本数量。
• prometheus_remote_storage_samples_pending (gauge): 正在 shard 中等待发送到远程存储的样本数量。
• prometheus_remote_storage_samples_retries_total (counter): 未能发送到远程存储但因可恢复错误而重试的样本总数。
• prometheus_remote_storage_samples_total (counter): 发送到远程存储的样本总数。
• prometheus_remote_storage_sent_batch_duration_seconds (histogram): 发送到远程存储的发送调用持续时间。
• prometheus_remote_storage_shard_capacity (gauge): 给定队列中 shard 的容量。
• prometheus_remote_storage_shards_desired (gauge): 队列为了跟上传入指标数量而希望运行的 shard 数量。
• prometheus_remote_storage_shards_max (gauge): 队列被允许运行的最大 shard 数量。
• prometheus_remote_storage_shards_min (gauge): 队列被允许运行的最小 shard 数量。
• prometheus_remote_storage_shards (gauge): 用于并发向端点传输指标的 shard 数量。
• prometheus_remote_write_wal_exemplars_appended_total (counter): 追加到 WAL 的 exemplars 总数。
• prometheus_remote_write_wal_out_of_order_samples_total (counter): 乱序样本摄取失败尝试的总次数。
• prometheus_remote_write_wal_samples_appended_total (counter): 追加到 WAL 的样本总数。
• prometheus_remote_write_wal_storage_active_series (gauge): WAL 当前跟踪的活跃系列数量。
• prometheus_remote_write_wal_storage_created_series_total (counter): 追加到 WAL 的已创建系列总数。
• prometheus_remote_write_wal_storage_deleted_series (gauge): 当前标记为从内存中删除的系列数量。
• prometheus_remote_write_wal_storage_removed_series_total (counter): 从 WAL 中移除的系列总数。

示例

以下示例展示了如何创建 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 实例发送了哪些指标系列。例如

   text 复制

   ./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 中缓冲接收到的指标。网络中断解决后，队列 shard 可以使用 WAL 并将缓冲的指标刷新到端点。

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

每次截断时，WAL 会删除对不再存在的系列的引用，并对自上次截断周期以来写入的 segments 中大约最旧的三分之二（向下取整到最接近的整数）进行检查点。检查点意味着 WAL 只跟踪每个现有指标系列的唯一标识符，并且不能再使用这些样本进行远程写入。如果该数据尚未推送到远程端点，则会丢失。

这种行为决定了 prometheus.remote_write 组件的数据保留策略。这也意味着无法将数据保留与数据本身的年龄直接关联，因为截断逻辑是针对 segments 而不是样本本身工作的。这使得当组件接收到非一致性速率的数据时，数据保留变得不太可预测。

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 更旧的样本将被强制移除。

远程写入长时间中断

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

如果远程写入中断时间长于 max_keepalive_time 参数，则 WAL 将被截断，并且最旧的数据会丢失。

远程写入间歇性中断

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

落后

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

调整 max_shards

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

Alloy 尽量不使用过多的 shard，但如果队列落后，远程写入组件会增加 shard 的数量，最多达到 max_shards，以提高吞吐量。过多的 shard 可能会压垮远程端点或增加 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 暴露了一些指标，可用于监控远程写入 shard

• prometheus_remote_storage_shards_desired (gauge): 队列为了跟上传入指标数量而希望运行的 shard 数量。
• prometheus_remote_storage_shards_max (gauge): 队列被允许运行的最大 shard 数量。
• prometheus_remote_storage_shards_min (gauge): 队列被允许运行的最小 shard 数量。
• prometheus_remote_storage_shards (gauge): 用于并发向端点传输指标的 shard 数量。

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

text 复制

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 segments 仍在写入磁盘时意外停止时，可能会发生 WAL 损坏。例如，主机计算机发生一般性磁盘故障并在您停止 Alloy 和其他正在运行的服务之前崩溃。当您重新启动 Alloy 时，它会验证 WAL，移除发现的任何损坏的 segments。有时，这种修复不成功，您必须手动删除损坏的 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 的组件