mudhorn/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2025-03-05 20:59:13 -08:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

docs: Update PromQL documentation to match the native histogram spec

Browse source 
This is also meant to document the actual implementation, but
see #13934 for the current state.

This also improves and streamlines some parts of the documentation
that are not strictly native histogram related, but are colocated with
them. In particular, the section about aggregation operators got
restructured quite a bit, including the removal of a quite verbose
example for `limit_ratio` (which was just too long an this location
and also a bit questionabl in its usefulness).

Signed-off-by: beorn7 <beorn@grafana.com>
This commit is contained in:
beorn7 2024-12-12 23:54:15 +01:00
parent f405c78e4a
commit 993d4e71c9
3 changed files with 400 additions and 318 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
docs/querying/basics.md
View file

@ -47,7 +47,19 @@ _Notes about the experimental native histograms:_
disabling the feature flag again), both instant vectors and range vectors may disabling the feature flag again), both instant vectors and range vectors may
now contain samples that aren't simple floating point numbers (float samples) now contain samples that aren't simple floating point numbers (float samples)
but complete histograms (histogram samples). A vector may contain a mix of but complete histograms (histogram samples). A vector may contain a mix of
float samples and histogram samples. float samples and histogram samples. Note that the term “histogram sample” in
the PromQL documentation always refers to a native histogram. Classic
histograms are broken up into a number of series of float samples. From the
perspective of PromQL, there are no “classic histogram samples”.
* Like float samples, histogram samples can be counters or gauges, also called
counter histograms or gauge histograms, respectively.
* Native histograms can have different bucket layouts, but they are generally
convertible to compatible versions to apply binary and aggregation operations
to them. This is not true for all bucketing schemas. If incompatible
histograms are encountered in an operation, the corresponding output vector
element is removed from the result, flagged with a warn-level annotation.
More details can be found in the
[native histogram specification](https://prometheus.io/docs/specs/native_histograms/#compatibility-between-histograms).
## Literals ## Literals

486
docs/querying/functions.md
View file

@ -11,30 +11,17 @@ instant-vector)`. This means that there is one argument `v` which is an instant
vector, which if not provided it will default to the value of the expression vector, which if not provided it will default to the value of the expression
`vector(time())`. `vector(time())`.
_Notes about the experimental native histograms:_
* Ingesting native histograms has to be enabled via a [feature
flag](../feature_flags.md#native-histograms). As long as no native histograms
have been ingested into the TSDB, all functions will behave as usual.
* Functions that do not explicitly mention native histograms in their
documentation (see below) will ignore histogram samples.
* Functions that do already act on native histograms might still change their
behavior in the future.
* If a function requires the same bucket layout between multiple native
histograms it acts on, it will automatically convert them
appropriately. (With the currently supported bucket schemas, that's always
possible.)
## `abs()` ## `abs()`
`abs(v instant-vector)` returns the input vector with all sample values converted to `abs(v instant-vector)` returns a vector containing all float samples in the
their absolute value. input vector converted to their absolute value. Histogram samples in the input
vector are ignored silently.
## `absent()` ## `absent()`
`absent(v instant-vector)` returns an empty vector if the vector passed to it `absent(v instant-vector)` returns an empty vector if the vector passed to it
has any elements (floats or native histograms) and a 1-element vector with the has any elements (float samples or histogram samples) and a 1-element vector
value 1 if the vector passed to it has no elements. with the value 1 if the vector passed to it has no elements.
This is useful for alerting on when no time series exist for a given metric name This is useful for alerting on when no time series exist for a given metric name
and label combination. and label combination.
@ -56,8 +43,9 @@ of the 1-element output vector from the input vector.
## `absent_over_time()` ## `absent_over_time()`
`absent_over_time(v range-vector)` returns an empty vector if the range vector `absent_over_time(v range-vector)` returns an empty vector if the range vector
passed to it has any elements (floats or native histograms) and a 1-element passed to it has any elements (float samples or histogram samples) and a
vector with the value 1 if the range vector passed to it has no elements. 1-element vector with the value 1 if the range vector passed to it has no
elements.
This is useful for alerting on when no time series exist for a given metric name This is useful for alerting on when no time series exist for a given metric name
and label combination for a certain amount of time. and label combination for a certain amount of time.
@ -78,8 +66,9 @@ labels of the 1-element output vector from the input vector.
## `ceil()` ## `ceil()`
`ceil(v instant-vector)` rounds the sample values of all elements in `v` up to `ceil(v instant-vector)` returns a vector containing all float samples in the
the nearest integer value greater than or equal to v. input vector rounded up to the nearest integer value greater than or equal to
their original value. Histogram samples in the input vector are ignored silently.
* `ceil(+Inf) = +Inf` * `ceil(+Inf) = +Inf`
* `ceil(±0) = ±0` * `ceil(±0) = ±0`
@ -90,49 +79,62 @@ the nearest integer value greater than or equal to v.
For each input time series, `changes(v range-vector)` returns the number of For each input time series, `changes(v range-vector)` returns the number of
times its value has changed within the provided time range as an instant times its value has changed within the provided time range as an instant
vector. vector. A float sample followed by a histogram sample, or vice versa, counts as
a change. A counter histogram sample followed by a gauge histogram sample with
otherwise exactly the same values, or vice versa, does not count as a change.
## `clamp()` ## `clamp()`
`clamp(v instant-vector, min scalar, max scalar)` `clamp(v instant-vector, min scalar, max scalar)` clamps the values of all
clamps the sample values of all elements in `v` to have a lower limit of `min` and an upper limit of `max`. float samples in `v` to have a lower limit of `min` and an upper limit of
`max`. Histogram samples in the input vector are ignored silently.
Special cases: Special cases:
* Return an empty vector if `min > max` * Return an empty vector if `min > max`
* Return `NaN` if `min` or `max` is `NaN` * Float samples are clamped to `NaN` if `min` or `max` is `NaN`
## `clamp_max()` ## `clamp_max()`
`clamp_max(v instant-vector, max scalar)` clamps the sample values of all `clamp_max(v instant-vector, max scalar)` clamps the values of all float
elements in `v` to have an upper limit of `max`. samples in `v` to have an upper limit of `max`. Histogram samples in the input
vector are ignored silently.
## `clamp_min()` ## `clamp_min()`
`clamp_min(v instant-vector, min scalar)` clamps the sample values of all `clamp_min(v instant-vector, min scalar)` clamps the values of all float
elements in `v` to have a lower limit of `min`. samples in `v` to have a lower limit of `min`. Histogram samples in the input
vector are ignored silently.
## `day_of_month()` ## `day_of_month()`
`day_of_month(v=vector(time()) instant-vector)` returns the day of the month `day_of_month(v=vector(time()) instant-vector)` interpretes float samples in
for each of the given times in UTC. Returned values are from 1 to 31. `v` as timestamps (number of seconds since January 1, 1970 UTC) and returns the
day of the month (in UTC) for each of those timestamps. Returned values are
from 1 to 31. Histogram samples in the input vector are ignored silently.
## `day_of_week()` ## `day_of_week()`
`day_of_week(v=vector(time()) instant-vector)` returns the day of the week for `day_of_week(v=vector(time()) instant-vector)` interpretes float samples in `v`
each of the given times in UTC. Returned values are from 0 to 6, where 0 means as timestamps (number of seconds since January 1, 1970 UTC) and returns the day
Sunday etc. of the week (in UTC) for each of those timestamps. Returned values are from 0
to 6, where 0 means Sunday etc. Histogram samples in the input vector are
ignored silently.
## `day_of_year()` ## `day_of_year()`
`day_of_year(v=vector(time()) instant-vector)` returns the day of the year for `day_of_year(v=vector(time()) instant-vector)` interpretes float samples in `v`
each of the given times in UTC. Returned values are from 1 to 365 for non-leap years, as timestamps (number of seconds since January 1, 1970 UTC) and returns the day
and 1 to 366 in leap years. of the year (in UTC) for each of those timestamps. Returned values are from 1
to 365 for non-leap years, and 1 to 366 in leap years. Histogram samples in the
input vector are ignored silently.
## `days_in_month()` ## `days_in_month()`
`days_in_month(v=vector(time()) instant-vector)` returns number of days in the `days_in_month(v=vector(time()) instant-vector)` interpretes float samples in
month for each of the given times in UTC. Returned values are from 28 to 31. `v` as timestamps (number of seconds since January 1, 1970 UTC) and returns the
number of days in the month of each of those timestamps (in UTC). Returned
values are from 28 to 31. Histogram samples in the input vector are ignored silently.
## `delta()` ## `delta()`
@ -150,36 +152,67 @@ between now and 2 hours ago:
delta(cpu_temp_celsius{host="zeus"}[2h]) delta(cpu_temp_celsius{host="zeus"}[2h])
``` ```
`delta` acts on native histograms by calculating a new histogram where each `delta` acts on histogram samples by calculating a new histogram where each
component (sum and count of observations, buckets) is the difference between component (sum and count of observations, buckets) is the difference between
the respective component in the first and last native histogram in the respective component in the first and last native histogram in `v`.
`v`. However, each element in `v` that contains a mix of float and native However, each element in `v` that contains a mix of float samples and histogram
histogram samples within the range, will be missing from the result vector. samples within the range will be omitted from the result vector, flagged by a
warn-level annotation.
`delta` should only be used with gauges and native histograms where the `delta` should only be used with gauges (for both floats and histograms).
components behave like gauges (so-called gauge histograms).
## `deriv()` ## `deriv()`
`deriv(v range-vector)` calculates the per-second derivative of the time series in a range `deriv(v range-vector)` calculates the per-second derivative of each float time
vector `v`, using [simple linear regression](https://en.wikipedia.org/wiki/Simple_linear_regression). series in the range vector `v`, using [simple linear
The range vector must have at least two samples in order to perform the calculation. When `+Inf` or regression](https://en.wikipedia.org/wiki/Simple_linear_regression). The range
`-Inf` are found in the range vector, the slope and offset value calculated will be `NaN`. vector must have at least two float samples in order to perform the
calculation. When `+Inf` or `-Inf` are found in the range vector, the slope and
offset value calculated will be `NaN`.
`deriv` should only be used with gauges. `deriv` should only be used with gauges and only works for float samples.
Elements in the range vector that contain only histogram samples are ignored
entirely. For elements that contain a mix of float and histogram samples, only
the float samples are used as input, which is flagged by an info-level
annotation.
## `double_exponential_smoothing()`
**This function has to be enabled via the [feature
flag](../feature_flags.md#experimental-promql-functions)
`--enable-feature=promql-experimental-functions`.**
`double_exponential_smoothing(v range-vector, sf scalar, tf scalar)` produces a
smoothed value for each float time series in the range in `v`. The lower the
smoothing factor `sf`, the more importance is given to old data. The higher the
trend factor `tf`, the more trends in the data is considered. Both `sf` and
`tf` must be between 0 and 1. For additional details, refer to [NIST
Engineering Statistics
Handbook](https://www.itl.nist.gov/div898/handbook/pmc/section4/pmc433.htm). In
Prometheus V2 this function was called `holt_winters`. This caused confusion
since the Holt-Winters method usually refers to triple exponential smoothing.
Double exponential smoothing as implemented here is also referred to as "Holt
Linear".
`double_exponential_smoothing` should only be used with gauges and only works
for float samples. Elements in the range vector that contain only histogram
samples are ignored entirely. For elements that contain a mix of float and
histogram samples, only the float samples are used as input, which is flagged
by an info-level annotation.
## `exp()` ## `exp()`
`exp(v instant-vector)` calculates the exponential function for all elements in `v`. `exp(v instant-vector)` calculates the exponential function for all float
Special cases are: samples in `v`. Histogram samples are ignored silently. Special cases are:
* `Exp(+Inf) = +Inf` * `Exp(+Inf) = +Inf`
* `Exp(NaN) = NaN` * `Exp(NaN) = NaN`
## `floor()` ## `floor()`
`floor(v instant-vector)` rounds the sample values of all elements in `v` down `floor(v instant-vector)` returns a vector containing all float samples in the
to the nearest integer value smaller than or equal to v. input vector rounded down to the nearest integer value smaller than or equal
to their original value. Histogram samples in the input vector are ignored silently.
* `floor(+Inf) = +Inf` * `floor(+Inf) = +Inf`
* `floor(±0) = ±0` * `floor(±0) = ±0`
@ -188,12 +221,8 @@ to the nearest integer value smaller than or equal to v.
## `histogram_avg()` ## `histogram_avg()`
_This function only acts on native histograms, which are an experimental `histogram_avg(v instant-vector)` returns the arithmetic average of observed
feature. The behavior of this function may change in future versions of values stored in each histogram sample in `v`. Float samples are ignored and do
Prometheus, including its removal from PromQL._
`histogram_avg(v instant-vector)` returns the arithmetic average of observed values stored in
a native histogram. Samples that are not native histograms are ignored and do
not show up in the returned vector. not show up in the returned vector.
Use `histogram_avg` as demonstrated below to compute the average request duration Use `histogram_avg` as demonstrated below to compute the average request duration
@ -209,32 +238,25 @@ Which is equivalent to the following query:
## `histogram_count()` and `histogram_sum()` ## `histogram_count()` and `histogram_sum()`
_Both functions only act on native histograms, which are an experimental
feature. The behavior of these functions may change in future versions of
Prometheus, including their removal from PromQL._
`histogram_count(v instant-vector)` returns the count of observations stored in `histogram_count(v instant-vector)` returns the count of observations stored in
a native histogram. Samples that are not native histograms are ignored and do each histogram sample in `v`. Float samples are ignored and do not show up in
not show up in the returned vector. the returned vector.
Similarly, `histogram_sum(v instant-vector)` returns the sum of observations Similarly, `histogram_sum(v instant-vector)` returns the sum of observations
stored in a native histogram. stored in each histogram sample.
Use `histogram_count` in the following way to calculate a rate of observations Use `histogram_count` in the following way to calculate a rate of observations
(in this case corresponding to “requests per second”) from a native histogram: (in this case corresponding to “requests per second”) from a series of
histogram samples:
histogram_count(rate(http_request_duration_seconds[10m])) histogram_count(rate(http_request_duration_seconds[10m]))
## `histogram_fraction()` ## `histogram_fraction()`
_This function only acts on native histograms, which are an experimental `histogram_fraction(lower scalar, upper scalar, v instant-vector)` returns the
feature. The behavior of this function may change in future versions of estimated fraction of observations between the provided lower and upper values
Prometheus, including its removal from PromQL._ for each histogram sample in `v`. Float samples are ignored and do not show up
in the returned vector.
For a native histogram, `histogram_fraction(lower scalar, upper scalar, v
instant-vector)` returns the estimated fraction of observations between the
provided lower and upper values. Samples that are not native histograms are
ignored and do not show up in the returned vector.
For example, the following expression calculates the fraction of HTTP requests For example, the following expression calculates the fraction of HTTP requests
over the last hour that took 200ms or less: over the last hour that took 200ms or less:
@ -253,12 +275,13 @@ observations less than or equal 0.2 would be `-Inf` rather than `0`.
Whether the provided boundaries are inclusive or exclusive is only relevant if Whether the provided boundaries are inclusive or exclusive is only relevant if
the provided boundaries are precisely aligned with bucket boundaries in the the provided boundaries are precisely aligned with bucket boundaries in the
underlying native histogram. In this case, the behavior depends on the schema underlying native histogram. In this case, the behavior depends on the schema
definition of the histogram. The currently supported schemas all feature definition of the histogram. (The usual standard exponential schemas all
inclusive upper boundaries and exclusive lower boundaries for positive values feature inclusive upper boundaries and exclusive lower boundaries for positive
(and vice versa for negative values). Without a precise alignment of values, and vice versa for negative values.) Without a precise alignment of
boundaries, the function uses linear interpolation to estimate the boundaries, the function uses interpolation to estimate the fraction. With the
fraction. With the resulting uncertainty, it becomes irrelevant if the resulting uncertainty, it becomes irrelevant if the boundaries are inclusive or
boundaries are inclusive or exclusive. exclusive. The interpolation method is the same as the one used for
`histogram_quantile()`. See there for more details.
## `histogram_quantile()` ## `histogram_quantile()`
@ -270,10 +293,6 @@ summaries](https://prometheus.io/docs/practices/histograms) for a detailed
explanation of φ-quantiles and the usage of the (classic) histogram metric explanation of φ-quantiles and the usage of the (classic) histogram metric
type in general.) type in general.)
_Note that native histograms are an experimental feature. The behavior of this
function when dealing with native histograms may change in future versions of
Prometheus._
The float samples in `b` are considered the counts of observations in each The float samples in `b` are considered the counts of observations in each
bucket of one or more classic histograms. Each float sample must have a label bucket of one or more classic histograms. Each float sample must have a label
`le` where the label value denotes the inclusive upper bound of the bucket. `le` where the label value denotes the inclusive upper bound of the bucket.
@ -284,8 +303,8 @@ type](https://prometheus.io/docs/concepts/metric_types/#histogram)
automatically provides time series with the `_bucket` suffix and the automatically provides time series with the `_bucket` suffix and the
appropriate labels. appropriate labels.
The native histogram samples in `b` are treated each individually as a separate The (native) histogram samples in `b` are treated each individually as a
histogram to calculate the quantile from. separate histogram to calculate the quantile from.
As long as no naming collisions arise, `b` may contain a mix of classic As long as no naming collisions arise, `b` may contain a mix of classic
and native histograms. and native histograms.
@ -336,7 +355,9 @@ non-zero-buckets of native histograms with a standard exponential bucketing
schema, the interpolation is done under the assumption that the samples within schema, the interpolation is done under the assumption that the samples within
the bucket are distributed in a way that they would uniformly populate the the bucket are distributed in a way that they would uniformly populate the
buckets in a hypothetical histogram with higher resolution. (This is also buckets in a hypothetical histogram with higher resolution. (This is also
called _exponential interpolation_.) called _exponential interpolation_. See the [native histogram
specification](https://prometheus.io/docs/specs/native_histograms/#interpolation-within-a-bucket)
for more details.)
If `b` has 0 observations, `NaN` is returned. For φ < 0, `-Inf` is If `b` has 0 observations, `NaN` is returned. For φ < 0, `-Inf` is
returned. For φ > 1, `+Inf` is returned. For φ = `NaN`, `NaN` is returned. returned. For φ > 1, `+Inf` is returned. For φ = `NaN`, `NaN` is returned.
@ -387,63 +408,46 @@ difference between two buckets is a trillionth (1e-12) of the sum of both
buckets.) Furthermore, if there are non-monotonic bucket counts even after this buckets.) Furthermore, if there are non-monotonic bucket counts even after this
adjustment, they are increased to the value of the previous buckets to enforce adjustment, they are increased to the value of the previous buckets to enforce
monotonicity. The latter is evidence for an actual issue with the input data monotonicity. The latter is evidence for an actual issue with the input data
and is therefore flagged with an informational annotation reading `input to and is therefore flagged by an info-level annotation reading `input to
histogram_quantile needed to be fixed for monotonicity`. If you encounter this histogram_quantile needed to be fixed for monotonicity`. If you encounter this
annotation, you should find and remove the source of the invalid data. annotation, you should find and remove the source of the invalid data.
## `histogram_stddev()` and `histogram_stdvar()` ## `histogram_stddev()` and `histogram_stdvar()`
_Both functions only act on native histograms, which are an experimental
feature. The behavior of these functions may change in future versions of
Prometheus, including their removal from PromQL._
`histogram_stddev(v instant-vector)` returns the estimated standard deviation `histogram_stddev(v instant-vector)` returns the estimated standard deviation
of observations in a native histogram, based on the geometric mean of the buckets of observations for each histogram sample in `v`, based on the geometric mean
where the observations lie. Samples that are not native histograms are ignored and of the buckets where the observations lie. Float samples are ignored and do not
do not show up in the returned vector. show up in the returned vector.
Similarly, `histogram_stdvar(v instant-vector)` returns the estimated standard Similarly, `histogram_stdvar(v instant-vector)` returns the estimated standard
variance of observations in a native histogram. variance of observations for each histogram sample in `v`.
## `double_exponential_smoothing()`
**This function has to be enabled via the [feature flag](../feature_flags.md#experimental-promql-functions) `--enable-feature=promql-experimental-functions`.**
`double_exponential_smoothing(v range-vector, sf scalar, tf scalar)` produces a smoothed value
for time series based on the range in `v`. The lower the smoothing factor `sf`,
the more importance is given to old data. The higher the trend factor `tf`, the
more trends in the data is considered. Both `sf` and `tf` must be between 0 and
1.
For additional details, refer to [NIST Engineering Statistics Handbook](https://www.itl.nist.gov/div898/handbook/pmc/section4/pmc433.htm).
In Prometheus V2 this function was called `holt_winters`. This caused confusion
since the Holt-Winters method usually refers to triple exponential smoothing.
Double exponential smoothing as implemented here is also referred to as "Holt
Linear".
`double_exponential_smoothing` should only be used with gauges.
## `hour()` ## `hour()`
`hour(v=vector(time()) instant-vector)` returns the hour of the day `hour(v=vector(time()) instant-vector)` interpretes float samples in `v` as
for each of the given times in UTC. Returned values are from 0 to 23. timestamps (number of seconds since January 1, 1970 UTC) and returns the hour
of the day (in UTC) for each of those timestamps. Returned values are from 0
to 23. Histogram samples in the input vector are ignored silently.
## `idelta()` ## `idelta()`
`idelta(v range-vector)` calculates the difference between the last two samples `idelta(v range-vector)` calculates the difference between the last two samples
in the range vector `v`, returning an instant vector with the given deltas and in the range vector `v`, returning an instant vector with the given deltas and
equivalent labels. equivalent labels. Both samples must be either float samples or histogram
samples. Elements in `v` where one of the last two samples is a float sample
and the other is a histogram sample will be omitted from the result vector,
flagged by a warn-level annotation.
`idelta` should only be used with gauges. `idelta` should only be used with gauges (for both floats and histograms).
## `increase()` ## `increase()`
`increase(v range-vector)` calculates the increase in the `increase(v range-vector)` calculates the increase in the time series in the
time series in the range vector. Breaks in monotonicity (such as counter range vector. Breaks in monotonicity (such as counter resets due to target
resets due to target restarts) are automatically adjusted for. The restarts) are automatically adjusted for. The increase is extrapolated to cover
increase is extrapolated to cover the full time range as specified the full time range as specified in the range vector selector, so that it is
in the range vector selector, so that it is possible to get a possible to get a non-integer result even if a counter increases only by
non-integer result even if a counter increases only by integer integer increments.
increments.
The following example expression returns the number of HTTP requests as measured The following example expression returns the number of HTTP requests as measured
over the last 5 minutes, per time series in the range vector: over the last 5 minutes, per time series in the range vector:
@ -452,19 +456,20 @@ over the last 5 minutes, per time series in the range vector:
increase(http_requests_total{job="api-server"}[5m]) increase(http_requests_total{job="api-server"}[5m])
``` ```
`increase` acts on native histograms by calculating a new histogram where each `increase` acts on histogram samples by calculating a new histogram where each
component (sum and count of observations, buckets) is the increase between component (sum and count of observations, buckets) is the increase between the
the respective component in the first and last native histogram in respective component in the first and last native histogram in `v`. However,
`v`. However, each element in `v` that contains a mix of float and native each element in `v` that contains a mix of float samples and histogram samples
histogram samples within the range, will be missing from the result vector. within the range, will be omitted from the result vector, flagged by a
warn-level annotation.
`increase` should only be used with counters and native histograms where the `increase` should only be used with counters (for both floats and histograms).
components behave like counters. It is syntactic sugar for `rate(v)` multiplied It is syntactic sugar for `rate(v)` multiplied by the number of seconds under
by the number of seconds under the specified time range window, and should be the specified time range window, and should be used primarily for human
used primarily for human readability. Use `rate` in recording rules so that readability. Use `rate` in recording rules so that increases are tracked
increases are tracked consistently on a per-second basis. consistently on a per-second basis.
## `info()` (experimental) ## `info()`
_The `info` function is an experiment to improve UX _The `info` function is an experiment to improve UX
around including labels from [info metrics](https://grafana.com/blog/2021/08/04/how-to-use-promql-joins-for-more-effective-queries-of-prometheus-metrics-at-scale/#info-metrics). around including labels from [info metrics](https://grafana.com/blog/2021/08/04/how-to-use-promql-joins-for-more-effective-queries-of-prometheus-metrics-at-scale/#info-metrics).
@ -560,7 +565,12 @@ consider all matching info series and with their appropriate identifying labels.
`irate(v range-vector)` calculates the per-second instant rate of increase of `irate(v range-vector)` calculates the per-second instant rate of increase of
the time series in the range vector. This is based on the last two data points. the time series in the range vector. This is based on the last two data points.
Breaks in monotonicity (such as counter resets due to target restarts) are Breaks in monotonicity (such as counter resets due to target restarts) are
automatically adjusted for. automatically adjusted for. Both samples must be either float samples or
histogram samples. Elements in `v` where one of the last two samples is a float
sample and the other is a histogram sample will be omitted from the result
vector, flagged by a warn-level annotation.
`irate` should only be used with counters (for both floats and histograms).
The following example expression returns the per-second rate of HTTP requests The following example expression returns the per-second rate of HTTP requests
looking up to 5 minutes back for the two most recent data points, per time looking up to 5 minutes back for the two most recent data points, per time
@ -618,8 +628,8 @@ label_replace(up{job="api-server",service="a:c"}, "foo", "$name", "service", "(?
## `ln()` ## `ln()`
`ln(v instant-vector)` calculates the natural logarithm for all elements in `v`. `ln(v instant-vector)` calculates the natural logarithm for all float samples
Special cases are: in `v`. Histogram samples in the input vector are ignored silently. Special cases are:
* `ln(+Inf) = +Inf` * `ln(+Inf) = +Inf`
* `ln(0) = -Inf` * `ln(0) = -Inf`
@ -628,35 +638,45 @@ Special cases are:
## `log2()` ## `log2()`
`log2(v instant-vector)` calculates the binary logarithm for all elements in `v`. `log2(v instant-vector)` calculates the binary logarithm for all float samples
The special cases are equivalent to those in `ln`. in `v`. Histogram samples in the input vector are ignored silently. The special cases
are equivalent to those in `ln`.
## `log10()` ## `log10()`
`log10(v instant-vector)` calculates the decimal logarithm for all elements in `v`. `log10(v instant-vector)` calculates the decimal logarithm for all float
The special cases are equivalent to those in `ln`. samples in `v`. Histogram samples in the input vector are ignored silently. The special
cases are equivalent to those in `ln`.
## `minute()` ## `minute()`
`minute(v=vector(time()) instant-vector)` returns the minute of the hour for each `minute(v=vector(time()) instant-vector)` interpretes float samples in `v` as
of the given times in UTC. Returned values are from 0 to 59. timestamps (number of seconds since January 1, 1970 UTC) and returns the minute
of the hour (in UTC) for each of those timestamps. Returned values are from 0
to 59. Histogram samples in the input vector are ignored silently.
## `month()` ## `month()`
`month(v=vector(time()) instant-vector)` returns the month of the year for each `month(v=vector(time()) instant-vector)` interpretes float samples in `v` as
of the given times in UTC. Returned values are from 1 to 12, where 1 means timestamps (number of seconds since January 1, 1970 UTC) and returns the month
January etc. of the year (in UTC) for each of those timestamps. Returned values are from 1
to 12, where 1 means January etc. Histogram samples in the input vector are
ignored silently.
## `predict_linear()` ## `predict_linear()`
`predict_linear(v range-vector, t scalar)` predicts the value of time series `predict_linear(v range-vector, t scalar)` predicts the value of time series
`t` seconds from now, based on the range vector `v`, using [simple linear `t` seconds from now, based on the range vector `v`, using [simple linear
regression](https://en.wikipedia.org/wiki/Simple_linear_regression). regression](https://en.wikipedia.org/wiki/Simple_linear_regression). The range
The range vector must have at least two samples in order to perform the vector must have at least two float samples in order to perform the
calculation. When `+Inf` or `-Inf` are found in the range vector, calculation. When `+Inf` or `-Inf` are found in the range vector, the predicted
the slope and offset value calculated will be `NaN`. value will be `NaN`.
`predict_linear` should only be used with gauges. `predict_linear` should only be used with gauges and only works for float
samples. Elements in the range vector that contain only histogram samples are
ignored entirely. For elements that contain a mix of float and histogram
samples, only the float samples are used as input, which is flagged by an
info-level annotation.
## `rate()` ## `rate()`
@ -675,13 +695,13 @@ rate(http_requests_total{job="api-server"}[5m])
`rate` acts on native histograms by calculating a new histogram where each `rate` acts on native histograms by calculating a new histogram where each
component (sum and count of observations, buckets) is the rate of increase component (sum and count of observations, buckets) is the rate of increase
between the respective component in the first and last native histogram in between the respective component in the first and last native histogram in `v`.
`v`. However, each element in `v` that contains a mix of float and native However, each element in `v` that contains a mix of float and native histogram
histogram samples within the range, will be missing from the result vector. samples within the range, will be omitted from the result vector, flagged by a
warn-level annotation.
`rate` should only be used with counters and native histograms where the `rate` should only be used with counters (for both floats and histograms). It
components behave like counters. It is best suited for alerting, and for is best suited for alerting, and for graphing of slow-moving counters.
graphing of slow-moving counters.
Note that when combining `rate()` with an aggregation operator (e.g. `sum()`) Note that when combining `rate()` with an aggregation operator (e.g. `sum()`)
or a function aggregating over time (any function ending in `_over_time`), or a function aggregating over time (any function ending in `_over_time`),
@ -696,17 +716,15 @@ decrease in the value between two consecutive float samples is interpreted as a
counter reset. A reset in a native histogram is detected in a more complex way: counter reset. A reset in a native histogram is detected in a more complex way:
Any decrease in any bucket, including the zero bucket, or in the count of Any decrease in any bucket, including the zero bucket, or in the count of
observation constitutes a counter reset, but also the disappearance of any observation constitutes a counter reset, but also the disappearance of any
previously populated bucket, an increase in bucket resolution, or a decrease of previously populated bucket, a decrease of the zero-bucket width, or any schema
the zero-bucket width. change that is not a compatible decrease of resolution.
`resets` should only be used with counters and counter-like native `resets` should only be used with counters (for both floats and histograms).
histograms.
If the range vector contains a mix of float and histogram samples for the same A float sample followed by a histogram sample, or vice versa, counts as a
series, counter resets are detected separately and their numbers added up. The reset. A counter histogram sample followed by a gauge histogram sample, or vice
change from a float to a histogram sample is _not_ considered a counter versa, also counts as a reset (but note that `resets` should not be used on
reset. Each float sample is compared to the next float sample, and each gauges in the first place, see above).
histogram is comprared to the next histogram.
## `round()` ## `round()`
@ -714,53 +732,63 @@ histogram is comprared to the next histogram.
elements in `v` to the nearest integer. Ties are resolved by rounding up. The elements in `v` to the nearest integer. Ties are resolved by rounding up. The
optional `to_nearest` argument allows specifying the nearest multiple to which optional `to_nearest` argument allows specifying the nearest multiple to which
the sample values should be rounded. This multiple may also be a fraction. the sample values should be rounded. This multiple may also be a fraction.
Histogram samples in the input vector are ignored silently.
## `scalar()` ## `scalar()`
Given a single-element input vector, `scalar(v instant-vector)` returns the Given an input vector that contains only one element with a float sample,
sample value of that single element as a scalar. If the input vector does not `scalar(v instant-vector)` returns the sample value of that float sample as a
have exactly one element, `scalar` will return `NaN`. scalar. If the input vector does not have exactly one element with a float
sample, `scalar` will return `NaN`. Histogram samples in the input vector are
ignored silently.
## `sgn()` ## `sgn()`
`sgn(v instant-vector)` returns a vector with all sample values converted to their sign, defined as this: 1 if v is positive, -1 if v is negative and 0 if v is equal to zero. `sgn(v instant-vector)` returns a vector with all float sample values converted
to their sign, defined as this: 1 if v is positive, -1 if v is negative and 0
if v is equal to zero. Histogram samples in the input vector are ignored silently.
## `sort()` ## `sort()`
`sort(v instant-vector)` returns vector elements sorted by their sample values, `sort(v instant-vector)` returns vector elements sorted by their float sample
in ascending order. Native histograms are sorted by their sum of observations. values, in ascending order. Histogram samples in the input vector are ignored silently.
Please note that `sort` only affects the results of instant queries, as range query results always have a fixed output ordering. Please note that `sort` only affects the results of instant queries, as range
query results always have a fixed output ordering.
## `sort_desc()` ## `sort_desc()`
Same as `sort`, but sorts in descending order. Same as `sort`, but sorts in descending order.
Like `sort`, `sort_desc` only affects the results of instant queries, as range query results always have a fixed output ordering.
## `sort_by_label()` ## `sort_by_label()`
**This function has to be enabled via the [feature flag](../feature_flags.md#experimental-promql-functions) `--enable-feature=promql-experimental-functions`.** **This function has to be enabled via the [feature
flag](../feature_flags.md#experimental-promql-functions)
`--enable-feature=promql-experimental-functions`.**
`sort_by_label(v instant-vector, label string, ...)` returns vector elements sorted by the values of the given labels in ascending order. In case these label values are equal, elements are sorted by their full label sets. `sort_by_label(v instant-vector, label string, ...)` returns vector elements
sorted by the values of the given labels in ascending order. In case these
label values are equal, elements are sorted by their full label sets.
`sort_by_label` acts on float and histogram samples in the same way.
Please note that the sort by label functions only affect the results of instant queries, as range query results always have a fixed output ordering. Please note that `sort_by_label` only affect the results of instant queries, as
range query results always have a fixed output ordering.
This function uses [natural sort order](https://en.wikipedia.org/wiki/Natural_sort_order). `sort_by_label` uses [natural sort
order](https://en.wikipedia.org/wiki/Natural_sort_order).
## `sort_by_label_desc()` ## `sort_by_label_desc()`
**This function has to be enabled via the [feature flag](../feature_flags.md#experimental-promql-functions) `--enable-feature=promql-experimental-functions`.** **This function has to be enabled via the [feature
flag](../feature_flags.md#experimental-promql-functions)
`--enable-feature=promql-experimental-functions`.**
Same as `sort_by_label`, but sorts in descending order. Same as `sort_by_label`, but sorts in descending order.
Please note that the sort by label functions only affect the results of instant queries, as range query results always have a fixed output ordering.
This function uses [natural sort order](https://en.wikipedia.org/wiki/Natural_sort_order).
## `sqrt()` ## `sqrt()`
`sqrt(v instant-vector)` calculates the square root of all elements in `v`. `sqrt(v instant-vector)` calculates the square root of all float samples in
`v`. Histogram samples in the input vector are ignored silently.
## `time()` ## `time()`
@ -771,66 +799,80 @@ expression is to be evaluated.
## `timestamp()` ## `timestamp()`
`timestamp(v instant-vector)` returns the timestamp of each of the samples of `timestamp(v instant-vector)` returns the timestamp of each of the samples of
the given vector as the number of seconds since January 1, 1970 UTC. It also the given vector as the number of seconds since January 1, 1970 UTC. It acts on
works with histogram samples. float and histogram samples in the same way.
## `vector()` ## `vector()`
`vector(s scalar)` returns the scalar `s` as a vector with no labels. `vector(s scalar)` converts the scalar `s` to a float sample and returns it as
a single-element instant vector with no labels.
## `year()` ## `year()`
`year(v=vector(time()) instant-vector)` returns the year `year(v=vector(time()) instant-vector)` returns the year for each of the given
for each of the given times in UTC. times in UTC. Histogram samples in the input vector are ignored silently.
## `<aggregation>_over_time()` ## `<aggregation>_over_time()`
The following functions allow aggregating each series of a given range vector The following functions allow aggregating each series of a given range vector
over time and return an instant vector with per-series aggregation results: over time and return an instant vector with per-series aggregation results:
* `avg_over_time(range-vector)`: the average value of all points in the specified interval. * `avg_over_time(range-vector)`: the average value of all float or histogram samples in the specified interval (see details below).
* `min_over_time(range-vector)`: the minimum value of all points in the specified interval. * `min_over_time(range-vector)`: the minimum value of all float samples in the specified interval.
* `max_over_time(range-vector)`: the maximum value of all points in the specified interval. * `max_over_time(range-vector)`: the maximum value of all float samples in the specified interval.
* `sum_over_time(range-vector)`: the sum of all values in the specified interval. * `sum_over_time(range-vector)`: the sum of all float or histogram samples in the specified interval (see details below).
* `count_over_time(range-vector)`: the count of all values in the specified interval. * `count_over_time(range-vector)`: the count of all samples in the specified interval.
* `quantile_over_time(scalar, range-vector)`: the φ-quantile (0 ≤ φ ≤ 1) of the values in the specified interval. * `quantile_over_time(scalar, range-vector)`: the φ-quantile (0 ≤ φ ≤ 1) of all float samples in the specified interval.
* `stddev_over_time(range-vector)`: the population standard deviation of the values in the specified interval. * `stddev_over_time(range-vector)`: the population standard deviation of all float samples in the specified interval.
* `stdvar_over_time(range-vector)`: the population standard variance of the values in the specified interval. * `stdvar_over_time(range-vector)`: the population standard variance of all float samples in the specified interval.
* `last_over_time(range-vector)`: the most recent point value in the specified interval. * `last_over_time(range-vector)`: the most recent sample in the specified interval.
* `present_over_time(range-vector)`: the value 1 for any series in the specified interval. * `present_over_time(range-vector)`: the value 1 for any series in the specified interval.
If the [feature flag](../feature_flags.md#experimental-promql-functions) If the [feature flag](../feature_flags.md#experimental-promql-functions)
`--enable-feature=promql-experimental-functions` is set, the following `--enable-feature=promql-experimental-functions` is set, the following
additional functions are available: additional functions are available:
* `mad_over_time(range-vector)`: the median absolute deviation of all points in the specified interval. * `mad_over_time(range-vector)`: the median absolute deviation of all float
samples in the specified interval.
Note that all values in the specified interval have the same weight in the Note that all values in the specified interval have the same weight in the
aggregation even if the values are not equally spaced throughout the interval. aggregation even if the values are not equally spaced throughout the interval.
`avg_over_time`, `sum_over_time`, `count_over_time`, `last_over_time`, and These functions act on histograms in the following way:
`present_over_time` handle native histograms as expected. All other functions
ignore histogram samples. - `count_over_time`, `last_over_time`, and `present_over_time()` act on float
and histogram samples in the same way.
- `avg_over_time()` and `sum_over_time()` act on histogram samples in a way
that corresponds to the respective aggregation operators. If a series
contains a mix of float samples and histogram samples within the range, the
corresponding result is removed entirely from the output vector. Such a
removal is flagged by a warn-level annotation.
- All other functions ignore histogram samples in the following way: Input
ranges containing only histogram samples are silently removed from the
output. For ranges with a mix of histogram and float samples, only the float
samples are processed and the omission of the histogram samples is flagged by
an info-level annotation.
## Trigonometric Functions ## Trigonometric Functions
The trigonometric functions work in radians: The trigonometric functions work in radians. They ignore histogram samples in
the input vector.
* `acos(v instant-vector)`: calculates the arccosine of all elements in `v` ([special cases](https://pkg.go.dev/math#Acos)). * `acos(v instant-vector)`: calculates the arccosine of all float samples in `v` ([special cases](https://pkg.go.dev/math#Acos)).
* `acosh(v instant-vector)`: calculates the inverse hyperbolic cosine of all elements in `v` ([special cases](https://pkg.go.dev/math#Acosh)). * `acosh(v instant-vector)`: calculates the inverse hyperbolic cosine of all float samples in `v` ([special cases](https://pkg.go.dev/math#Acosh)).
* `asin(v instant-vector)`: calculates the arcsine of all elements in `v` ([special cases](https://pkg.go.dev/math#Asin)). * `asin(v instant-vector)`: calculates the arcsine of all float samples in `v` ([special cases](https://pkg.go.dev/math#Asin)).
* `asinh(v instant-vector)`: calculates the inverse hyperbolic sine of all elements in `v` ([special cases](https://pkg.go.dev/math#Asinh)). * `asinh(v instant-vector)`: calculates the inverse hyperbolic sine of all float samples in `v` ([special cases](https://pkg.go.dev/math#Asinh)).
* `atan(v instant-vector)`: calculates the arctangent of all elements in `v` ([special cases](https://pkg.go.dev/math#Atan)). * `atan(v instant-vector)`: calculates the arctangent of all float samples in `v` ([special cases](https://pkg.go.dev/math#Atan)).
* `atanh(v instant-vector)`: calculates the inverse hyperbolic tangent of all elements in `v` ([special cases](https://pkg.go.dev/math#Atanh)). * `atanh(v instant-vector)`: calculates the inverse hyperbolic tangent of all float samples in `v` ([special cases](https://pkg.go.dev/math#Atanh)).
* `cos(v instant-vector)`: calculates the cosine of all elements in `v` ([special cases](https://pkg.go.dev/math#Cos)). * `cos(v instant-vector)`: calculates the cosine of all float samples in `v` ([special cases](https://pkg.go.dev/math#Cos)).
* `cosh(v instant-vector)`: calculates the hyperbolic cosine of all elements in `v` ([special cases](https://pkg.go.dev/math#Cosh)). * `cosh(v instant-vector)`: calculates the hyperbolic cosine of all float samples in `v` ([special cases](https://pkg.go.dev/math#Cosh)).
* `sin(v instant-vector)`: calculates the sine of all elements in `v` ([special cases](https://pkg.go.dev/math#Sin)). * `sin(v instant-vector)`: calculates the sine of all float samples in `v` ([special cases](https://pkg.go.dev/math#Sin)).
* `sinh(v instant-vector)`: calculates the hyperbolic sine of all elements in `v` ([special cases](https://pkg.go.dev/math#Sinh)). * `sinh(v instant-vector)`: calculates the hyperbolic sine of all float samples in `v` ([special cases](https://pkg.go.dev/math#Sinh)).
* `tan(v instant-vector)`: calculates the tangent of all elements in `v` ([special cases](https://pkg.go.dev/math#Tan)). * `tan(v instant-vector)`: calculates the tangent of all float samples in `v` ([special cases](https://pkg.go.dev/math#Tan)).
* `tanh(v instant-vector)`: calculates the hyperbolic tangent of all elements in `v` ([special cases](https://pkg.go.dev/math#Tanh)). * `tanh(v instant-vector)`: calculates the hyperbolic tangent of all float samples in `v` ([special cases](https://pkg.go.dev/math#Tanh)).
The following are useful for converting between degrees and radians: The following are useful for converting between degrees and radians:
* `deg(v instant-vector)`: converts radians to degrees for all elements in `v`. * `deg(v instant-vector)`: converts radians to degrees for all float samples in `v`.
* `pi()`: returns pi. * `pi()`: returns pi.
* `rad(v instant-vector)`: converts degrees to radians for all elements in `v`. * `rad(v instant-vector)`: converts degrees to radians for all float samples in `v`.

216
docs/querying/operators.md
View file

@ -23,22 +23,51 @@ The following binary arithmetic operators exist in Prometheus:
* `^` (power/exponentiation) * `^` (power/exponentiation)
Binary arithmetic operators are defined between scalar/scalar, vector/scalar, Binary arithmetic operators are defined between scalar/scalar, vector/scalar,
and vector/vector value pairs. and vector/vector value pairs. They follow the usual [IEEE 754 floating point
arithmetic](https://en.wikipedia.org/wiki/IEEE_754), including the handling of
special values like `NaN`, `+Inf`, and `-Inf`.
**Between two scalars**, the behavior is obvious: they evaluate to another **Between two scalars**, the behavior is obvious: they evaluate to another
scalar that is the result of the operator applied to both scalar operands. scalar that is the result of the operator applied to both scalar operands.
**Between an instant vector and a scalar**, the operator is applied to the **Between an instant vector and a scalar**, the operator is applied to the
value of every data sample in the vector. E.g. if a time series instant vector value of every data sample in the vector. If the data sample is a float, the
is multiplied by 2, the result is another vector in which every sample value of operation performed on the data sample is again obvious, e.g. if an instant
the original vector is multiplied by 2. The metric name is dropped. vector of float samples is multiplied by 2, the result is another vector of
float samples in which every sample value of the original vector is multiplied
by 2. For vector elements that are histogram samples, the behavior is the
following: For `*`, all bucket populations and the count and the sum of
observations are multiplied by the scalar. For `/`, the histogram sample has to
be on the left hand side (LHS), followed by the scalar on the right hand side
(RHS). All bucket populations and the count and the sum of observations are
then divided by the scalar. A division by zero results in a histogram with no
regular buckets and the zero bucket population and the count and sum of
observations all set to +Inf, -Inf, or NaN, depending on their values in the
input histogram (positive, negative, or zero/NaN, respectively). For `/` with a
scalar on the LHS and a histogram sample on the RHS, and similarly for all
other arithmetic binary operators in any combination of a scalar and a
histogram sample, there is no result and the corresponding element is removed
from the resulting vector. Such a removal is flagged by an info-level
annotation.
**Between two instant vectors**, a binary arithmetic operator is applied to **Between two instant vectors**, a binary arithmetic operator is applied to
each entry in the left-hand side vector and its [matching element](#vector-matching) each entry in the LHS vector and its [matching element](#vector-matching) in
in the right-hand vector. The result is propagated into the result vector with the the RHS vector. The result is propagated into the result vector with the
grouping labels becoming the output label set. The metric name is dropped. Entries grouping labels becoming the output label set. Entries for which no matching
for which no matching entry in the right-hand vector can be found are not part of entry in the right-hand vector can be found are not part of the result. If two
the result. float samples are matched, the behavior is obvious. If a float sample is
matched with a histogram sample, the behavior follows the same logic as between
a scalar and a histogram sample (see above), i.e. `*` and `/` (the latter with
the histogram sample on the LHS) are valid operations, while all others lead to
the removal of the corresponding element from the resulting vector. If two
histogram samples are matched, only `+` and `-` are valid operations, each
adding or substracting all matching bucket populations and the count and the
sum of observations. All other operations result in the removal of the
corresponding element from the output vector, flagged by an info-level
annotation.
**In any arithmetic binary operation involving vectors**, the metric name is
dropped.
### Trigonometric binary operators ### Trigonometric binary operators
@ -46,9 +75,12 @@ The following trigonometric binary operators, which work in radians, exist in Pr
* `atan2` (based on https://pkg.go.dev/math#Atan2) * `atan2` (based on https://pkg.go.dev/math#Atan2)
Trigonometric operators allow trigonometric functions to be executed on two vectors using Trigonometric operators allow trigonometric functions to be executed on two
vector matching, which isn't available with normal functions. They act in the same manner vectors using vector matching, which isn't available with normal functions.
as arithmetic operators. They act in the same manner as arithmetic operators. They only operate on float
samples. Operations involving histogram samples result in the removal of the
corresponding vector elements from the output vector, flagged by an
info-level annotation.
### Comparison binary operators ### Comparison binary operators
@ -72,20 +104,28 @@ operators result in another scalar that is either `0` (`false`) or `1`
**Between an instant vector and a scalar**, these operators are applied to the **Between an instant vector and a scalar**, these operators are applied to the
value of every data sample in the vector, and vector elements between which the value of every data sample in the vector, and vector elements between which the
comparison result is `false` get dropped from the result vector. If the `bool` comparison result is `false` get dropped from the result vector. These
modifier is provided, vector elements that would be dropped instead have the value operation only work with float samples in the vector. For histogram samples,
`0` and vector elements that would be kept have the value `1`. The metric name the corresponding element is removed from the result vector, flagged by an
is dropped if the `bool` modifier is provided. info-level annotation.
**Between two instant vectors**, these operators behave as a filter by default, **Between two instant vectors**, these operators behave as a filter by default,
applied to matching entries. Vector elements for which the expression is not applied to matching entries. Vector elements for which the expression is not
true or which do not find a match on the other side of the expression get true or which do not find a match on the other side of the expression get
dropped from the result, while the others are propagated into a result vector dropped from the result, while the others are propagated into a result vector
with the grouping labels becoming the output label set. with the grouping labels becoming the output label set. Matches between two
If the `bool` modifier is provided, vector elements that would have been float samples work as usual, while matches between a float sample and a
dropped instead have the value `0` and vector elements that would be kept have histogram sample are invalid. The corresponding element is removed from the
the value `1`, with the grouping labels again becoming the output label set. result vector, flagged by an info-level annotation. Between two histogram
The metric name is dropped if the `bool` modifier is provided. samples, `==` and `!=` work as expected, but all other comparison binary
operations are again invalid.
**In any comparison binary operation involving vectors**, providing the `bool`
modifier changes the behavior in the following way: Vector elements that would
be dropped instead have the value `0` and vector elements that would be kept
have the value `1`. Additionally, the metric name is dropped. (Note that
invalid operations involving histogram samples still return no result rather
than the value `0`.)
### Logical/set binary operators ### Logical/set binary operators
@ -108,6 +148,9 @@ which do not have matching label sets in `vector1`.
`vector1` for which there are no elements in `vector2` with exactly matching `vector1` for which there are no elements in `vector2` with exactly matching
label sets. All matching elements in both vectors are dropped. label sets. All matching elements in both vectors are dropped.
As these logical/set binary operators do not interact with the sample values,
they work in the same way for float samples and histogram samples.
## Vector matching ## Vector matching
Operations between vectors attempt to find a matching element in the right-hand side Operations between vectors attempt to find a matching element in the right-hand side
@ -219,19 +262,20 @@ used to aggregate the elements of a single instant vector, resulting in a new
vector of fewer elements with aggregated values: vector of fewer elements with aggregated values:
* `sum` (calculate sum over dimensions) * `sum` (calculate sum over dimensions)
* `avg` (calculate the arithmetic average over dimensions)
* `min` (select minimum over dimensions) * `min` (select minimum over dimensions)
* `max` (select maximum over dimensions) * `max` (select maximum over dimensions)
* `avg` (calculate the average over dimensions) * `bottomk` (smallest _k_ elements by sample value)
* `topk` (largest _k_ elements by sample value)
* `limitk` (sample _k_ elements, **experimental**, must be enabled with `--enable-feature=promql-experimental-functions`)
* `limit_ratio` (sample a pseudo-randem ratio _r_ of elements, **experimental**, must be enabled with `--enable-feature=promql-experimental-functions`)
* `group` (all values in the resulting vector are 1) * `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` (count number of elements in the vector)
* `count_values` (count number of elements with the same value) * `count_values` (count number of elements with the same value)
* `bottomk` (smallest k elements by sample value)
* `topk` (largest k elements by sample value) * `stddev` (calculate population standard deviation over dimensions)
* `stdvar` (calculate population standard variance over dimensions)
* `quantile` (calculate φ-quantile (0 ≤ φ ≤ 1) over dimensions) * `quantile` (calculate φ-quantile (0 ≤ φ ≤ 1) over dimensions)
* `limitk` (sample n elements)
* `limit_ratio` (sample elements with approximately 𝑟 ratio if `𝑟 > 0`, and the complement of such samples if `𝑟 = -(1.0 - 𝑟)`)
These operators can either be used to aggregate over **all** label dimensions These operators can either be used to aggregate over **all** label dimensions
or preserve distinct dimensions by including a `without` or `by` clause. These or preserve distinct dimensions by including a `without` or `by` clause. These
@ -251,29 +295,67 @@ all other labels are preserved in the output. `by` does the opposite and drops
labels that are not listed in the `by` clause, even if their label values are labels that are not listed in the `by` clause, even if their label values are
identical between all elements of the vector. identical between all elements of the vector.
`parameter` is only required for `count_values`, `quantile`, `topk`, `parameter` is only required for `topk`, `bottomk`, `limitk`, `limit_ratio`,
`bottomk`, `limitk` and `limit_ratio`. `quantile`, and `count_values`. It is used as the value for _k_, _r_, φ, or the
name of the additional label, respectively.
### Detailed explanations
`sum` sums up sample values in the same way as the `+` binary operator does
between two values. Similarly, `avg` divides the sum by the number of
aggregated samples in the same way as the `/` binary operator. Therefore, all
sample values aggregation into a single resulting vector element must either be
float samples or histogram samples. An aggregation of a mix of both is invalid,
resulting in the removeal of the corresponding vector element from the output
vector, flagged by a warn-level annotation.
`min` and `max` only operate on float samples, following IEEE 754 floating
point arithmetic, which in particular implies that `NaN` is only ever
considered a minimum or maximum if all aggregated values are `NaN`. Histogram
samples in the input vector are ignored, flagged by an info-level annotation.
`topk` and `bottomk` are different from other aggregators in that a subset of
the input samples, including the original labels, are returned in the result
vector. `by` and `without` are only used to bucket the input vector. Similar to
`min` and `max`, they only operate on float samples, considering `NaN` values
to be farthest from the top or bottom, respectively. Histogram samples in the
input vector are ignored, flagged by an info-level annotation.
`limitk` and `limit_ratio` also return a subset of the input samples, including
the original labels in the result vector. The subset is selected in a
deterministic pseudo-random way. `limitk` picks _k_ samples, while
`limit_ratio` picks a ratio _r_ of samples (each determined by `parameter`).
This happens independent of the sample type. Therefore, it works for both float
samples and histogram samples. _r_ can be between +1 and -1. The absolute value
of _r_ is used as the selection ratio, but the selection order is inverted for
a negative _r_, which can be used to select complements. For example,
`limit_ratio(0.1, ...)` returns a deterministic set of approximatiely 10% of
the input samples, while `limit_ratio(-0.9, ...)` returns precisely the
remaining approximately 90% of the input samples not returned by
`limit_ratio(0.1, ...)`.
`group` and `count` do not do not interact with the sample values,
they work in the same way for float samples and histogram samples.
`count_values` outputs one time series per unique sample value. Each series has `count_values` outputs one time series per unique sample value. Each series has
an additional label. The name of that label is given by the aggregation an additional label. The name of that label is given by the aggregation
parameter, and the label value is the unique sample value. The value of each parameter, and the label value is the unique sample value. The value of each
time series is the number of times that sample value was present. time series is the number of times that sample value was present.
`count_values` works with both float samples and histogram samples. For the
latter, a compact string representation of the histogram sample value is used
as the label value.
`topk` and `bottomk` are different from other aggregators in that a subset of `stddev` and `stdvar` only work with float samples, following IEEE 754 floating
the input samples, including the original labels, are returned in the result point arithmetic. Histogram samples in the input vector are ignored, flagged by
vector. `by` and `without` are only used to bucket the input vector. an info-level annotation.
`limitk` and `limit_ratio` also return a subset of the input samples,
including the original labels in the result vector, these are experimental
operators that must be enabled with `--enable-feature=promql-experimental-functions`.
`quantile` calculates the φ-quantile, the value that ranks at number φ*N among `quantile` calculates the φ-quantile, the value that ranks at number φ*N among
the N metric values of the dimensions aggregated over. φ is provided as the the N metric values of the dimensions aggregated over. φ is provided as the
aggregation parameter. For example, `quantile(0.5, ...)` calculates the median, aggregation parameter. For example, `quantile(0.5, ...)` calculates the median,
`quantile(0.95, ...)` the 95th percentile. For φ = `NaN`, `NaN` is returned. For φ < 0, `-Inf` is returned. For φ > 1, `+Inf` is returned. `quantile(0.95, ...)` the 95th percentile. For φ = `NaN`, `NaN` is returned.
For φ < 0, `-Inf` is returned. For φ > 1, `+Inf` is returned.
### Examples
Example:
If the metric `http_requests_total` had time series that fan out by If the metric `http_requests_total` had time series that fan out by
`application`, `instance`, and `group` labels, we could calculate the total `application`, `instance`, and `group` labels, we could calculate the total
@ -303,28 +385,6 @@ could write:
limitk(10, http_requests_total) limitk(10, http_requests_total)
To deterministically sample approximately 10% of timeseries we could write:
limit_ratio(0.1, http_requests_total)
Given that `limit_ratio()` implements a deterministic sampling algorithm (based
on labels' hash), you can get the _complement_ of the above samples, i.e.
approximately 90%, but precisely those not returned by `limit_ratio(0.1, ...)`
with:
limit_ratio(-0.9, http_requests_total)
You can also use this feature to e.g. verify that `avg()` is a representative
aggregation for your samples' values, by checking that the difference between
averaging two samples' subsets is "small" when compared to the standard
deviation.
abs(
avg(limit_ratio(0.5, http_requests_total))
-
avg(limit_ratio(-0.5, http_requests_total))
) <= bool stddev(http_requests_total)
## Binary operator precedence ## Binary operator precedence
The following list shows the precedence of binary operators in Prometheus, from The following list shows the precedence of binary operators in Prometheus, from
@ -340,35 +400,3 @@ highest to lowest.
Operators on the same precedence level are left-associative. For example, Operators on the same precedence level are left-associative. For example,
`2 * 3 % 2` is equivalent to `(2 * 3) % 2`. However `^` is right associative, `2 * 3 % 2` is equivalent to `(2 * 3) % 2`. However `^` is right associative,
so `2 ^ 3 ^ 2` is equivalent to `2 ^ (3 ^ 2)`. so `2 ^ 3 ^ 2` is equivalent to `2 ^ (3 ^ 2)`.
## Operators for native histograms
Native histograms are an experimental feature. Ingesting native histograms has
to be enabled via a [feature flag](../../feature_flags.md#native-histograms). Once
native histograms have been ingested, they can be queried (even after the
feature flag has been disabled again). However, the operator support for native
histograms is still very limited.
Logical/set binary operators work as expected even if histogram samples are
involved. They only check for the existence of a vector element and don't
change their behavior depending on the sample type of an element (float or
histogram). The `count` aggregation operator works similarly.
The binary `+` and `-` operators between two native histograms and the `sum`
and `avg` aggregation operators to aggregate native histograms are fully
supported. Even if the histograms involved have different bucket layouts, the
buckets are automatically converted appropriately so that the operation can be
performed. (With the currently supported bucket schemas, that's always
possible.) If either operator has to aggregate a mix of histogram samples and
float samples, the corresponding vector element is removed from the output
vector entirely.
The binary `*` operator works between a native histogram and a float in any
order, while the binary `/` operator can be used between a native histogram
and a float in that exact order.
All other operators (and unmentioned cases for the above operators) do not
behave in a meaningful way. They either treat the histogram sample as if it
were a float sample of value 0, or (in case of arithmetic operations between a
scalar and a vector) they leave the histogram sample unchanged. This behavior
will change to a meaningful one before native histograms are a stable feature.