Commit 54043b11 authored by Brian Brazil's avatar Brian Brazil

Add docs for ignoring and new group_* semantics.

parent b3a1fe1f
......@@ -102,17 +102,20 @@ matching behavior:
**One-to-one** finds a unique pair of entries from each side of the operation.
In the default case, that is an operation following the format `vector1 <operator> vector2`.
Two entries match if they have the exact same set of labels and corresponding values.
The `on` keyword allows reducing the set of considered labels to a provided list:
The `ignoring` keyword allows ignoring certain labels when matching, while the
`on` keyword allows reducing the set of considered labels to a provided list:
<vector expr> <bin-op> ignoring(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) <vector expr>
Example input:
method:http_errors:rate5m{source="internal", method="get", code="500"} 24
method:http_errors:rate5m{source="external", method="get", code="404"} 30
method:http_errors:rate5m{source="internal", method="put", code="501"} 3
method:http_errors:rate5m{source="internal", method="post", code="500"} 6
method:http_errors:rate5m{source="external", method="post", code="404"} 21
method_code:http_errors:rate5m{method="get", code="500"} 24
method_code:http_errors:rate5m{method="get", code="404"} 30
method_code:http_errors:rate5m{method="put", code="501"} 3
method_code:http_errors:rate5m{method="post", code="500"} 6
method_code:http_errors:rate5m{method="post", code="404"} 21
method:http_requests:rate5m{method="get"} 600
method:http_requests:rate5m{method="del"} 34
......@@ -120,35 +123,41 @@ Example input:
Example query:
method:http_errors:rate5m{code="500"} / on(method) method:http_requests:rate5m
method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m
This returns a result vector containing the fraction of HTTP requests with status code
of 500 for each method, as measured over the last 5 minutes. Without `on(method)` there
of 500 for each method, as measured over the last 5 minutes. Without `ignoring(code)` there
would have been no match as the metrics do not share the same set of labels.
The entries with methods `put` and `del` have no match and will not show up in the result:
{method="get"} 0.04 // 24 / 600
{method="post"} 0.1 // 12 / 120
**Many-to-one** and **one-to-many** matchings refer to the case where each vector element on
the "one"-side can match with multiple elements on the "many"-side. This has to
be explicitly requested using the `group_left` or `group_right` modifier, where
left/right determines which vector has the higher cardinality.
<vector expr> <bin-op> ignoring(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> ignoring(<label list>) group_right(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_right(<label list>) <vector expr>
The label list provided with the group modifier contains additional labels from the "many"-side
to be included in the result metrics. A label can only appear in one of the lists. Every time
series of the result vector must be uniquely identifiable by the labels from both lists combined.
The label list provided with the group modifier contains additional labels from
the "one"-side to be included in the result metrics. For `on` a label can only
appear in one of the lists. Every time series of the result vector must be
uniquely identifiable.
_Grouping modifiers can only be used for [comparison](#comparison-binary-operators)
and [arithmetic](#arithmetic-binary-operators) operations as `and` and `or` operations
match with all possible entries in the right vector by default._
_Grouping modifiers can only be used for
[comparison](#comparison-binary-operators) and
[arithmetic](#arithmetic-binary-operators). Operations as `and`, `unless` and
`or` operations match with all possible entries in the right vector by
default._
Example query:
method:http_errors:rate5m / on(method) group_left(code,source) method:http_requests:rate5m
method_code:http_errors:rate5m / ignoring(code) group_left method:http_requests:rate5m
In this case the left vector contains more than one entry per `method` label value. Thus,
we indicate this using `group_left`. To ensure that the result vector entries are unique, additional
......@@ -156,14 +165,13 @@ labels have to be provided. Either `code` or `source` satisfy this requirement,
can be added for a more detailed result. The elements from the right side
are now matched with multiple elements with the same `method` label on the left:
{source="internal", method="get", code="500"} 0.04 // 24 / 600
{source="external", method="get", code="404"} 0.05 // 30 / 600
{source="internal", method="post", code="500"} 0.1 // 12 / 120
{source="external", method="post", code="404"} 0.175 // 21 / 120
{method="get", code="500"} 0.04 // 24 / 600
{method="get", code="404"} 0.05 // 30 / 600
{method="post", code="500"} 0.1 // 12 / 120
{method="post", code="404"} 0.175 // 21 / 120
_Many-to-one and one-to-many matching are advanced use cases that should be carefully considered.
Often a proper use of `on(<labels>)` provides the desired outcome._
Often a proper use of `ignoring(<labels>)` provides the desired outcome._
## Aggregation operators
......@@ -187,7 +195,7 @@ or preserve distinct dimensions by including a `without` or `by` clause.
`without` removes the listed labels from the result vector, while all other
labels are preserved the output. `by` does the opposite and drops labels that
are not listed in the `by` clause, even if their label values are identical
between all elements of the vector. The `keep_common` clause allows to keep
between all elements of the vector. The `keep_common` clause allows keeping
those extra labels (labels that are identical between elements, but not in the
`by` clause).
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment