From 1e794f7ef9b7a6915951834297b456ac123ebec1 Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Wed, 11 Jun 2025 13:21:10 +1000 Subject: [PATCH 1/9] Break large paragraphs into smaller pieces Signed-off-by: Charles Korn --- docs/querying/operators.md | 92 ++++++++++++++++++++++---------------- 1 file changed, 53 insertions(+), 39 deletions(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index 5e4f127b86..2d79c638c0 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -29,37 +29,46 @@ special values like `NaN`, `+Inf`, and `-Inf`. 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 -value of every data sample in the vector. If the data sample is a float, the -operation performed on the data sample is again obvious, e.g. if an instant -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. +value of every data sample in the vector. + +If the data sample is a float, the operation performed on the data sample is +again obvious, e.g. if an instant 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 each entry in the LHS vector and its [matching element](#vector-matching) in the RHS vector. The result is propagated into the result vector with the grouping labels becoming the output label set. Entries for which no matching -entry in the right-hand vector can be found are not part of the result. If two -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 +entry in the right-hand vector can be found are not part of the result. + +If two 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 subtracting 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. @@ -102,8 +111,8 @@ 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 value of every data sample in the vector, and vector elements between which the -comparison result is `false` get dropped from the result vector. These -operation only work with float samples in the vector. For histogram samples, +comparison result is false get dropped from the result vector. These +operations only work with float samples in the vector. For histogram samples, the corresponding element is removed from the result vector, flagged by an info-level annotation. @@ -111,19 +120,24 @@ info-level annotation. 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 dropped from the result, while the others are propagated into a result vector -with the grouping labels becoming the output label set. Matches between two -float samples work as usual, while matches between a float sample and a -histogram sample are invalid. The corresponding element is removed from the -result vector, flagged by an info-level annotation. Between two histogram -samples, `==` and `!=` work as expected, but all other comparison binary -operations are again invalid. +with the grouping labels becoming the output label set. + +Matches between two float samples work as usual. + +Matches between a float sample and a histogram sample are invalid, and the +corresponding element is removed from the result vector, flagged by an info-level +annotation. + +Between two histogram 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`.) +modifier changes the behavior in the following ways: +* Vector elements that would be dropped instead have the value `0` and + vector elements that would be kept have the value `1`. (Note that + invalid operations involving histogram samples still return no result rather + than the value `0`.) +* The metric name is dropped. ### Logical/set binary operators From 40bed6281e469baed4cd3a4fccc8dd78949da6bb Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Wed, 11 Jun 2025 13:30:16 +1000 Subject: [PATCH 2/9] Clarify behaviour of metric names with `bool` modifier Based on discussion in https://github.com/prometheus/prometheus/issues/15471 Signed-off-by: Charles Korn --- docs/querying/operators.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index 2d79c638c0..ed2d4d90a8 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -139,6 +139,12 @@ modifier changes the behavior in the following ways: than the value `0`.) * The metric name is dropped. +If the `bool` modifier is not provided, then the metric name from the left side +is retained, with some exceptions: +* If `on` is used, then the metric name is dropped. +* If `group_right` is used, then the metric name from the right side is retained, + to avoid collisions. + ### Logical/set binary operators These logical/set binary operators are only defined between instant vectors: From 0c6ef1b23ccb07413c39c1836eb1b8f2e4af3a1b Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Wed, 11 Jun 2025 13:35:07 +1000 Subject: [PATCH 3/9] Clarify behaviour of `bool` modifier Signed-off-by: Charles Korn --- docs/querying/operators.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index ed2d4d90a8..9054b97a56 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -133,10 +133,11 @@ comparison binary operations are again invalid. **In any comparison binary operation involving vectors**, providing the `bool` modifier changes the behavior in the following ways: -* Vector elements that would be dropped instead have the value `0` and - vector elements that would be kept have the value `1`. (Note that - invalid operations involving histogram samples still return no result rather - than the value `0`.) +* Vector elements which find a match on the other side of the expression but for + which the expression is false instead have the value `0` and vector elements + that do find a match and for which the expression is true have the value `1`. + (Note that elements with no match or invalid operations involving histogram + samples still return no result rather than the value `0`.) * The metric name is dropped. If the `bool` modifier is not provided, then the metric name from the left side From 5926159f2ac35aeeacc1accfd0a3725a55f4ce35 Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Wed, 11 Jun 2025 13:36:55 +1000 Subject: [PATCH 4/9] Clarify expected behaviour of `on(__name__)` See https://github.com/prometheus/prometheus/issues/16631 Signed-off-by: Charles Korn --- docs/querying/operators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index 9054b97a56..6367f6e73c 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -74,7 +74,7 @@ corresponding element from the output vector, flagged by an info-level annotation. **In any arithmetic binary operation involving vectors**, the metric name is -dropped. +dropped unless it is explicitly mentioned in `on`. ### Trigonometric binary operators From 9c6916f4f9a5d0455ab8457122626cee3dda14f7 Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Tue, 1 Jul 2025 20:06:15 +1000 Subject: [PATCH 5/9] Address PR feedback: add blank lines before lists Signed-off-by: Charles Korn --- docs/querying/operators.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index 6367f6e73c..65ba86fb60 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -38,6 +38,7 @@ 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. @@ -132,7 +133,8 @@ Between two histogram 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 ways: +modifier changes the behavior in the following ways: + * Vector elements which find a match on the other side of the expression but for which the expression is false instead have the value `0` and vector elements that do find a match and for which the expression is true have the value `1`. @@ -142,6 +144,7 @@ modifier changes the behavior in the following ways: If the `bool` modifier is not provided, then the metric name from the left side is retained, with some exceptions: + * If `on` is used, then the metric name is dropped. * If `group_right` is used, then the metric name from the right side is retained, to avoid collisions. From 70df21a68005a9651b73e2b1f079f883d582ddf5 Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Tue, 1 Jul 2025 20:07:07 +1000 Subject: [PATCH 6/9] Address PR feedback: format Inf and NaN as monospace Signed-off-by: Charles Korn --- docs/querying/operators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index 65ba86fb60..cf348d266e 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -46,8 +46,8 @@ following: 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). + 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 From 665eb3d6cb96db1bf7b44fb728824345cc354047 Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Tue, 1 Jul 2025 20:08:18 +1000 Subject: [PATCH 7/9] Address PR feedback: remove use of "obvious" Signed-off-by: Charles Korn --- docs/querying/operators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index cf348d266e..e35b17aab3 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -61,7 +61,7 @@ the RHS vector. The result is propagated into the result vector with the grouping labels becoming the output label set. Entries for which no matching entry in the right-hand vector can be found are not part of the result. -If two float samples are matched, the behavior is obvious. +If two float samples are matched, the arithmetic operator is applied to the two input values. 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 `/` From 1977452331caadddd95f481a2173699de554fb3a Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Tue, 1 Jul 2025 20:10:20 +1000 Subject: [PATCH 8/9] Address PR feedback: adjust docs to match current behaviour Signed-off-by: Charles Korn --- docs/querying/operators.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index e35b17aab3..d1c6a8b8cd 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -75,7 +75,8 @@ corresponding element from the output vector, flagged by an info-level annotation. **In any arithmetic binary operation involving vectors**, the metric name is -dropped unless it is explicitly mentioned in `on`. +dropped. This occurs even if `__name__` is explicitly mentioned in `on` +(see https://github.com/prometheus/prometheus/issues/16631 for further discussion). ### Trigonometric binary operators From d19a9ab673db31200fae03c001f03a6b58d28937 Mon Sep 17 00:00:00 2001 From: Charles Korn Date: Tue, 1 Jul 2025 20:13:46 +1000 Subject: [PATCH 9/9] Remove other instances of "obvious" Signed-off-by: Charles Korn --- docs/querying/operators.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/querying/operators.md b/docs/querying/operators.md index d1c6a8b8cd..f8bddc8bda 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -25,14 +25,14 @@ 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 straightforward: they evaluate to another 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 value of every data sample in the vector. -If the data sample is a float, the operation performed on the data sample is -again obvious, e.g. if an instant vector of float samples is multiplied by 2, +If the data sample is a float, the operation is performed between that float and the scalar. +For example, if an instant 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.