Prometheus promql

PromQL is prometheus's query language.
It's syntax is inspired by golang.
You can query prometheus from

• HTTP API
• UI table/graph view

Documentation

official docs	https://prometheus.io/docs/prometheus/latest/querying/basics/
official examples	https://prometheus.io/docs/prometheus/latest/querying/examples/
re2 (regex engine)	https://github.com/google/re2/wiki/Syntax

Comments

# a comment

Datatypes

Strings

# string
"foo"
`foo`

# string-literal
'foo\nbar'

Floats

23
-2.43
3.4e-9
0x8f
-Inf
NaN

Metric-Selectors

Basics

The most basic query you can use is your_metric_name which queries all samples for that metric.
These metric selectors can be composed and filtered.

{__name__="your_metric_name"}            # query all (you can match multiple metrics this way)

your_metric_name                         # query all
your_metric_name[5min]                   # lump data into 5min clumps
your_metric_name{job="foo",group="bar"}  # filter by metric-labels

Operators

label metrics support various matchers/operators

=   # equal
!=  # not-equal
=~  # regex match
!~  # not regex match

Clustering Metrics

TODO:

are these aggregates averages? sums? greatest-value?

your_metric_name[5min]   # lump data into 5min clumps

Units

ms  # milliseconds
s   # seconds
m   # minutes
h   # hours
d   # days
w   # weeks
y   # years

Query Time Ranges

your_metric_name offset 5min   # query 5min-ago until present

your_metric_name @ 1609746000 # query at exactly '2021-01-04T07:40:00+00:00'

Queries

Basics

A simple query is simply a metric-selector with an optional filter

your_metric_name{job="foo"}

SubQueries

You can combine functions and metrics.
From official examples:

rate(http_requests_total[5m])[30m:1m]

Metric Operators

You can do simple math using metrics.
There is some type-trickiness here, see docs for details.

metric_start - metric_end

math

+  # add
-  # subtract
*  # multiplication
/  # division
%  # modulo
^  # exponent

metric_1 and     metric_2  # only elements of metric_1 with exactly matching label-sets in metric_2
metric_1 or      metric_2  # all elements of metric_1, and elements of metric_2 with non-matching labels
metric_1 unless  metric_2  # only elements of metric_1, where there are no matching label-sets in metric_2

Metric Matching

Aggregates

sum(your_metric_name)                      # aggregate function
sum without (duration) (your_metric_name)  # excludes 'duration' labels from sum
sum by (job, duration) (your_metric_name)  # group sums by label 'job' and 'duration'

# simple
sum           # sum elements
min           # smallest of elements
max           # largest of elements
avg           # average of elements
count         # num of elements
count_values  # num elements with same value

# complex
group
stddev
stdvar
bottomk
topk
quantile

Functions

There are several builtin functions.