使用 Vector 通过 Prometheus Remote Write 接入 VictoriaMetrics 完整指南【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics导读本文围绕 VictoriaMetrics 官方数据接入文档中关于 Vector 的部分展开系统讲解如何将 Vector 配置为 Prometheus remote write 客户端把采集到的指标推送到 VictoriaMetrics 的/api/v1/write写入端点。全文覆盖最小可运行配置、Basic Auth 与 Bearer Token 两种认证方式以及一份 Vector 同时向 VictoriaMetrics 推送指标、向 VictoriaLogs 推送日志的组合部署方案并结合本仓库源码说明写入端点的底层处理逻辑帮助读者快速落地一套可生产使用的指标采集链路。一、为什么选择 Vector 作为 VictoriaMetrics 的数据采集前端Vector 是一个可编程的数据管道pipeline工具它通过sources采集源、transforms转换、sinks输出端三段式配置模型把不同来源的遥测数据汇聚后转发到任意目标。在 VictoriaMetrics 生态中Vector 最常见的用法是充当指标采集与转发代理由host_metrics等内置 source 采集主机指标再由类型为prometheus_remote_write的 sink 将数据批量推送到 VictoriaMetrics。VictoriaMetrics 完整兼容 Prometheus remote write 协议其单机版与集群版都原生暴露了 remote write 写入端点因此 Vector 无需任何自定义插件即可直接对接。从源码可以确认写入路径/prometheus/api/v1/write、/api/v1/write、/api/v1/push、/prometheus/api/v1/push都会被路由到promremotewrite.InsertHandler处理见 app/vminsert/main.go该 handler 会解析 Prometheus 的 protobuf 格式请求体并写入存储。也就是说Vector 发出的标准 remote write 请求与 Prometheus 自身、vmagent 等工具的写入方式完全一致。本文以下所有示例均遵循官方文档约定配置中的占位符需要替换为你自己的实际值例如victoriametrics_url应替换为你的 VictoriaMetrics 单机版地址如http://localhost:8428或集群版 vminsert 地址如http://vminsert:8480。二、最小配置将主机指标推送到 VictoriaMetrics官方文档给出的最小配置只需一个 source 和一个 sinksources: host_metrics_source: type: host_metrics sinks: victoriametrics_sink: type: prometheus_remote_write inputs: - host_metrics_source endpoint: https://victoriametrics_url/api/v1/write healthcheck: enabled: false配置要点说明host_metrics_sourceVector 内置的主机指标采集器负责收集 CPU、内存、磁盘、网络等系统级指标无需额外安装采集组件。sinks.victoriametrics_sink.type: prometheus_remote_write将 sink 声明为 Prometheus remote write 类型Vector 会按该协议编码并推送数据。inputs声明数据来源即上文定义的 source 名称形成 source → sink 的数据流。endpoint指向 VictoriaMetrics 的 remote write 写入地址。注意端点路径必须精确为/api/v1/write或等价的/prometheus/api/v1/writeVictoriaMetrics 的 HTTP 路由器正是针对该路径调用 remote write 处理逻辑见 app/vminsert/main.go。healthcheck.enabled: false关闭 Vector 对目标端点的健康检查。官方文档在三个示例中都显式关闭了它主要原因是在 VictoriaMetrics 面前remote write 路径本身不接受 Vector 健康检查请求的预期响应格式关闭可避免无谓的告警或重试。从 VictoriaMetrics 侧看请求到达后由 app/vminsert/promremotewrite/request_handler.go 的InsertHandler处理它先解析请求中的extra_label等附加标签随后流式解析请求体中的prompb.TimeSeries逐批调用insertRows落盘处理完成后返回204 No Content状态码。这一实现意味着 Vector 推送的数据会被当作原生指标写入查询时可直接使用 MetricsQL / PromQL 检索。2.1 补充为写入请求附加标签extra_labelVictoriaMetrics 的 remote write 端点还支持通过查询参数为每批写入数据统一附加标签。源码GetExtraLabels见 lib/protoparser/protoparserutil/extra_labels.go会解析请求 URL 中形如extra_labelnamevalue的查询参数并把它们合并进每条时间序列的标签集合。如果你希望通过 Vector 路由之外的方式给指标打上环境、机房等公共标签可以在 Vector 的 sink 配置中把 endpoint 写成endpoint: https://victoriametrics_url/api/v1/write?extra_labelenvprodextra_labelregioncn-east三、Basic Authentication 认证接入当 VictoriaMetrics 开启了 HTTP Basic Auth例如通过-httpAuth.username与-httpAuth.password启动参数启用见 lib/httpserver/httpserver.goVector 需要在 sink 中显式携带认证信息。官方文档给出的配置如下sources: host_metrics_source: type: host_metrics sinks: victoriametrics_sink: type: prometheus_remote_write inputs: - host_metrics_source endpoint: https://victoriametrics_url/api/v1/write auth: strategy: basic user: victoriametrics_user password: victoriametrics_password healthcheck: enabled: false配置要点说明auth.strategy: basic声明使用 HTTP Basic Authentication 认证策略。auth.user/auth.password分别填入 VictoriaMetrics 侧配置的用户名与密码。注意官方原文档中user行的写法为victoriametrics_user缺少闭合的实际使用时应写为victoriametrics_user与password的victoriametrics_password占位符风格保持一致。开启 Basic Auth 后所有未携带正确凭据的写入请求会被 VictoriaMetrics 的 HTTP 服务器直接拒绝从而保护写入端点不被未授权客户端滥用。四、Bearer / Token 认证接入如果 VictoriaMetrics或前置的反向代理 / vmauth采用 Bearer Token 鉴权则只需替换auth块中的策略与凭据字段sources: host_metrics_source: type: host_metrics sinks: victoriametrics_sink: type: prometheus_remote_write inputs: - host_metrics_source endpoint: https://victoriametrics_url/api/v1/write auth: strategy: bearer token: victoriametrics_token healthcheck: enabled: false配置要点说明auth.strategy: bearer切换为 Bearer Token 认证Vector 会在每个写入请求的Authorization头中携带Bearer token。auth.token填入实际的令牌值。这种方式尤其适合对接 VictoriaMetrics 集群版前端的 vmauth 网关或企业版中基于令牌的租户鉴权场景。与 Basic Auth 示例相比其余结构完全一致便于在两种鉴权方式间快速切换。五、一份 Agent 同时推送指标到 VictoriaMetrics 与日志到 VictoriaLogsVictoriaMetrics 与 VictoriaLogs 是两个独立的时序/日志数据库官方文档给出了将两者打通的最佳实践使用同一个 Vector 实例同时向 VictoriaMetrics 推送指标、向 VictoriaLogs 推送日志。指标仍走prometheus_remote_writesink而日志则通过 VictoriaLogs 兼容的 Elasticsearch bulk 写入端点接收。sources: host_metrics_source: type: host_metrics journald_source: type: journald sinks: victoriametrics_sink: type: prometheus_remote_write inputs: - host_metrics_source endpoint: https://victoriametrics_url/api/v1/write auth: strategy: bearer token: token healthcheck: enabled: false victorialogs_sink: inputs: - journald_source type: elasticsearch endpoints: - https://victorialogs_url/insert/elasticsearch/ mode: bulk api_version: v8 healthcheck: enabled: false query: _msg_field: message _time_field: timestamp _stream_fields: host,container_name该组合配置的核心机制双 source 双 sinkhost_metrics_source采集系统指标journald_source采集 systemd 日志两者各自流入对应的 sink互不干扰实现一个 Agent 管理两条数据通路。指标侧与第四节相同使用 Bearer Token 认证向/api/v1/write推送指标。日志侧sink 类型为elasticsearch端点指向 VictoriaLogs 的https://victorialogs_url/insert/elasticsearch/写入地址mode: bulk使用批量写入模式api_version: v8采用 Elasticsearch 8.x 兼容协议。query参数映射日志字段这是接入 VictoriaLogs 的关键。VictoriaLogs 通过特殊查询参数约定日志字段语义_msg_field: message告诉 VictoriaLogs 日志正文存放在名为message的字段中_time_field: timestamp指定日志时间戳字段为timestamp_stream_fields: host,container_name声明以host、container_name两个字段作为日志流的划分维度VictoriaLogs 会据此对日志流做索引与检索分组。说明VictoriaLogs 的源码现已独立维护原app/vlinsert目录仅保留迁移说明见 app/vlinsert/README.md但其_msg_field、_time_field、_stream_fields等 Elasticsearch 兼容写入参数的语义仍以上述官方文档为准使用前请以当前版本的 VictoriaLogs 文档核对参数名称。六、VictoriaMetrics 侧写入端点的实现原理与验证为了让读者对Vector 推送到/api/v1/write之后发生了什么有更底层的认知这里结合本仓库源码做一次链路还原路由分发单机版入口 app/victoria-metrics/main.go 启动后挂载 vminsert 的 HTTP 处理逻辑。vminsert的RequestHandler中/api/v1/write等四个等价路径统一进入promremotewrite.InsertHandler见 app/vminsert/main.go并登记vm_http_requests_total{path/api/v1/write, protocolpromremotewrite}等指标app/vminsert/main.go。解析与写入InsertHandler先通过GetExtraLabels解析extra_label查询参数lib/protoparser/protoparserutil/extra_labels.go随后流式解析 protobuf 请求体把prompb.TimeSeries拆成采样点逐批写入存储app/vminsert/promremotewrite/request_handler.go。认证前置Basic Auth 由lib/httpserver的-httpAuth.username/-httpAuth.password启动参数控制lib/httpserver/httpserver.go在请求进入写入 handler 之前即完成校验因此 Vector 侧必须按第三节、第四节的auth块配置凭据否则请求会被 401 拒绝。协议兼容VictoriaMetrics 还支持 zstd 压缩的 remote write 请求体Content-Encoding: zstdVector 的prometheus_remote_writesink 若开启压缩同样可以被原生解压处理。如果你希望快速验证整条链路是否打通可以在 VictoriaMetrics 单机版运行后执行# 使用 curl 模拟 Vector 的 remote write 行为空 body 验证端点可达性 curl -i -X POST http://localhost:8428/api/v1/write正常情况下 VictoriaMetrics 会返回204 No Content空 body 也会被协议解析容忍随后即可在 vmui/vmui页面或 PromQL 查询中检索到 Vector 推送的host_metrics_*指标。七、生产落地建议与注意事项结合官方文档与仓库实现将上述配置用于生产时建议关注以下几点关闭 healthcheck 的必要性三个官方示例均设置healthcheck.enabled: false。若你的部署确实需要健康检查应改为指向 VictoriaMetrics 的健康端点如/health而不是对 remote write 写入端点发起探测。认证凭据的保管Basic Auth 密码与 Bearer Token 都属于敏感信息建议通过 Vector 的环境变量注入如password: ${VM_PASSWORD}或密钥管理机制引用避免明文落入配置文件版本库。多租户场景VictoriaMetrics 集群版可通过 URL 前缀区分租户例如http://vminsert:8480/select/0/prometheus/api/v1/write写入端点按租户路由。此时只需修改 endpoint 前缀即可复用本文全部配置结构。字段命名一致性日志接入中_msg_field、_time_field必须与 Vector source 实际输出的字段名严格一致否则日志正文或时间戳将无法被 VictoriaLogs 正确解析。数据链路观测可在 VictoriaMetrics 的/metrics页面观察vm_http_requests_total{path/api/v1/write}计数是否持续增长以此确认 Vector → VictoriaMetrics 的推送在持续进行。参考资料本文对应官方文档docs/victoriametrics/data-ingestion/Vector.mdVictoriaMetrics remote write 端点实现app/vminsert/main.go、app/vminsert/promremotewrite/request_handler.goextra_label 附加标签解析lib/protoparser/protoparserutil/extra_labels.goHTTP Basic Auth 启动参数lib/httpserver/httpserver.go【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Vector 通过 Prometheus Remote Write 接入 VictoriaMetrics 完整指南
使用 Vector 通过 Prometheus Remote Write 接入 VictoriaMetrics 完整指南【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics导读本文围绕 VictoriaMetrics 官方数据接入文档中关于 Vector 的部分展开系统讲解如何将 Vector 配置为 Prometheus remote write 客户端把采集到的指标推送到 VictoriaMetrics 的/api/v1/write写入端点。全文覆盖最小可运行配置、Basic Auth 与 Bearer Token 两种认证方式以及一份 Vector 同时向 VictoriaMetrics 推送指标、向 VictoriaLogs 推送日志的组合部署方案并结合本仓库源码说明写入端点的底层处理逻辑帮助读者快速落地一套可生产使用的指标采集链路。一、为什么选择 Vector 作为 VictoriaMetrics 的数据采集前端Vector 是一个可编程的数据管道pipeline工具它通过sources采集源、transforms转换、sinks输出端三段式配置模型把不同来源的遥测数据汇聚后转发到任意目标。在 VictoriaMetrics 生态中Vector 最常见的用法是充当指标采集与转发代理由host_metrics等内置 source 采集主机指标再由类型为prometheus_remote_write的 sink 将数据批量推送到 VictoriaMetrics。VictoriaMetrics 完整兼容 Prometheus remote write 协议其单机版与集群版都原生暴露了 remote write 写入端点因此 Vector 无需任何自定义插件即可直接对接。从源码可以确认写入路径/prometheus/api/v1/write、/api/v1/write、/api/v1/push、/prometheus/api/v1/push都会被路由到promremotewrite.InsertHandler处理见 app/vminsert/main.go该 handler 会解析 Prometheus 的 protobuf 格式请求体并写入存储。也就是说Vector 发出的标准 remote write 请求与 Prometheus 自身、vmagent 等工具的写入方式完全一致。本文以下所有示例均遵循官方文档约定配置中的占位符需要替换为你自己的实际值例如victoriametrics_url应替换为你的 VictoriaMetrics 单机版地址如http://localhost:8428或集群版 vminsert 地址如http://vminsert:8480。二、最小配置将主机指标推送到 VictoriaMetrics官方文档给出的最小配置只需一个 source 和一个 sinksources: host_metrics_source: type: host_metrics sinks: victoriametrics_sink: type: prometheus_remote_write inputs: - host_metrics_source endpoint: https://victoriametrics_url/api/v1/write healthcheck: enabled: false配置要点说明host_metrics_sourceVector 内置的主机指标采集器负责收集 CPU、内存、磁盘、网络等系统级指标无需额外安装采集组件。sinks.victoriametrics_sink.type: prometheus_remote_write将 sink 声明为 Prometheus remote write 类型Vector 会按该协议编码并推送数据。inputs声明数据来源即上文定义的 source 名称形成 source → sink 的数据流。endpoint指向 VictoriaMetrics 的 remote write 写入地址。注意端点路径必须精确为/api/v1/write或等价的/prometheus/api/v1/writeVictoriaMetrics 的 HTTP 路由器正是针对该路径调用 remote write 处理逻辑见 app/vminsert/main.go。healthcheck.enabled: false关闭 Vector 对目标端点的健康检查。官方文档在三个示例中都显式关闭了它主要原因是在 VictoriaMetrics 面前remote write 路径本身不接受 Vector 健康检查请求的预期响应格式关闭可避免无谓的告警或重试。从 VictoriaMetrics 侧看请求到达后由 app/vminsert/promremotewrite/request_handler.go 的InsertHandler处理它先解析请求中的extra_label等附加标签随后流式解析请求体中的prompb.TimeSeries逐批调用insertRows落盘处理完成后返回204 No Content状态码。这一实现意味着 Vector 推送的数据会被当作原生指标写入查询时可直接使用 MetricsQL / PromQL 检索。2.1 补充为写入请求附加标签extra_labelVictoriaMetrics 的 remote write 端点还支持通过查询参数为每批写入数据统一附加标签。源码GetExtraLabels见 lib/protoparser/protoparserutil/extra_labels.go会解析请求 URL 中形如extra_labelnamevalue的查询参数并把它们合并进每条时间序列的标签集合。如果你希望通过 Vector 路由之外的方式给指标打上环境、机房等公共标签可以在 Vector 的 sink 配置中把 endpoint 写成endpoint: https://victoriametrics_url/api/v1/write?extra_labelenvprodextra_labelregioncn-east三、Basic Authentication 认证接入当 VictoriaMetrics 开启了 HTTP Basic Auth例如通过-httpAuth.username与-httpAuth.password启动参数启用见 lib/httpserver/httpserver.goVector 需要在 sink 中显式携带认证信息。官方文档给出的配置如下sources: host_metrics_source: type: host_metrics sinks: victoriametrics_sink: type: prometheus_remote_write inputs: - host_metrics_source endpoint: https://victoriametrics_url/api/v1/write auth: strategy: basic user: victoriametrics_user password: victoriametrics_password healthcheck: enabled: false配置要点说明auth.strategy: basic声明使用 HTTP Basic Authentication 认证策略。auth.user/auth.password分别填入 VictoriaMetrics 侧配置的用户名与密码。注意官方原文档中user行的写法为victoriametrics_user缺少闭合的实际使用时应写为victoriametrics_user与password的victoriametrics_password占位符风格保持一致。开启 Basic Auth 后所有未携带正确凭据的写入请求会被 VictoriaMetrics 的 HTTP 服务器直接拒绝从而保护写入端点不被未授权客户端滥用。四、Bearer / Token 认证接入如果 VictoriaMetrics或前置的反向代理 / vmauth采用 Bearer Token 鉴权则只需替换auth块中的策略与凭据字段sources: host_metrics_source: type: host_metrics sinks: victoriametrics_sink: type: prometheus_remote_write inputs: - host_metrics_source endpoint: https://victoriametrics_url/api/v1/write auth: strategy: bearer token: victoriametrics_token healthcheck: enabled: false配置要点说明auth.strategy: bearer切换为 Bearer Token 认证Vector 会在每个写入请求的Authorization头中携带Bearer token。auth.token填入实际的令牌值。这种方式尤其适合对接 VictoriaMetrics 集群版前端的 vmauth 网关或企业版中基于令牌的租户鉴权场景。与 Basic Auth 示例相比其余结构完全一致便于在两种鉴权方式间快速切换。五、一份 Agent 同时推送指标到 VictoriaMetrics 与日志到 VictoriaLogsVictoriaMetrics 与 VictoriaLogs 是两个独立的时序/日志数据库官方文档给出了将两者打通的最佳实践使用同一个 Vector 实例同时向 VictoriaMetrics 推送指标、向 VictoriaLogs 推送日志。指标仍走prometheus_remote_writesink而日志则通过 VictoriaLogs 兼容的 Elasticsearch bulk 写入端点接收。sources: host_metrics_source: type: host_metrics journald_source: type: journald sinks: victoriametrics_sink: type: prometheus_remote_write inputs: - host_metrics_source endpoint: https://victoriametrics_url/api/v1/write auth: strategy: bearer token: token healthcheck: enabled: false victorialogs_sink: inputs: - journald_source type: elasticsearch endpoints: - https://victorialogs_url/insert/elasticsearch/ mode: bulk api_version: v8 healthcheck: enabled: false query: _msg_field: message _time_field: timestamp _stream_fields: host,container_name该组合配置的核心机制双 source 双 sinkhost_metrics_source采集系统指标journald_source采集 systemd 日志两者各自流入对应的 sink互不干扰实现一个 Agent 管理两条数据通路。指标侧与第四节相同使用 Bearer Token 认证向/api/v1/write推送指标。日志侧sink 类型为elasticsearch端点指向 VictoriaLogs 的https://victorialogs_url/insert/elasticsearch/写入地址mode: bulk使用批量写入模式api_version: v8采用 Elasticsearch 8.x 兼容协议。query参数映射日志字段这是接入 VictoriaLogs 的关键。VictoriaLogs 通过特殊查询参数约定日志字段语义_msg_field: message告诉 VictoriaLogs 日志正文存放在名为message的字段中_time_field: timestamp指定日志时间戳字段为timestamp_stream_fields: host,container_name声明以host、container_name两个字段作为日志流的划分维度VictoriaLogs 会据此对日志流做索引与检索分组。说明VictoriaLogs 的源码现已独立维护原app/vlinsert目录仅保留迁移说明见 app/vlinsert/README.md但其_msg_field、_time_field、_stream_fields等 Elasticsearch 兼容写入参数的语义仍以上述官方文档为准使用前请以当前版本的 VictoriaLogs 文档核对参数名称。六、VictoriaMetrics 侧写入端点的实现原理与验证为了让读者对Vector 推送到/api/v1/write之后发生了什么有更底层的认知这里结合本仓库源码做一次链路还原路由分发单机版入口 app/victoria-metrics/main.go 启动后挂载 vminsert 的 HTTP 处理逻辑。vminsert的RequestHandler中/api/v1/write等四个等价路径统一进入promremotewrite.InsertHandler见 app/vminsert/main.go并登记vm_http_requests_total{path/api/v1/write, protocolpromremotewrite}等指标app/vminsert/main.go。解析与写入InsertHandler先通过GetExtraLabels解析extra_label查询参数lib/protoparser/protoparserutil/extra_labels.go随后流式解析 protobuf 请求体把prompb.TimeSeries拆成采样点逐批写入存储app/vminsert/promremotewrite/request_handler.go。认证前置Basic Auth 由lib/httpserver的-httpAuth.username/-httpAuth.password启动参数控制lib/httpserver/httpserver.go在请求进入写入 handler 之前即完成校验因此 Vector 侧必须按第三节、第四节的auth块配置凭据否则请求会被 401 拒绝。协议兼容VictoriaMetrics 还支持 zstd 压缩的 remote write 请求体Content-Encoding: zstdVector 的prometheus_remote_writesink 若开启压缩同样可以被原生解压处理。如果你希望快速验证整条链路是否打通可以在 VictoriaMetrics 单机版运行后执行# 使用 curl 模拟 Vector 的 remote write 行为空 body 验证端点可达性 curl -i -X POST http://localhost:8428/api/v1/write正常情况下 VictoriaMetrics 会返回204 No Content空 body 也会被协议解析容忍随后即可在 vmui/vmui页面或 PromQL 查询中检索到 Vector 推送的host_metrics_*指标。七、生产落地建议与注意事项结合官方文档与仓库实现将上述配置用于生产时建议关注以下几点关闭 healthcheck 的必要性三个官方示例均设置healthcheck.enabled: false。若你的部署确实需要健康检查应改为指向 VictoriaMetrics 的健康端点如/health而不是对 remote write 写入端点发起探测。认证凭据的保管Basic Auth 密码与 Bearer Token 都属于敏感信息建议通过 Vector 的环境变量注入如password: ${VM_PASSWORD}或密钥管理机制引用避免明文落入配置文件版本库。多租户场景VictoriaMetrics 集群版可通过 URL 前缀区分租户例如http://vminsert:8480/select/0/prometheus/api/v1/write写入端点按租户路由。此时只需修改 endpoint 前缀即可复用本文全部配置结构。字段命名一致性日志接入中_msg_field、_time_field必须与 Vector source 实际输出的字段名严格一致否则日志正文或时间戳将无法被 VictoriaLogs 正确解析。数据链路观测可在 VictoriaMetrics 的/metrics页面观察vm_http_requests_total{path/api/v1/write}计数是否持续增长以此确认 Vector → VictoriaMetrics 的推送在持续进行。参考资料本文对应官方文档docs/victoriametrics/data-ingestion/Vector.mdVictoriaMetrics remote write 端点实现app/vminsert/main.go、app/vminsert/promremotewrite/request_handler.goextra_label 附加标签解析lib/protoparser/protoparserutil/extra_labels.goHTTP Basic Auth 启动参数lib/httpserver/httpserver.go【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考