vmagent 采集与转发
vmagent 是 VictoriaMetrics 的采集与转发组件，可读取大部分 Prometheus 抓取配置，负责服务发现、Relabel、抓取失败重试和 Remote Write 缓冲。它适合将采集职责从 Prometheus 分离出来，或将同一份指标安全转发到多个后端。vmagent 不提供长期存储和通用 PromQL 查询，不应被当作 VictoriaMetrics 数据库使用。
1. 何时使用 vmagent
| 需求 | 推荐方式 | 原因 |
|---|---|---|
| 已有 Prometheus，需要先接入长期存储 | Prometheus Remote Write | 变更最小，见 Remote Write 接入 |
| 多集群集中转发，网络存在短暂抖动 | vmagent | 本地磁盘缓冲和统一转发策略更容易管理 |
| 仅需采集、转发与 Grafana 查询 | vmagent + VictoriaMetrics | 可减少 Prometheus Server 的本地 TSDB 开销 |
| 需要规则计算与告警 | vmagent + vmalert/Alertmanager | vmagent 本身不执行告警规则 |
2. 采集配置
vmagent 使用 Prometheus 风格的抓取配置。以下例子保留 Kubernetes 服务发现和必要的标签过滤；不要将全部 Pod 标签映射为指标标签，否则很容易导致高基数。
# /etc/vmagent/prometheus.yml
global:
scrape_interval: 30s # 采集间隔应按 SLO 和存储成本统一规划。
scrape_timeout: 10s # 必须小于 scrape_interval，避免任务重叠。
scrape_configs:
- job_name: kubernetes-pods
kubernetes_sd_configs:
- role: pod # 通过集群内 ServiceAccount 发现 Pod。
relabel_configs:
# 只有显式标记 prometheus.io/scrape=true 的 Pod 才会被采集。
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
action: keep
regex: "true"
# 使用注解覆盖指标路径；未设置时保留默认 /metrics。
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
action: replace
target_label: __metrics_path__
regex: (.+)
# 仅保留受控的 namespace、pod 与 container 标签。
- source_labels: [__meta_kubernetes_namespace]
target_label: namespace
- source_labels: [__meta_kubernetes_pod_name]
target_label: pod
- source_labels: [__meta_kubernetes_pod_container_name]
target_label: container
3. Kubernetes 部署
部署时将抓取配置挂载为 ConfigMap，并为缓冲目录提供持久卷。缓冲盘的容量要覆盖后端不可用期间的样本量；临时卷在节点重启或 Pod 迁移后可能丢弃尚未发送的数据。
apiVersion: apps/v1
kind: Deployment
metadata:
name: vmagent
namespace: monitoring
spec:
replicas: 1 # 多副本采集需规划目标分片或重复采集与去重策略。
selector:
matchLabels:
app.kubernetes.io/name: vmagent
template:
metadata:
labels:
app.kubernetes.io/name: vmagent
spec:
serviceAccountName: vmagent # 需授予读取 Pod、Service、EndpointSlice 的最小 RBAC 权限。
containers:
- name: vmagent
image: victoriametrics/vmagent:<validated-version>
args:
# 复用 Prometheus 风格抓取配置。
- -promscrape.config=/etc/vmagent/prometheus.yml
# 单机 VM 写入地址；集群部署时改为 vminsert 地址。
- -remoteWrite.url=http://victoriametrics.monitoring.svc:8428/api/v1/write
# 队列与未送达数据的本地缓冲目录。
- -remoteWrite.tmpDataPath=/var/lib/vmagent
ports:
- name: http
containerPort: 8429
volumeMounts:
- name: config
mountPath: /etc/vmagent
readOnly: true
- name: buffer
mountPath: /var/lib/vmagent
volumes:
- name: config
configMap:
name: vmagent-config
- name: buffer
persistentVolumeClaim:
claimName: vmagent-buffer
完整生产清单还应包含 Deployment 所需的 ServiceAccount、Role/ClusterRole、RoleBinding/ClusterRoleBinding、资源请求限制、反亲和或拓扑分布约束，以及 NetworkPolicy。RBAC 权限范围取决于服务发现的角色，不能直接照搬高权限集群管理员角色。
4. 多后端与标签治理
vmagent 可以将样本写到多个后端。多写适合迁移、容灾或将不同类别指标送至不同存储，但每新增一个后端都会增加网络、磁盘缓冲和故障处理复杂度。
# 以命令行参数形式配置多后端，顺序与 remoteWrite.url 参数一一对应。
args:
# 主存储写入地址。
- -remoteWrite.url=http://vminsert.monitoring.svc:8480/insert/0/prometheus/api/v1/write
# 迁移期间的第二写入目标；验证完成后应及时移除，避免长期双写成本。
- -remoteWrite.url=https://metrics-dr.example.internal/api/v1/write
# 为所有写入数据增加稳定来源标签。
- -remoteWrite.label=cluster=production-shanghai
cluster、environment、region 等标签应在采集端统一添加。不要以请求 ID、完整 URL、用户 ID、容器镜像摘要或随机版本号作为标签；这些信息应放在日志、Trace 或受控的元数据系统中。
5. 验收与排障
# 查看 vmagent 服务、日志和本地缓冲卷使用情况。
kubectl -n monitoring get pods -l app.kubernetes.io/name=vmagent
kubectl -n monitoring logs deploy/vmagent --tail=200
kubectl -n monitoring exec deploy/vmagent -- df -h /var/lib/vmagent
# 查询 vmagent 自身指标，重点检查 Remote Write 队列与错误。
kubectl -n monitoring port-forward deploy/vmagent 8429:8429
curl -fsS http://127.0.0.1:8429/metrics | rg 'vmagent_remotewrite.*(pending|error|dropped)'
排查顺序是：目标发现是否符合预期、抓取是否成功、Relabel 是否错误丢弃样本、缓冲盘是否增长、后端是否接收并可查询。不要仅通过 up 判断 vmagent 正常，因为 up 只覆盖被抓取目标，不覆盖转发链路。