Docs

Volcengine Managed Service for Prometheus

Get started with PromQL

Basic usage of PromQL

This topic describes the basic usage of PromQL, which is the built-in data query language of Prometheus.

PromQL overview

In Prometheus, every time series is uniquely identified by its metric name and corresponding key-value pairs called labels. The metric name reflects the basic characteristics of the monitoring sample, and the labels provide multiple characteristic dimensions for the collected data based on the basic characteristics. You can filter, aggregate, and collect statistics on data based on these characteristic dimensions to generate a new time series after computing. As a built-in data query language of Prometheus, PromQL can be used to query, aggregate, and perform logical operations on time series data. PromQL is widely used in the daily application scenarios of Prometheus, including data query, visualization, and alert handling.

PromQL expressions

Each PromQL expression must contain at least a metric name (such as http_request_total) or a label filter (such as {code="200"}) that does not match an empty string. A metric name can be viewed as a label with the key __name__. Therefore, you can interpret that valid PromQL expressions must always contain non-empty filter conditions. Sample code:

Precautions

The metric name must not be one of the following keywords including bool, on, ignoring, group_left, and group_right. If the reported metric name is one of the preceding keywords, you need to replace the name with __name__.

Labels are frequently used for filtering. Sample code:

tip

In PromQL, the key of a label filter can be repeatedly configured. PromQL will finally parse the values as an AND relationship. For example, node_filesystem_free_bytes{mountpoint!="/data00", mountpoint!="/data01"} is equivalent to node_filesystem_free_bytes{mountpoint!~"/data00|/data01"}.

The PromQL query result will be empty: node_filesystem_free_bytes{mountpoint="/data00", mountpoint="/data02"}

Full match

PromQL supports two full match modes: = and !=.

Equal to. label=value is used to select the time series whose labels match the expression definition.

Not equal to. label!=value is used to exclude time series whose labels match the expression definition. For example, if you need to filter out all data whose code label is not 200, you can modify the PromQL expression to http_requests_total{code!=“200”}.

Regular expression matching

PromQL can also use regular expressions as matching conditions. Multiple matching conditions can be used.

Inclusive matching. label=~regx is used to select those time series whose labels match the regular expression definition.

Exclusive matching. label!~regx is used to exclude those time series whose labels match the regular expression definition. For example, if you want to query all handler labels that start with /api/v1 in the metric http_requests_total, you can use the expression http_requests_total{handler=~"/api/v1/.*"}.

Range query

Basic query

When you query time series by using a PromQL expression such as http_requests_total, only one data point is returned for the same metric with the same label. This kind of expression is called an instant-vector-typed expression, and the returned result is called an instant vector. If you want to query sample data within a period of time, you need to use a range vector expression, whose queried result is called a range vector. The time range is defined by the time range selector []. For example, you can use the following expression to select all sample data in the last 5 minutes:

The following table shows the time units supported in the time range selector.

Time offset

In instant-vector-typed expressions or range-vector-typed expressions, the current time is used as a benchmark by default. However, if you want to query the instant sample data in the last 5 minutes, or the sample data in the last day, you can perform the time offset operation. The keyword of the time offset operation is offset. Sample code:

The preceding sample code shows that offset can be used to compare vectors at different time points. Sample code:

In some special scenarios, if you want a PromQL query statement to use a specified time point instead of the current time as the benchmark, you need to use the @ modifier and follow @ with a standard Unix timestamp. The following sample code provides an example on the timestamp 1660404944 = "2022-08-13 23:35:44".

Aggregation operations

Generally, you can use PromQL to query a large amount of data. The aggregation operations provided by PromQL can be used to process these time series and form a new time series. Common aggregation operations include count and sum. For example:

Count: count(http_requests_total)

Sum the values of all data: sum(http_requests_total)

tip

For more details of aggregation operations, refer to PromQL aggregation operations.

Last updated: 2026.07.10 11:37:29