VictoriaMetrics vmagent 与 Google PubSub 集成实战：Enterprise 版指标读写全指南-港品优选

VictoriaMetrics vmagent 与 Google PubSub 集成实战：Enterprise 版指标读写全指南

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics

导读

本文聚焦 VictoriaMetrics 生态中vmagent与 Google PubSub 的深度集成（该能力仅在 Enterprise 版 vmagent 中提供），完整讲解两大核心场景：从 Google PubSub 主题订阅中读取指标（支持 promremotewrite、influx、prometheus、graphite、jsonline 五种格式、多主题并发、gzip 解压）与向 Google PubSub 主题写入指标（通过pubsub:前缀的-remoteWrite.url实现流式发布）。阅读本文后，你将掌握全部-gcp.pubsub.subscribe.*与-gcp.pubsub.publish.*命令行参数的语义、默认值与配置方法，并理解其与 vmagent 本地磁盘缓冲队列、多租户机制的配合方式，可直接上手搭建基于 PubSub 的指标中转链路。原文档位于 docs/victoriametrics/integrations/pubsub.md，建议配合 vmagent 完整文档阅读。

注意：本集成仅在 Enterprise 版的 vmagent 中受支持。开源版 vmagent 不包含gcp.pubsub.*相关实现与命令行 flag（在app/vmagent与lib目录的公开源码中不存在对应代码），使用前请确认你持有 Enterprise 二进制，并通过./bin/vmagent -help查看本机二进制实际暴露的 flag 清单。

集成能力总览

vmagent 可以作为 Google PubSub 的消费者（从主题订阅读取指标），也可以作为生产者（向主题发布指标），从而把 PubSub 变成指标数据在采集端与远程存储之间的异步消息通道。

读取（Consumer）：从 PubSub 主题订阅中消费消息，解析为各类指标协议格式后，通过-remoteWrite.url转发到远程存储（如 VictoriaMetrics 单机版、集群版 vminsert）。
写入（Producer）：将采集到的指标以 Prometheus remote_write 协议封装为 PubSub 消息发布到指定主题；这些消息随后可被另一个 vmagent 实例按promremotewrite格式读取，形成"vmagent → PubSub → vmagent → 远程存储"的链路。

两条链路都基于 Google 标准的应用默认凭据（ADC）机制完成鉴权，也可通过credentialsFile显式指定服务账号凭据文件。

从 Google PubSub 读取指标

vmagent可以从 Google PubSub 消息中读取多种格式的指标。读取时通过两条命令行 flag 控制期望的格式：

-gcp.pubsub.subscribe.defaultMessageFormat：全局默认格式（当某个订阅未显式指定messageFormat时生效），默认值为promremotewrite。
-gcp.pubsub.subscribe.topicSubscription.messageFormat：为指定订阅单独覆盖格式。

支持的消息格式如下：

格式	说明
`promremotewrite`	Prometheus remote_write 协议编码。由 vmagent 写入 PubSub 的消息即为此格式（详见下文"写入指标"一节）。该格式为默认格式
`influx`	InfluxDB 行协议（Line protocol）格式
`prometheus`	Prometheus 文本暴露格式及 OpenMetrics 格式
`graphite`	Graphite 纯文本（plaintext）协议格式
`jsonline`	JSON line 格式（VictoriaMetrics 数据导入使用的逐行 JSON 格式）

需要特别说明的是：influx、prometheus、graphite、jsonline这四种格式的单条 PubSub 消息可以包含多行数据，各行之间以\n换行符分隔，vmagent 会逐行解析；而promremotewrite格式的一条消息即对应一个完整的 remote_write 请求体。此外，除promremotewrite外的四种格式还支持消息体为 gzip 压缩（通过isGzipped参数开启），便于降低传输带宽。

订阅参数与鉴权方式

vmagent 通过-gcp.pubsub.subscribe.topicSubscription命令行 flag 指定要消费的 PubSub 主题订阅，其取值格式为：

projects/<project-id>/subscriptions/<subscription-name>

该 flag 为数组类型：可以重复传入多个 flag 来订阅多个主题，也可以用逗号分隔多个值。当配置了多个订阅时，所有-gcp.pubsub.subscribe.topicSubscription.*系列的数组型 flag（如messageFormat、isGzipped、concurrency）按下标与订阅一一对应。

鉴权方面，vmagent 使用 Google 标准的授权机制访问主题：默认采用应用默认凭据（Application Default Credentials，ADC），在 Kubernetes 中对应 Workload Identity，在普通环境中则从GOOGLE_APPLICATION_CREDENTIALS环境变量指向的服务账号 JSON 文件读取凭据。如需显式指定凭据文件，可通过-gcp.pubsub.subscribe.credentialsFile传入文件路径。

读取指标的最小配置示例

以下命令配置 vmagent 从 PubSub 订阅projects/victoriametrics-vmagent-pub-sub-test/subscriptions/telegraf-testing中读取InfluxDB 行协议格式的指标，并转发到本地 VictoriaMetrics 的写入端点：

./bin/vmagent -remoteWrite.url=http://localhost:8428/api/v1/write \ -gcp.pubsub.subscribe.topicSubscription=projects/victoriametrics-vmagent-pub-sub-test/subscriptions/telegraf-testing \ -gcp.pubsub.subscribe.topicSubscription.messageFormat=influx

此例的预期场景是 Telegraf 通过其cloud_pubsub输出插件向victoriametrics-vmagent-pub-sub-test项目的telegraf-testing主题写入 InfluxDB 行协议数据，Telegraf 侧配置如下：

[[outputs.cloud_pubsub]] project = "victoriametrics-vmagent-pub-sub-test" topic = "telegraf-testing" data_format = "influx"

背压缓冲与磁盘队列

当-remoteWrite.url指向的远程存储无法跟上数据摄入速率时，vmagent 会把从 PubSub 读到的消息缓冲到本地磁盘，待远程存储恢复后继续投递。这一行为沿用 vmagent 标准的 on-disk persistence 机制（实现位于 app/vmagent/remotewrite/remotewrite.go，文档详见 vmagent.md 的 On-disk persistence 章节）：

缓冲目录由-remoteWrite.tmpDataPath指定，每个-remoteWrite.url对应目录下的一个持久化队列文件夹；
每个 URL 可占用的最大磁盘空间由-remoteWrite.maxDiskUsagePerURL限制，达到上限时 vmagent 会丢弃最旧数据以容纳新数据；
若希望禁用磁盘缓冲（例如客户端侧更能容忍背压、或磁盘性能不足以支撑当前写入速率），可通过-remoteWrite.disableOnDiskQueue关闭。从源码看，该 flag 为数组布尔类型、可按-remoteWrite.url逐一配置（remotewrite.go 中disableOnDiskQueue定义）；当同时配置多个远程存储且其中任一启用了disableOnDiskQueue时，vmagent 会启用全局的丢样本策略（dropSamplesOnFailureGlobal，见 remotewrite.go 相关逻辑），未投递成功的样本将被丢弃而非积压。

关于关闭磁盘持久化的更多讨论，可参阅 Disabling On-disk persistence 一节。

此外，如果你希望把来自不同租户的指标写入远程集群的多个租户，可参考 vmagent 多租户（multitenancy）文档，该能力与 PubSub 读取链路是正交且可组合的。

多主题多格式读取示例

vmagent 可以从不同主题以不同格式并行消费消息。例如下面的命令同时订阅了两个主题：从telegraf-testing订阅读取纯文本 Influx 行协议消息（不启用 gzip），从json-line-testing订阅读取gzip 压缩的 JSON line消息：

./bin/vmagent -remoteWrite.url=http://localhost:8428/api/v1/write \ -gcp.pubsub.subscribe.topicSubscription=projects/victoriametrics-vmagent-pub-sub-test/subscriptions/telegraf-testing \ -gcp.pubsub.subscribe.topicSubscription.messageFormat=influx \ -gcp.pubsub.subscribe.topicSubscription.isGzipped=false \ -gcp.pubsub.subscribe.topicSubscription=projects/victoriametrics-vmagent-pub-sub-test/subscriptions/json-line-testing \ -gcp.pubsub.subscribe.topicSubscription.messageFormat=jsonline \ -gcp.pubsub.subscribe.topicSubscription.isGzipped=true

注意：messageFormat、isGzipped、concurrency均为与topicSubscription下标对应的数组 flag，因此上例中第一个下标（telegraf-testing）对应influx格式 +isGzipped=false，第二个下标（json-line-testing）对应jsonline格式 +isGzipped=true，顺序必须严格对齐。

消费者命令行参数完整参考

以下为读取（消费）链路全部可用 flag 的完整说明（-help输出整理），所有 flag 仅存在于 Enterprise 二进制中：

-gcp.pubsub.subscribe.credentialsFile string Path to file with GCP credentials to use for PubSub client. If not set, default credentials are used (see Workload Identity for K8S or application-default-credentials). This flag is available only in Enterprise binaries. -gcp.pubsub.subscribe.defaultMessageFormat string Default message format if -gcp.pubsub.subscribe.topicSubscription.messageFormat is missing. (default "promremotewrite") This flag is available only in Enterprise binaries. -gcp.pubsub.subscribe.topicSubscription array GCP PubSub topic subscription in the format: projects/<project-id>/subscriptions/<subscription-name>. Supports an array of values separated by comma or specified via multiple flags. This flag is available only in Enterprise binaries. -gcp.pubsub.subscribe.topicSubscription.concurrency array The number of concurrently processed messages for topic subscription specified via -gcp.pubsub.subscribe.topicSubscription flag. (default 0) Supports array of values separated by comma or specified via multiple flags. This flag is available only in Enterprise binaries. -gcp.pubsub.subscribe.topicSubscription.isGzipped array Enables gzip decompression for messages payload at the corresponding -gcp.pubsub.subscribe.topicSubscription. Only prometheus, jsonline, graphite and influx formats accept gzipped messages. Supports array of values separated by comma or specified via multiple flags. This flag is available only in Enterprise binaries. -gcp.pubsub.subscribe.topicSubscription.messageFormat array Message format for the corresponding -gcp.pubsub.subscribe.topicSubscription. Valid formats: influx, prometheus, promremotewrite, graphite, jsonline. Supports array of values separated by comma or specified via multiple flags. This flag is available only in Enterprise binaries.

关于这些参数的实践要点：

concurrency默认值为0。当其为 0 时 vmagent 使用内部默认的并发处理数；显式设置可控制单订阅的并行消息处理量，用于在吞吐与远端写入压力之间做平衡。
isGzipped只对prometheus、jsonline、graphite、influx四种格式生效，promremotewrite格式本身已是二进制编码的 remote_write 请求体，不支持 gzip 标志。
数组 flag 支持"逗号分隔单 flag"与"重复多 flag"两种写法，两种写法可混用；各数组 flag 的次序必须与topicSubscription列表一致。

向 Google PubSub 写入指标

vmagent 也可以作为生产者将指标写入 Google PubSub——只需让-remoteWrite.url以pubsub:前缀开头：

-remoteWrite.url=pubsub:projects/victoriametrics-vmagent-publish-test/topics/testing-pubsub-push

此时 vmagent 会把本应通过 HTTP remote_write 发送的指标数据封装成Prometheus remote_write 协议的 PubSub 消息，按批量策略发布到指定主题。这些消息之后可被另一个 vmagent 实例以promremotewrite格式读取（即上文"读取指标"链路），由此构成完整的指标接力链路：

采集源 → vmagent(Producer) → PubSub 主题 → vmagent(Consumer) → 远程存储

这种模式适用于：生产环境与存储环境之间需要异步解耦、跨网络/跨账号传输指标、或希望借助 PubSub 的订阅/推送语义做多消费者扇出等场景。

写入侧同样使用 Google 标准授权机制访问主题；若需要自定义凭据，通过-gcp.pubsub.publish.credentialsFile指定服务账号凭据文件即可（注意与读取侧的-gcp.pubsub.subscribe.credentialsFile是两个独立 flag）。

发布批处理与背压控制

写入侧的核心调优维度是Publish 批处理策略。vmagent 使用 Google PubSub 客户端库的流式发布能力，将多个消息聚合成 batch 后发送，以下参数控制 batch 的触发条件与客户端的背压行为：

-gcp.pubsub.publish.byteThreshold int（默认1000000）：当 batch 累积的字节数达到该值时触发发布。
-gcp.pubsub.publish.countThreshold int（默认100）：当 batch 内消息条数达到该值时触发发布。
-gcp.pubsub.publish.delayThreshold value（默认10ms）：非空 batch 在该延迟过后即使未达到上述两个阈值也会被发布，避免低流量场景下消息长期滞留。
-gcp.pubsub.publish.maxOutstandingMessages int（默认100）：客户端允许积压的待发布消息最大条数，用于限制内存占用与发布背压。
-gcp.pubsub.publish.maxOutstandingBytes int（默认-1）：客户端允许积压的待发布消息最大字节数；当取值小于等于0时该限制被禁用（默认即禁用），仅靠消息条数限制控制积压。
-gcp.pubsub.publish.timeout value（默认60s）：客户端尝试发布单个消息 bundle 的最大时间，超过后发布失败，触发 vmagent 的磁盘缓冲/重试逻辑。

其中delayThreshold与timeout属于 duration 类型 flag，支持s（秒）、h（小时）、d（天）、w（周）、y（年）后缀；不写后缀时按"月"计，因此务必显式写出单位（例如10ms、60s），避免语义歧义。

实际调优建议：若发布吞吐需求高，可适当调大byteThreshold/countThreshold以降低单条消息的开销；若对端（下游 vmagent 消费）处理较慢，则应保持或调小maxOutstandingMessages与timeout，让背压尽早传导到上游采集端，并通过磁盘队列兜底，而不是无限堆积内存。

生产者命令行参数完整参考

以下为写入（发布）链路全部可用 flag 的完整说明（-help输出整理），所有 flag 仅存在于 Enterprise 二进制中：

-gcp.pubsub.publish.byteThreshold int Publish a batch when its size in bytes reaches this value. (default 1000000) This flag is available only in Enterprise binaries. -gcp.pubsub.publish.countThreshold int Publish a batch when it has this many messages. (default 100) This flag is available only in Enterprise binaries. -gcp.pubsub.publish.credentialsFile string Path to file with GCP credentials to use for PubSub client. If not set, default credentials will be used (see Workload Identity for K8S or application-default-credentials). This flag is available only in Enterprise binaries. -gcp.pubsub.publish.delayThreshold value Publish a non-empty batch after this delay has passed. (default 10ms) The following optional suffixes are supported: s (second), h (hour), d (day), w (week), y (year). If suffix isn't set, then the duration is counted in months. This flag is available only in Enterprise binaries. -gcp.pubsub.publish.maxOutstandingBytes int The maximum size of buffered messages to be published. If less than or equal to zero, this is disabled. (default -1) This flag is available only in Enterprise binaries. -gcp.pubsub.publish.maxOutstandingMessages int The maximum number of buffered messages to be published. If less than or equal to zero, this is disabled. (default 100) This flag is available only in Enterprise binaries. -gcp.pubsub.publish.timeout value The maximum time that the client will attempt to publish a bundle of messages. (default 60s) The following optional suffixes are supported: s (second), h (hour), d (day), w (week), y (year). If suffix isn't set, then the duration is counted in months. This flag is available only in Enterprise binaries.

完整实战链路：Telegraf → PubSub → vmagent → VictoriaMetrics

将上述能力串成一个端到端示例。假设你已在 GCP 上创建了项目、主题telegraf-testing及其订阅telegraf-testing，并配置好服务账号权限（Pub/Sub Subscriber / Publisher 角色），完整链路如下：

1. Telegraf 将指标以 InfluxDB 行协议写入 PubSub 主题：

[[outputs.cloud_pubsub]] project = "victoriametrics-vmagent-pub-sub-test" topic = "telegraf-testing" data_format = "influx"

2. vmagent（Consumer，Enterprise 版）订阅该主题并写入远程存储：

./bin/vmagent -remoteWrite.url=http://localhost:8428/api/v1/write \ -gcp.pubsub.subscribe.topicSubscription=projects/victoriametrics-vmagent-pub-sub-test/subscriptions/telegraf-testing \ -gcp.pubsub.subscribe.topicSubscription.messageFormat=influx

3.（可选）若远程存储不可达，vmagent 自动将数据缓冲到-remoteWrite.tmpDataPath指定的磁盘队列；可通过-remoteWrite.maxDiskUsagePerURL限制缓冲上限。

4.（可选）将同一份数据继续中转到另一个 PubSub 主题：在另一台/另一个 vmagent 上把-remoteWrite.url设为pubsub:前缀，即可把当前 vmagent 收到的指标再次发布到 PubSub，供下游消费，例如：

./bin/vmagent \ -remoteWrite.url=pubsub:projects/victoriametrics-vmagent-publish-test/topics/testing-pubsub-push

5. 下游验证：使用第二个 vmagent 以-gcp.pubsub.subscribe.topicSubscription.messageFormat=promremotewrite订阅该发布主题，即可把消息还原为指标写入最终存储。

调试时可用./bin/vmagent -help | grep pubsub确认 Enterprise 二进制中相关 flag 是否就绪；消费链路的运行指标（已消费消息数、解析失败数等）与 vmagent 其他摄入协议一致，可从 vmagent 的/metrics端点观察。

企业官网建设流程全解析