PromQL
PromQL is a query language built for the Prometheus project. It specializes in time series queries.
Basic Queries
To query all 5xx HTTP errors, try:
http_requests_total{status="500"}To query the per-second rate of those errors over 5 minutes, try:
rate(http_requests_total{status="500"}[5m])This demonstrates how time series are a native data structure in PromQL.
Label Dimensions
Data can be split by label dimensions using the by clause. To query the per-second, per-page rate of 5xx errors over 5 minutes, try:
by(path) rate(http_requests_total{status="500"}[5m])The without clause operates inversely. It splits data by all dimensions except those lists.
Aggregation
The following aggregation operators are built in.
sum - calculate sum over dimensions
min - select minimum over dimensions
max - select maximum over dimensions
avg - calculate the average over dimensions
group - all values in the resulting vector are 1
stddev - calculate population standard deviation over dimensions
stdvar - calculate population standard variance over dimensions
count - count number of elements in the vector
count_values - count number of elements with the same value
bottomk - smallest k elements by sample value
topk - largest k elements by sample value
quantile - calculate φ-quantile over dimensions
quantile(0.5, ...) would calculate the median
As indicated, data can be aggregated over label dimensions. sum(http_requests_total) would return the total number of HTTP requests, while sum by(path) (http_requests_total) would return the total numbers of HTTP requests per page.
Functional Programming
Queries can be functionally combined as shown below, to compute the error rate:
sum(rate(http_requests_total{status="500"}[5m]))
/ sum(rate(http_requests_total{}[5m]))
Vectors
Operators including division (/) are capable of matching left-hand and right-hand vectors. To compute the per-page error rate, try:
sum by(path) (rate(http_requests_total{status="500"}[5m]))
/ sum by(path) (rate(http_requests_total{}[5m]))