VictoriaMetrics vmagent

验证：未记录

适用版本: 未记录
验证范围: 尚未登记验证记录。

本文缩写（英文全称与中文含义）

缩写	英文全称／名称	中文含义
TSDB	Time Series Database	时间序列数据库
UI	User Interface	用户界面

1. Important Points#

vmagent 是 VictoriaMetrics 的 metrics collection agent。它负责 scrape Prometheus 格式的 /metrics，然后通过 remote_write 写入 VictoriaMetrics。

vmagent 负责采集和 remote_write，不是长期查询存储；发送前控制 labels，高基数值会传到后端放大成本。

use for:
    scrape node_exporter / process-exporter / app /metrics
    remote_write to VictoriaMetrics single-node or cluster vminsert
    replace Prometheus when you only need scrape + remote_write
    buffer remote_write data when backend is temporarily unavailable
    relabel / drop / normalize labels before writing

do not use for:
    query UI
    alert rule evaluation
    long-term metrics storage
    logs collection

核心关系：

exporters / apps
    -> vmagent scrape
        -> remote_write
            -> VictoriaMetrics single-node / vminsert

2. vmagent vs Prometheus vs Vector#

Tool	Main Role	When To Use
vmagent	scrape + remote_write	metrics-only collection into VictoriaMetrics
Prometheus	scrape + local TSDB + query + rules	need local Prometheus query/rules/storage
Vector	observability pipeline	metrics + logs + transforms + multiple sinks

简单判断：

only scrape Prometheus metrics and write to VictoriaMetrics:
    use vmagent

need logs and metrics in one pipeline:
    consider Vector

need local Prometheus UI / rules / TSDB:
    use Prometheus

3. Scrape Config#

vmagent 使用 Prometheus scrape config 格式。

# /etc/vmagent/prometheus.yml
global:
  scrape_interval: 30s
  scrape_timeout: 10s

scrape_configs:
  - job_name: node
    static_configs:
      - targets:
          - 127.0.0.1:9100
        labels:
          env: uat
          service: node

  - job_name: process-exporter
    static_configs:
      - targets:
          - 127.0.0.1:9256
        labels:
          env: uat
          service: process-exporter

  - job_name: app
    metrics_path: /metrics
    static_configs:
      - targets:
          - 127.0.0.1:8080
        labels:
          env: uat
          service: orders-api

4. Run#

single-node VictoriaMetrics#

vmagent -promscrape.config=/etc/vmagent/prometheus.yml -remoteWrite.url=http://victoria-metrics:8428/api/v1/write -remoteWrite.tmpDataPath=/var/lib/vmagent-remotewrite

cluster VictoriaMetrics#

Cluster 模式写入 vminsert，不是写 vmselect 或 vmstorage。

vmagent -promscrape.config=/etc/vmagent/prometheus.yml -remoteWrite.url=http://vminsert:8480/insert/0/prometheus/api/v1/write -remoteWrite.tmpDataPath=/var/lib/vmagent-remotewrite

through vmauth#

vmagent -promscrape.config=/etc/vmagent/prometheus.yml -remoteWrite.url=http://vmauth:8427/api/v1/write -remoteWrite.bearerToken=replace-with-token -remoteWrite.tmpDataPath=/var/lib/vmagent-remotewrite

5. Docker Compose#

services:
  vmagent:
    image: victoriametrics/vmagent:latest
    command:
      - -promscrape.config=/etc/vmagent/prometheus.yml
      - -remoteWrite.url=http://victoria-metrics:8428/api/v1/write
      - -remoteWrite.tmpDataPath=/vmagent-remotewrite-data
    volumes:
      - ./prometheus.yml:/etc/vmagent/prometheus.yml:ro
      - vmagent-data:/vmagent-remotewrite-data
    ports:
      - "8429:8429"

volumes:
  vmagent-data:

6. Relabel Examples#

add stable labels#

scrape_configs:
  - job_name: app
    static_configs:
      - targets:
          - 127.0.0.1:8080
    relabel_configs:
      - target_label: env
        replacement: uat
      - target_label: region
        replacement: ap-northeast-1

drop high-cardinality labels#

scrape_configs:
  - job_name: app
    static_configs:
      - targets:
          - 127.0.0.1:8080
    metric_relabel_configs:
      - action: labeldrop
        regex: "user_id|request_id|trace_id|session_id"

7. Verify#

# vmagent self metrics / targets UI
curl http://127.0.0.1:8429/metrics
curl http://127.0.0.1:8429/targets

# VictoriaMetrics query
curl "http://victoria-metrics:8428/api/v1/query?query=up"
curl "http://victoria-metrics:8428/api/v1/query?query=vmagent_remotewrite_pending_data_bytes"

常看指标：

Metric	Meaning
`up`	scrape target 是否成功
`scrape_samples_scraped`	每次 scrape 抓到多少 samples
`scrape_duration_seconds`	scrape 耗时
`vmagent_remotewrite_pending_data_bytes`	remote_write 待发送数据大小
`vmagent_remotewrite_packets_dropped_total`	remote_write 丢弃数据计数

8. Common Pitfalls#

wrong remote_write endpoint:
    single-node uses /api/v1/write
    cluster uses vminsert /insert/<accountID>/prometheus/api/v1/write

no persistent tmpDataPath:
    backend unavailable时 pending data 需要落盘缓存
    production should mount persistent disk for -remoteWrite.tmpDataPath

high cardinality:
    drop user_id / request_id / trace_id / full_url before remote_write

scrape timeout too close to scrape interval:
    scrape_timeout should be lower than scrape_interval

confusing vmagent and vmalert:
    vmagent collects and writes metrics
    vmalert evaluates rules and sends alerts

9. References#

vmagent docs: https://docs.victoriametrics.com/victoriametrics/vmagent/
Prometheus scrape config: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config