Skip to main content
In this lesson we cover selectors and matchers in Prometheus: how to narrow down metric queries using label filters, the supported matcher operators, regex usage, and the difference between instant- and range-vectors. When you query Prometheus with only a metric name (for example, node_filesystem_avail_bytes), Prometheus returns all time series that have that metric:
Sample instant-vector output (all series for that metric):
To restrict which series are returned, use label matchers. Label matchers select time series by matching label key/value pairs.
A dark-themed infographic titled "Matchers" that explains label matchers for time series, with a highlighted "Label Matchers" header. It shows operator icons (=, !=, =, !) alongside short descriptions of exact match, negative match, regex match, etc.

​
Equality matcher

To return all time series coming from node1, filter by the instance label:
Sample output (only the node1 series remain):

​
Negative equality matcher

Exclude series whose device label equals tmpfs:
Sample output (series with device="tmpfs" are excluded):

​
Regex matcher

Use =~ for pattern matching. Prometheus uses RE2 regular expressions (no backtracking), so keep expressions RE2-compatible. Example: match devices that start with /dev/sda:
Sample output (only /dev/sda* devices are returned):
If you need more details about RE2 syntax, see the RE2 documentation: https://github.com/google/re2/wiki/Syntax.

​
Negative regex matcher

Exclude series whose mountpoint begins with /boot using !~:
Sample output (entries with mountpoint starting with /boot are excluded):

​
Combining selectors

Combine multiple label matchers by separating them with commas inside the braces. For example, to select series from node1 that are not tmpfs:
This returns node1 series whose device label is not tmpfs.

​
Range-vector selector

An instant vector returns the most recent sample for each matching series. A range vector returns all samples for each matching series over a specified time window. To form a range vector, append a duration in square brackets to an instant-vector expression. Example: get the last 2 minutes of node_arp_entries for node1:
Sample range-vector output (multiple samples for the series over the 2-minute window):
Always quote label values and regex patterns (for example, instance="node1" and device=~"/dev/sda.*"). When authoring PromQL in MDX/MD files, place any expression containing { or } inside code blocks or inline code so it does not get interpreted as JSX.

Watch Video