Prefer a guided lab? Take Introduction to PromQL
to learn fundamentals, or take PromQL 201 when you need
vector matching, aggregations over time, and other complex query patterns.
Basic querying
All PromQL expressions start with a selector, which is typically the name of the metric followed by a set of labels, values, and operators. A query returns one or more time series that match the criteria. PromQL refers to these as instant vectors because they represent a set of time series where every single data point maps to a timestamp at that instant.node_network_receive_bytes_total.
The following query returns all time series that match the metric name:
{}) after the metric name.
The following query returns all time series that match the metric name, and which
also have a device label whose value is equal to eth1:
device label whose value is equal to eth1 and an instance
label whose value is equal to production:
=: Select labels equal to the provided string.!=: Select labels not equal to the provided string.=~: Select labels that match the provided string based on a regular expression.!~: Select labels that don’t match the provided string based on a regular expression.
device label whose value matches eth followed by any non-zero number
of other characters:
Filter values to a range
Query results often must be filtered to a narrower time span or time-range offset. PromQL refers to these as range vectors because they represent a set of time series where every timestamp maps to a range of data points from some point in the past, as determined by the query. The following query returns all time series with anoffset of an hour (1h)
ago that match the metric name, and which also have a device label whose value
matches eth0:
offset modifier, see the
PromQL documentation.
You can use PromQL to return a range vector, then use a function to perform calculations
on the resulting range of time series.
The following query returns all time series from the last 10 minutes that match
the metric name, and which also have a device label whose value matches eth0:
Variables
Cortex XCOR provides built-in variables for PromQL queries. These are distinct from dashboard variables, and you can use both to write queries for dashboard panels.$__range: Defines a range for the current query or dashboard.$__rate_interval: Combines the tenant’s global scrape interval with the calculated step, using the formulaMath.max($__interval + scrapeInterval, 4 * scrapeInterval). This ensures reliable rate calculations. Be aware that the Grafana special variable$__rate_intervalhas unique behavior that might not be compatible with the Cortex XCOR Prometheus data source’s scrape interval. Cortex XCOR instead recommends using a separate$intervalvariable.$__interval: Automatically picks a step size based on the panel’s time range and its resolution setting (Low, Medium, or High), rounded to a value like15sor30s. A higher resolution produces a smaller step. If a minimum step (min_step) is set in your query, Cortex XCOR respects that.
Cortex XCOR-specific functions
Cortex XCOR extends standard PromQL with two categories of additional functions.Custom functions
Custom functions are Cortex XCOR-specific additions to PromQL that aren’t part of the Prometheus project. They’re stable, fully supported, and designed to address common observability use cases.Experimental functions
Experimental functions are upstream Prometheus functions available behind a feature flag. The Prometheus project might change or remove them without notice. Cortex XCOR enables a subset considered relatively stable and high value, and will provide a deprecation timeline for any breaking upstream changes.Other querying features
Cortex XCOR also provides querying features beyond those covered by using query languages in its user interface.- Delta queries: Query metrics that employ delta temporality, as opposed to cumulative temporality.
- Alert metrics: Query the
ALERTSmetric for triggered alert series and metadata. - Prometheus API access: Interact directly with Prometheus API endpoints for programmatic workflows.