docs: clarify and expand binary operations documentation #16716
Conversation
Signed-off-by: Charles Korn <charles.korn@grafana.com>
Based on discussion in prometheus#15471 Signed-off-by: Charles Korn <charles.korn@grafana.com>
Signed-off-by: Charles Korn <charles.korn@grafana.com>
See prometheus#16631 Signed-off-by: Charles Korn <charles.korn@grafana.com>
| the original vector is multiplied by 2. | ||
|
|
||
| For vector elements that are histogram samples, the behavior is the | ||
| following: |
There was a problem hiding this comment.
We've had problems in the past with Markdown formatting (depending on MD preprocessing environment) not working when there is no empty line before a list. Let's add an empty line before the list just to be safe.
| 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 |
There was a problem hiding this comment.
| and the count and sum of observations all set to +Inf, -Inf, or NaN, depending | |
| and the count and sum of observations all set to `+Inf`, `-Inf`, or `NaN`, depending |
(we do this above for these special values as well)
| 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). |
There was a problem hiding this comment.
| on their values in the input histogram (positive, negative, or zero/NaN, respectively). | |
| on their values in the input histogram (positive, negative, or zero/`NaN`, respectively). |
| 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. |
There was a problem hiding this comment.
I would like to avoid too much use of the word "obvious" in documentation, especially for people who are already overwhelmed and don't feel that things are obvious (it's too subjective) :) How about something more like:
| If two float samples are matched, the behavior is obvious. | |
| If two float samples are matched, the result sample value is generated by applying the binary operator to the two input values in a straightforward way. |
| 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: |
There was a problem hiding this comment.
Same comment here about adding an empty line before the Markdown list.
| 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. | ||
| dropped unless it is explicitly mentioned in `on`. |
There was a problem hiding this comment.
This is still false, right? Since we decided to not change the current behavior of dropping the metric name even when it's mentioned in an on() clause, see #16631 (comment)
This PR clarifies the documentation for binary operations, based on the discussions in #15471 and #16631.
It also reformats some longer paragraphs into smaller pieces for easier reading.
I've made each change as a separate commit, and I'd suggest reviewing each separately.