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

prometheus.remote_write

prometheus.remote_write 从其他组件收集指标，并将它们写入预写日志（WAL），然后通过网络将它们转发到一系列用户提供的端点。指标通过网络使用 Prometheus 远程写入协议 发送。

可以通过为它们提供不同的标签来指定多个 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 和域名可以包含端口号。《proxy_url》必须配置，如果 no_proxy 已配置。

proxy_from_environment 使用环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY（或其小写版本）。请求使用与其方案匹配的环境变量中的代理，除非被 no_proxy 排除。《proxy_url》和 no_proxy 必须在 proxy_from_environment 已配置的情况下不配置。

只有当 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 和域名可以包含端口号。《proxy_url》必须配置，如果 no_proxy 已配置。

proxy_from_environment 使用环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY（或其小写版本）。请求使用与其方案匹配的环境变量中的代理，除非被 no_proxy 排除。《proxy_url》和 no_proxy 必须在 proxy_from_environment 已配置的情况下不配置。

只有当 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 块

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

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

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

shards会重试由于可恢复错误而失败请求。如果服务器响应带有 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 - 丢弃匹配target_label的连接的source_labels的目标。
• hashmod - 对连接的标签进行哈希处理，计算其模数，并将结果写入target_label。
• keep - 保留匹配使用source_labels和separator提取的字符串的regex的指标。
• keepequal - 丢弃不匹配target_label的连接的source_labels的目标。
• labeldrop - 将regex与所有标签名称匹配。任何匹配的标签都将从指标的标签集中删除。
• labelkeep - 将regex与所有标签名称匹配。任何不匹配的标签都将从指标的标签集中删除。
• labelmap - 将regex与所有标签名称匹配。任何匹配的标签将根据replacement字段的内容重命名。
• lowercase - 将target_label设置为连接的source_labels的小写形式。
• replace - 将regex与连接的标签匹配。如果匹配，则使用replacement字段的内容替换target_label的内容。
• uppercase - 将target_label设置为连接的source_labels的大写形式。

wal block

该wal块自定义用于在将指标发送到配置的端点之前临时存储指标的写前日志（WAL）。

WAL有两个主要用途

• 缓冲因网络问题中断而未发送的指标。
• 在进程重启后填充内存缓存。

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

《truncate_frequency》参数配置了WAL（Write-Ahead Logging）清理的频率。每当《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》（仪表盘）：当前WAL跟踪的活跃系列数量。
• 《prometheus_remote_write_wal_storage_deleted_series》（仪表盘）：当前标记为从内存中删除的系列数量。
• 《prometheus_remote_write_wal_out_of_order_samples_total》（计数器）：顺序错误样本摄入失败的尝试总数。
• 《prometheus_remote_write_wal_storage_created_series_total》（计数器）：附加到WAL的创建系列总数。
• 《prometheus_remote_write_wal_storage_removed_series_total》（计数器）：从WAL中移除的系列总数。
• 《prometheus_remote_write_wal_samples_appended_total》（计数器）：附加到WAL的样本总数。
• 《prometheus_remote_write_wal_exemplars_appended_total》（计数器）：附加到WAL的样本总数。
• 《prometheus_remote_storage_samples_total》（计数器）：发送到远程存储的样本总数。
• 《prometheus_remote_storage_exemplars_total》（计数器）：发送到远程存储的样本总数。
• 《prometheus_remote_storage_metadata_total》（计数器）：发送到远程存储的元数据条目总数。
• 《prometheus_remote_storage_samples_failed_total》（计数器）：由于不可恢复错误而发送到远程存储失败的样本总数。
• 《prometheus_remote_storage_exemplars_failed_total》（计数器）：由于不可恢复错误而发送到远程存储失败的样本总数。
• 《prometheus_remote_storage_metadata_failed_total》（计数器）：由于不可恢复错误而发送到远程存储失败的元数据条目总数。
• 《prometheus_remote_storage_samples_retries_total》（计数器）：由于可恢复错误而重新尝试发送到远程存储失败的样本总数。
• 《prometheus_remote_storage_exemplars_retried_total》（计数器）：由于可恢复错误而重新尝试发送到远程存储失败的样本总数。
• 《prometheus_remote_storage_metadata_retried_total》（计数器）：由于可恢复错误而重新尝试发送到远程存储失败的元数据条目总数。
• 《prometheus_remote_storage_samples_dropped_total》（计数器）：由于未知引用ID而被丢弃的样本总数。
• 《prometheus_remote_storage_exemplars_dropped_total》（计数器）：由于未知引用ID而被丢弃的样本总数。
• 《prometheus_remote_storage_enqueue_retries_total》（计数器）：由于队列已满而失败入队的总次数。
• 《prometheus_remote_storage_sent_batch_duration_seconds》（直方图）：发送调用远程存储的持续时间。
• 《prometheus_remote_storage_queue_highest_sent_timestamp_seconds》（仪表盘）：队列成功发送的最新WAL样本的Unix时间戳。
• 《prometheus_remote_storage_samples_pending》（仪表盘）：等待在分片中发送到远程存储的样本数量。
• 《prometheus_remote_storage_exemplars_pending》（仪表盘）：等待在分片中发送到远程存储的样本总数。
• 《prometheus_remote_storage_shard_capacity》（仪表盘）：给定队列中分片的容量。
• prometheus_remote_storage_shards (仪表盘): 用于同时向端点交付指标所使用的分片数量。
• prometheus_remote_storage_shards_min (仪表盘): 允许队列运行的最小分片数量。
• prometheus_remote_storage_shards_max (仪表盘): 允许队列运行的最大分片数量。
• prometheus_remote_storage_shards_desired (仪表盘): 队列想要运行以跟上接收到的指标数量的分片数量。
• prometheus_remote_storage_bytes_total (计数器): 队列在压缩后发送的数据字节数总和。
• prometheus_remote_storage_metadata_bytes_total (计数器): 队列在压缩后发送的元数据字节数总和。
• prometheus_remote_storage_max_samples_per_send (仪表盘): 每个分片在单个请求中允许发送的最大样本数。
• prometheus_remote_storage_samples_in_total (计数器): 读取到远程存储中的样本。
• prometheus_remote_storage_exemplars_in_total (计数器): 读取到远程存储中的示例。

示例

以下示例展示了如何创建向不同目的地发送指标的 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次抓取间隔并不罕见。如果组件落后于上次截断间隔以来写入的数据的超过三分之一的数量，截断循环可能在推送至远程写入端点之前对数据进行检查点。

调整 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，并假设远程写入请求的平均延迟为500ms，则可达到的最大吞吐量约为 50 * 2000 * (1s / 500ms) = 200K样本 / s。

默认的 max_shards 配置适用于大多数用例，特别是如果每个Alloy实例抓取多达100万个活跃序列。然而，如果您在大型规模上运行Alloy，并且每个实例抓取的序列数超过100万个，我们建议增加 max_shards 的值。

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

• prometheus_remote_storage_shards (仪表盘): 用于同时向端点交付指标所使用的分片数量。
• prometheus_remote_storage_shards_min (仪表盘): 允许队列运行的最小分片数量。
• prometheus_remote_storage_shards_max（仪表盘）：队列允许运行的最多分片数。
• prometheus_remote_storage_shards_desired（仪表盘）：队列想要运行的分片数，以跟上传入指标的数量。

如果您已经运行了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 的组件