= PromQL =

'''PromQL''' is a query language built for the Prometheus project. It specializes in time series queries.

<<TableOfContents>>

----



== 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]))
}}}



----
CategoryRicottone