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.
Related Resources
- English for TigerBeetle Developers
- English for Checkly Monitoring Developers
- English for Bugsnag Error Tracking Developers
Navigating Nuance: Addressing Feedback as a Non-Native Speaker
Learning professional English, particularly within the technical domain of VictoriaMetrics, can feel like deciphering a complex system itself. It’s not just about knowing the words; it’s understanding how those words are used in specific contexts and recognizing subtle differences in tone that can significantly impact communication. For non-native speakers, this can be especially challenging – the unspoken rules of code reviews, Slack discussions, and PR descriptions often rely heavily on established conventions built around native English fluency.
One common hurdle is framing feedback constructively. A simple “This doesn’t work” feels blunt and unhelpful. Instead, consider phrasing like: “I noticed a potential issue with the query’s performance; could we explore optimizing it for cardinality? Perhaps reducing the scope of the aggregation would alleviate some of the load.” Or, if reviewing code, “The logic here seems sound, but I was wondering about the readability of this section – might adding a comment explaining the intention improve maintainability?” Focusing on impact—how something affects performance, scalability, or clarity—is key. Similarly, when describing changes in a Pull Request, don’t just state “Fixed bug.” Instead, “This PR addresses a reported issue with intermittent data loss; I’ve implemented a retry mechanism and added logging to monitor the frequency of failures.”
Another area requiring careful attention is using precise terminology. While “downsampling” might seem straightforward, its implications – reducing resolution for historical data – can be nuanced when discussing retention policies or query performance. Similarly, understanding the difference between “remote write” (sending metrics data to VictoriaMetrics) and “MetricsQL queries” (analysing that data) is fundamental. Don’t assume everyone shares your intuitive grasp; explicitly defining terms, especially during discussions about infrastructure design, is a valuable practice.
Finally, remember that active listening plays a crucial role. If you’re unsure about something, ask for clarification. Asking “Could you elaborate on what you mean by ‘optimal cardinality’ in this context?” demonstrates engagement and reduces the risk of misinterpretation. Don’t be afraid to admit when you don’t fully understand – it’s far better than proceeding based on assumptions.
vm query -d my_metrics --query "sum(http_requests{status_code=200}) by {job}"This simple command, executed via the VictoriaMetrics CLI, demonstrates a common scenario: querying for aggregate metrics (HTTP requests with status code 200) grouped by job. The output – which you’d then discuss in a team setting – would likely involve considerations of cardinality (the number of unique jobs), retention policies (how long historical data is stored), and potentially downsampling if the query was returning too much data.