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

    ...
  }

  ...
}

参数

以下参数被支持：

Block

以下块在 prometheus.remote_write 的定义内被支持：

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

endpoint block

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
• 微软编码：{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 - 对连接的标签进行哈希处理，计算其模数，并将结果写入到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的 uppercase 形式。

wal block

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（标记量）：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 (计数器): 在发送到远程写入之前，从WAL读取后被丢弃的样本总数，因为未知引用ID。
• prometheus_remote_storage_exemplars_dropped_total (计数器): 在发送到远程写入之前，从WAL读取后被丢弃的可实例化条目总数，因为未知引用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实例

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

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实例

您可以创建一个发送您的指标到Mimir实例内特定租户的 prometheus.remote_write 组件。当您的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",
    }
  }
}

将指标发送到托管服务

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

alloy 复制

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

技术细节

prometheus.remote_write 使用 snappy 进行压缩。

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

数据保留

《prometheus.remote_write》组件使用写前日志（WAL）来防止网络中断期间的数据丢失。该组件在每个配置的端点中缓冲接收到的度量指标在WAL中。网络中断解决后，队列分片可以使用WAL并将缓存的度量指标刷新到端点。

WAL以128MB的段形式记录度量指标。为了避免磁盘上的WAL无限期增长，组件在特定时间间隔内截断其段。

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

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

《WAL block》包含一些可配置 参数，可用于在内存使用、磁盘使用和数据保留之间进行权衡。

《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》的样本。

合金将尽量不使用太多碎片，但如果队列落后，远程写入组件将增加碎片数量最多到max_shards以增加吞吐量。大量的碎片可能会导致远程端点过载或增加合金内存利用率。因此，将max_shards调整到合适的值，以确保不会过载远程端点并能跟上发送到远程端点的数据积压，非常重要。

远程写入时合金可以达到的最大吞吐量等于max_shards * max_samples_per_send * <1 / average write request latency>。例如，使用默认配置的50max_shards和2000max_samples_per_send运行合金，假设远程写入请求的平均延迟为500ms，可得的最大吞吐量约为50 * 2000 * (1s / 500ms) = 200K samples / s。

默认的max_shards配置适用于大多数用例，特别是当每个合金实例抓取多达一百万个活跃系列时。但是，如果您以大规模运行合金，并且每个实例抓取超过一百万个系列，我们建议增加max_shards的值。

合金暴露了一些您可以使用来监控远程写入碎片的指标。

• prometheus_remote_storage_shards (仪表): 用于并发将指标发送到端点的分片数量。
• prometheus_remote_storage_shards_min (仪表): 队列允许运行的分片最小数量。
• prometheus_remote_storage_shards_max（仪表板）：一个队列允许运行的碎片的最大数量。
• prometheus_remote_storage_shards_desired（仪表板）：队列想要运行的碎片数量，以跟上传入指标的数量。

如果您已经运行了合金，一个经验规则是将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
)

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

WAL损坏

当合金意外停止而最新的WAL段仍在写入磁盘时，可能会发生WAL损坏。例如，主机计算机出现磁盘通用故障并在您停止合金和其他运行的服务之前崩溃。当您重新启动合金时，它将验证WAL，删除发现的任何损坏片段。有时，此修复无法成功，您必须手动删除损坏的WAL以继续。如果WAL损坏，合金将向日志文件写入错误消息，如err="failed to find segment for index"。

要删除损坏的WAL

1. 停止合金。

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

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

   注意

   为每个prometheus.remote_write组件存在一个wal目录。

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

兼容组件

prometheus.remote_write有一些可以由以下组件使用的导出项

• 消耗Prometheus MetricsReceiver的组件