PromQL is a language used in Prometheus to query time series data. Its core lies in filtering, aggregating and transforming data through indicator names and tags. 1. It supports directly entering the metric name to view relevant time series; 2. Use tag filtering such as {job="node-exporter"} to narrow the range; 3. Provide functions such as rate() to handle incremental counters; 4. Distinguish between real-time vectors (such as up) and range vectors (such as rate() required); 5. Can be used to calculate request rate, error rate and aggregate data across instances, such as avg() by (instance). Mastering PromQL helps build monitoring dashboards and set alert rules.

Prometheus Query Language, or PromQL, is the specialized language used to retrieve and work with time-series data stored in Prometheus. It's what you use when you're querying metrics—like CPU usage, memory consumption, or request latency—cross your systems.

Understanding Time-Series Data in PromQL

At its core, Prometheus collects metrics as time-series data. Each metric has a name (like http_requests_total ) and optional labels that provide additional dimensions such as method, status code, or instance.
For example:
http_requests_total{job="api-server", method="POST", status="200"}

PromQL lets you filter, aggregate, and transform these time series. You can select raw values, apply mathematical operations, or group and sum across instances. The key thing to understand is that everything in PromQL reverses around these labeled time series.

Some basic ways to get started include:

• Typing a metric name directly into the expression browser to see all associated time series.
• Adding label filters to narrow down results, like {job="node-exporter"} .
• Using functions like rate() or increase() for counters that only go up.

Working with Instant Vectors and Range Vectors

PromQL deals with two main types of data: instant vectors and range vectors.

An instant vector is a set of time series that each have a single value at the current evaluation time. For example, up gives you the current status of all your targets right now.

A range vector , on the other hand, contains a range of data points over time. These are mainly used with functions like rate() , avg_over_time() , or histogram_quantile() . They're especially useful when analyzing trends or calculating averages over a period.

The distinction matters because not all functions work on both types. For example, rate() expects a counter metric over a time window, so it needs a range vector. But abs() works only on instant vectors since it operates on a per-value basis.

Common Use Cases and Examples

PromQL really shines when you start applying it to real-world monitoring tasks.

If you want to know how many requests per second your API is handling, you might write something like:

 rate(http_requests_total[5m])

This shows the per-second average rate of HTTP requests over the last 5 minutes.

Or if you're trying to calculate error rates:

 rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

This divides the rate of 5xx errors by the total request rate to give you an error percentage.

Another common scenario is aggregating metrics across multiple instances. Let's say you want the average CPU usage across all your servers:

 avg(rate(node_cpu_seconds_total{mode!="idle"}[5m])) by (instance)

Here, we're filtering out idle time, calculating the rate, then grouping the result by instance.

These aren't just queries—they're the foundation for dashboards, alerts, and deeper analysis in Prometheus.

Final Thoughts

PromQL takes some getting used to, especially if you're coming from SQL or another query language. But once you grap how metrics and labels work together, it becomes a powerful tool for understanding your system's behavior.
It's not overly complex, but there are enough nuances—like handling counters vs. gauges or knowing when to use by vs. without —that it pays to experiment and dig into the official docs occasionally.

Basically that's it.

The above is the detailed content of What is the Prometheus Query Language (PromQL)?. For more information, please follow other related articles on the PHP Chinese website!