VictoriaMetrics: Scalable Prometheus-Compatible TSDB

VictoriaMetrics

VictoriaMetrics is an open-source time series database and monitoring stack built for high ingestion rates, efficient storage, and simple operations. It speaks the Prometheus ecosystem's protocols — it accepts Prometheus remote write and scrapes targets, answers PromQL-compatible queries, and works as a Prometheus data source in Grafana — while using notably less memory and disk than many alternatives. A single binary handles millions of active series on modest hardware; a cluster version scales further horizontally.

Teams adopt VictoriaMetrics as long-term storage behind existing Prometheus servers, as a drop-in replacement for Prometheus storage, or as the core of a full monitoring stack with its own agent and alerting components.

TL;DR

Single-node VictoriaMetrics is one binary; the cluster splits into vminsert, vmstorage, and vmselect.
Ingest with Prometheus remote write, vmagent (scraping and buffering), or other protocols such as InfluxDB line protocol and OpenTelemetry.
Query with MetricsQL, a backward-compatible extension of PromQL.
Set retention with -retentionPeriod, and deduplicate HA pairs with -dedup.minScrapeInterval.
vmalert evaluates recording and alerting rules and sends alerts to Alertmanager.
Back up with vmbackup using instant snapshots; manage cardinality with built-in tools.

Quick Example

Run single-node VictoriaMetrics with one year of retention and deduplication for an HA Prometheus pair:

Send data from existing Prometheus servers:

Or replace Prometheus scraping with vmagent, which buffers to disk if the database is unreachable:

Grafana uses http://victoriametrics:8428 as a Prometheus data source; existing PromQL dashboards keep working.

Core Concepts

Deployment Options

Single-node is simpler and surprisingly capable; move to the cluster version for horizontal scaling, tenant isolation, or replication across storage nodes.

Ingestion

MetricsQL

MetricsQL accepts valid PromQL and adds conveniences: optional lookbehind windows (rate(http_requests_total) picks one automatically), WITH templates for reusable expressions, extra functions for rollups and label manipulation, and different handling of some edge cases (for example, extrapolation in rate). Most dashboards migrate without changes; verify critical alert expressions after switching.

Retention and Deduplication

-retentionPeriod sets how long data is kept (in months by default, or with suffixes such as 90d). When an HA pair of Prometheus servers or vmagents sends the same series, -dedup.minScrapeInterval keeps one sample per interval, so storage and queries see a single series. The cluster version can also replicate data across storage nodes.

Alerting and Rules

vmalert runs Prometheus-compatible recording and alerting rule files against VictoriaMetrics and sends alerts to Alertmanager. Running rules centrally works well when data from many sources lands in one database.

Operations

Backups: vmbackup creates incremental backups from instant snapshots to object storage; vmrestore restores them.
Cardinality: the cardinality explorer and /api/v1/status/tsdb show the series and labels driving growth.
Capacity: monitor active series, ingestion rate, churn, disk usage, and slow queries through VictoriaMetrics' own metrics.
Limits: protect against expensive queries and unbounded label values with query and series limits.
Migration: vmctl imports historical data from Prometheus snapshots, Thanos, and other sources.

VictoriaMetrics Compared With Alternatives

See Thanos and Prometheus Long-Term Storage.

Best Practices

Keep Local Prometheus for Fast Alerting

Many teams keep Prometheus or vmagent close to workloads and send data to VictoriaMetrics for global queries and history, avoiding a single point of failure for alerting.

Enable On-Disk Buffering in Agents

vmagent's persistent queue preserves data during network or database outages; size it for the longest outage you want to survive.

Watch Series Churn

Labels with unbounded values (request IDs, user IDs, pod names in short-lived jobs) drive memory and storage. Drop or aggregate them with relabeling or stream aggregation.

Test Alert Expressions After Migration

MetricsQL differs from PromQL in a few edge cases. Run critical alerts against both systems in parallel during migration.

Common Mistakes

Forgetting Deduplication for HA Pairs

Unbounded Cardinality

No Backups Because "It's Just Metrics"

FAQ

What is VictoriaMetrics?

An open-source, Prometheus-compatible time series database and monitoring toolkit designed for high performance, efficient storage, and simple operation, available as a single binary or a horizontally scalable cluster.

Can VictoriaMetrics replace Prometheus?

It can replace Prometheus's storage and scraping (with vmagent or built-in scraping) and its rule evaluation (with vmalert). Many teams instead keep Prometheus for local scraping and alerting and use VictoriaMetrics for long-term storage.

Is MetricsQL compatible with PromQL?

Largely. MetricsQL accepts PromQL queries and adds extensions, but a few functions behave differently in edge cases, so important alerts should be verified after migration.

When do I need the cluster version?

When a single node cannot handle your ingestion rate or series count, or when you need multi-tenancy or replication across storage nodes. Single-node handles very large workloads before that point.

How do I migrate data from Prometheus?

Start remote writing new data to VictoriaMetrics, then import historical data from Prometheus snapshots with vmctl, and run both in parallel until dashboards and alerts are verified.