Selectors and Matchers

Pick series by name and labels

A selector such as http_requests_total{job="orders-api", status=~"5.."} returns matching series. Label matchers are =, !=, =~ (regex match) and !~ (regex non-match). An instant vector has one sample per series at the evaluation time; adding a duration in brackets, as in [5m], gives a range vector with all samples in that window, which functions like rate need. offset 1h shifts the window back for comparisons.

Asking questions of time series

Selectors, rate functions and aggregation answer most monitoring questions.

Selector examples

PromQL.

# all 5xx responses of the orders API (instant vector)
http_requests_total{job="orders-api", status=~"5.."}

# last 5 minutes of samples (range vector, input to rate())
http_requests_total{job="orders-api"}[5m]

# targets that are down
up == 0

# the same series one day ago
http_requests_total{job="orders-api"} offset 1d

Regex matchers are fully anchored

status=~"5.." matches 500 to 599 but not 1500, because PromQL regexes match the whole value.

Quick check: Which matcher selects labels matching a regular expression?

• =~
• ==
• !=
• ~~