VictoriaMetrics

Last reviewed Aug 26, 2026 · 814 words

VictoriaMetrics replaces Prometheus's storage engine with one Go binary that starts on 256 MB of RAM, accepts remote_write on port 8428, and answers Grafana as if it were Prometheus. The catch is in the phrase "drop-in": your dashboards drop in, your prometheus.yml does not, and the retention flag you set on day one decides whether the disk fills in month four.

Drop-in means the Grafana datasource, not your config file

The mental model that prevents most confusion: VictoriaMetrics is a storage and query engine, not a scraper you configure the way you configure Prometheus. Point a Grafana datasource of type Prometheus at http://victoriametrics:8428 and every existing dashboard renders, because /api/v1/query and /api/v1/query_range speak the same protocol. What it does not read is a full Prometheus config with rule_files and alerting blocks. Scrape targets can be handed over, as shown below, but recording rules and alerts live in a separate companion called vmalert. The Grafana vs Prometheus piece explains why those two are layers rather than rivals; VictoriaMetrics slots into the Prometheus layer and leaves Grafana untouched.

Three ways to get metrics in

Pick one and do not mix them casually.

Option 1 keeps Prometheus scraping and adds a remote_write block pointing at http://victoriametrics:8428/api/v1/write. Lowest risk, nothing else changes, and Prometheus's own retention can drop to 2 days.

Option 2 lets VictoriaMetrics scrape directly with -promscrape.config=/etc/prometheus.yml. It reads the scrape_configs section of a Prometheus file, including static targets and file-based discovery, so a homelab list of node-exporter and cAdvisor endpoints moves across unchanged.

Option 3 is vmagent, a small companion that scrapes and forwards with on-disk buffering. It is the right answer once 2 or more machines ship metrics over a flaky link; on a single server it is one more container you do not need.

services:
  victoriametrics:
    image: victoriametrics/victoria-metrics:latest
    command:
      - -storageDataPath=/victoria-metrics-data
      - -retentionPeriod=12
      - -promscrape.config=/etc/prometheus.yml
    ports:
      - "8428:8428"
    volumes:
      - ./vm-data:/victoria-metrics-data
      - ./prometheus.yml:/etc/prometheus.yml:ro
    restart: unless-stopped

Retention is one flag, and it is the one that matters

-retentionPeriod defaults to 1 month. A bare number means months, so 12 keeps a year; suffixes such as 30d or 2y work too. Compression is strong in practice, but a year of 15-second samples from a dozen exporters still grows into the low gigabytes, so set the value deliberately instead of inheriting the default and discovering it later. Per-metric retention is an enterprise feature; the open-source workaround is dropping noisy series at scrape time with relabeling. Backups are a snapshot call (curl http://localhost:8428/snapshot/create) followed by copying the directory it creates under snapshots/ with restic or rsync. Never copy the live data directory while it is being written.

MetricsQL diverges from PromQL in ways that show up late

MetricsQL runs almost every PromQL query unmodified, then adds conveniences: rate() without a lookbehind window, WITH expressions for reusable fragments, functions like range_last and histogram_quantiles. The divergences cut the other way as well. Some edge cases differ, most visibly around staleness handling and how rate() treats the first sample of a series, so a dashboard leaning on a subtle PromQL corner can plot slightly different numbers. In a homelab that is a curiosity. In a team sharing alert rules with a colleague on stock Prometheus, it becomes a source of "works on mine" arguments, and the fix is to write new rules in the shared subset.

Stay single-binary until you can name the reason not to

The cluster edition splits into vminsert, vmselect and vmstorage and wants a load balancer in front. It exists for tens of millions of active series and for multi-tenancy, not for a homelab that upgraded from 8 GB to 32 GB. One process on a mini PC handles every exporter a home rack can produce with headroom, and it upgrades by pulling a new image. Compared with Thanos, which bolts long-term storage onto Prometheus using object storage and several sidecar services, VictoriaMetrics reaches the same outcome in one process on a local disk. The cost is a smaller ecosystem: fewer blog posts, fewer Helm examples, and Grafana's query builder does not know about MetricsQL extensions.

What I'd do

Run Prometheus for 1 more month with remote_write into VictoriaMetrics and Prometheus retention cut to 2 days, confirm the Grafana panels match, then remove Prometheus and move the scrape config to -promscrape.config. Set -retentionPeriod=12 on day one, snapshot nightly, and leave the cluster edition alone. Keep a separate tool for uptime checks and alerting; VictoriaMetrics stores and answers, and it does that better per megabyte than anything else I have run.