English for VictoriaMetrics Developers
Vocabulary for developers running VictoriaMetrics — remote write, MetricsQL, downsampling, cardinality, and retention — for teams discussing time-series metrics infrastructure in English.
VictoriaMetrics is a fast, cost-efficient time-series database that’s largely Prometheus-compatible, built to handle the scale and cardinality problems that make long-term Prometheus storage expensive. Its vocabulary overlaps heavily with the broader Prometheus ecosystem, but a few terms — cardinality, downsampling, remote write — come up constantly in capacity and cost discussions. Here’s the English your team needs.
Ingesting Metrics
Remote write — the protocol Prometheus (or any compatible agent) uses to push scraped metrics into a long-term storage backend like VictoriaMetrics, instead of Prometheus storing them locally forever. “We pointed Prometheus’s remote write at the VictoriaMetrics cluster so local disk only needs to hold a few hours of buffer, not months of history.”
Scrape target — an endpoint that exposes metrics in a Prometheus-compatible format, which a scraper polls on an interval to collect data points. “The new service wasn’t showing up in dashboards because we forgot to register it as a scrape target — the metrics endpoint existed but nothing was pulling from it.”
Time series — a sequence of timestamped data points sharing the same metric name and label set, the fundamental unit VictoriaMetrics stores and queries. “Each unique combination of labels creates a new time series — that’s the detail that turns an innocent-looking metric into a cardinality problem.”
Querying with MetricsQL
MetricsQL
MetricsQL is VictoriaMetrics’s query language — a superset of PromQL with additional functions and syntax conveniences, so most existing Prometheus queries work unchanged.
“We didn’t have to rewrite our alerting rules for the migration — MetricsQL is backward-compatible with the PromQL we already had.”
Rate and Aggregation Functions
Functions like rate() and aggregation operators like sum by (...) are used to turn raw counters into meaningful per-second rates or grouped summaries.
“The dashboard was showing raw counter resets as spikes — wrapping the query in
rate()smoothed that out and gave us the actual requests-per-second trend.”
Cardinality and Cost
Cardinality — the number of unique time series a metric produces, driven by how many distinct label value combinations exist; high cardinality is the single biggest driver of storage and query cost in time-series systems.
“Adding
user_idas a label multiplied our cardinality by the number of active users overnight — we reverted it and moved that detail into logs instead.”
Downsampling — reducing the resolution of older data (storing hourly averages instead of per-second points) to cut storage cost while keeping long-term trend visibility.
“After 30 days we downsample to five-minute resolution — nobody needs second-level granularity for a graph covering the last six months.”
Retention period — how long raw or downsampled data is kept before being deleted, configured per use case to balance storage cost against how far back you need to investigate incidents.
“We set a 13-month retention period so we can always compare this month against the same month last year, without paying to keep every second-level data point that long.”
Operating the Cluster
vmagent — VictoriaMetrics’s lightweight scraping and remote-write agent, often used as a drop-in replacement for Prometheus’s own scraping when you don’t need Prometheus’s local storage.
“We swapped Prometheus for vmagent on the edge nodes — it has a much smaller memory footprint since it doesn’t need to store anything locally.”
Cluster mode (vminsert/vmstorage/vmselect) — the horizontally scalable deployment mode where ingestion, storage, and querying are split into separate, independently scalable components.
“We’re still on single-node VictoriaMetrics — cluster mode is on the roadmap once ingestion volume outgrows what one instance can handle.”
Explaining VictoriaMetrics to a Team
| Situation | Phrase |
|---|---|
| Justifying the migration from raw Prometheus | ”Long-term storage and cardinality management were becoming a real cost center — VictoriaMetrics compresses far better and our existing PromQL queries still work.” |
| Explaining a cost spike | ”That new label pushed cardinality way up — we’re generating a new time series per unique value, and that’s what’s driving the storage bill.” |
| Describing a retention decision | ”We downsample after 30 days and drop raw data after a year — that keeps recent debugging detailed while controlling long-term storage cost.” |
| Discussing scaling | ”Once single-node ingestion becomes the bottleneck, cluster mode lets us scale ingestion and querying independently.” |
Common Mistakes
- Adding high-cardinality labels (user IDs, request IDs) to metrics without realizing each unique value creates a new stored time series.
- Saying “PromQL” when the query actually uses a MetricsQL-only extension — worth flagging in code review since it affects portability back to plain Prometheus.
- Confusing retention (how long data is kept) with downsampling (at what resolution it’s kept) — a team can downsample without shortening retention, or vice versa.
Practice Exercise
- Explain, in two sentences, why high cardinality is a cost problem rather than just a query-performance problem.
- Write a short PR description for adding a downsampling rule that reduces resolution after 30 days.
- Draft a message justifying a move from local Prometheus storage to VictoriaMetrics remote write, focused on retention and cost.