写点什么

Prometheus 官方文档【查询篇 - 运算符】

用户头像
卓丁
关注
发布于: 2021 年 01 月 10 日
Prometheus官方文档【查询篇-运算符】

Binary operators

运算符

Prometheus's query language supports basic logical and arithmetic operators. For operations between two instant vectors, the matching behavior can be modified.

Prometheus 的查询语言支持基本逻辑/算术运算符。

对两个瞬时向量之间的运算,可以修改匹配行为


Arithmetic binary operators

算术运算符

The following binary arithmetic operators exist in Prometheus:

Prometheus 包括以下算术运算符:

  • + (addition) 加

  • - (subtraction) 减

  • * (multiplication) 乘

  • / (division) 除

  • % (modulo) 模

  • ^ (power/exponentiation) 幂

Binary arithmetic operators are defined between scalar/scalar, vector/scalar, and vector/vector value pairs.

算术运算符适用于 标量和标量,向量和标量,向量和向量对之间。

Between two scalars, the behavior is obvious: 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. E.g. if a time series instant vector is multiplied by 2, the result is another vector in which every sample value of the original vector is multiplied by 2. The metric name is dropped.

一个瞬时向量和一个标量之间,将运算符应用于向量中每个数据样本的值。例如。 如果将时间序列瞬时向量乘以 2,则结果是另一个向量,其中原始向量的每个样本值都乘以 2。度量名称被删除。


Between two instant vectors, a binary arithmetic operator is applied to each entry in the left-hand side vector and its matching element in the right-hand vector. The result is propagated into the result vector with the grouping labels becoming the output label set. The metric name is dropped. Entries for which no matching entry in the right-hand vector can be found are not part of the result.

两个瞬时向量之间, 将二进制算术运算符应用于左侧向量中的每个条目及其右侧向量中的匹配元素。

结果被传播到结果向量中,分组标签成为输出标签集。

指标名称将被删除。在右侧向量中找不到匹配项的项不是结果的一部分。

Comparison binary operators

比较运算符

The following binary comparison operators exist in Prometheus:

Prometheus 包括以下比较运算符:

  • == (equal) 等于

  • != (not-equal) 不等于

  • > (greater-than) 大于

  • < (less-than) 小于

  • >= (greater-or-equal) 大于等于

  • <= (less-or-equal) 小于等于

Comparison operators are defined between scalar/scalar, vector/scalar, and vector/vector value pairs. By default they filter. Their behavior can be modified by providing bool after the operator, which will return 0 or 1 for the value rather than filtering.

比较运算符适用于标量/标量、向量/标量和向量/向量值对之间,

Between two scalars, the bool modifier must be provided and these operators result in another scalar that is either 0 (false) or 1 (true), depending on the comparison result.

两个标量之间, 默认情况下,这些比较运算符的查询行为是进行结果过滤。

但我们可以通过在操作符后面提供 bool 来修改它们的行为,使该操作符返回值 0 或值 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. If the bool modifier is provided, vector elements that would be dropped instead have the value 0 and vector elements that would be kept have the value 1. The metric name is dropped if the bool modifier is provided.

一个瞬时向量和一个标量之间 ,将这些运算符应用于向量中每个数据样本的值,并从结果向量中删除比较结果为 false 的向量元素。如果提供了 bool 修饰符,则将被删除的向量元素的值为 0,而将被保留的向量元素的值为 1。如果提供了 bool 修饰符,则会删除指标名称。

Between two instant vectors, these operators behave as a filter by default, 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. If the bool modifier is provided, vector elements that would have been dropped instead have the value 0 and vector elements that would be kept have the value 1, with the grouping labels again becoming the output label set. The metric name is dropped if the bool modifier is provided.

两个瞬时向量之间 ,默认情况下,这些运算符的行为类似于过滤器,应用于匹配的条目。

表达式为非真或在表达式的另一侧未找到匹配项的向量元素将从结果中删除,

而其他元素将传播到结果向量中,分组标签将成为输出标签集。

如果提供了 bool 修饰符,则将被删除的向量元素的值为 0,而将被保留的向量元素的值为 1,

分组标签将再次成为输出标签集。如果提供了 bool 修饰符,则会删除指标名称。

Logical/set binary operators

逻辑/集合 运算符

These logical/set binary operators are only defined between instant vectors:

逻辑/集合运算符仅可被适用于两个瞬时向量之间:

  • and (intersection) 交

  • or (union) 并

  • unless (complement) 补

vector1 and vector2 results in a vector consisting of the elements of vector1 for which there are elements in vector2 with exactly matching label sets. Other elements are dropped. The metric name and values are carried over from the left-hand side vector.

vector1 or vector2 results in a vector that contains all original elements (label sets + values) of vector1 and additionally all elements of vector2 which do not have matching label sets in vector1.

vector1 unless vector2 results in a vector consisting of the elements of vector1 for which there are no elements in vector2 with exactly matching label sets. All matching elements in both vectors are dropped.

vector1vector2生成一个向量,该向量由vector1的元素组成,其中vector2中的元素具有完全匹配的标签集。其他元素被删除。度量名称和值从左侧向量继承。

vector1vector2生成的向量包含vector1的所有原始元素(标签集+值)以及vector2中在vector1中没有匹配标签集的所有元素。

除非vector2产生一个由vector1元素组成的向量,否则vector2中没有元素具有完全匹配的标签集。 两个向量中的所有匹配元素都将被删除。


Vector matching

向量匹配

Operations between vectors attempt to find a matching element in the right-hand side vector for each entry in the left-hand side. There are two basic types of matching behavior: One-to-one and many-to-one/one-to-many.

向量之间的运算试图为左侧的每个条目在右侧向量中找到匹配的元素。匹配行为有两种基本类型:一对一和多对一/一对多。

One-to-one vector matches

一对一向量匹配

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 ignoring keyword allows ignoring certain labels when matching, while the on keyword allows reducing the set of considered labels to a provided list:

从操作的每一侧查找一对唯一的条目。 在默认情况下,该操作将遵循vector1 <operator> vector2格式。 如果两个条目具有完全相同的一组标签和相应的值,则它们匹配。

忽略ignoring允许在匹配时忽略某些标签,而on关键字允许将考虑的标签集减少到提供的列表中:

<vector expr> <bin-op> ignoring(<label list>) <vector expr><vector expr> <bin-op> on(<label list>) <vector expr>
复制代码

Example input:

例如:

method_code:http_errors:rate5m{method="get", code="500"}  24method_code:http_errors:rate5m{method="get", code="404"}  30method_code:http_errors:rate5m{method="put", code="501"}  3method_code:http_errors:rate5m{method="post", code="500"} 6method_code:http_errors:rate5m{method="post", code="404"} 21
method:http_requests:rate5m{method="get"} 600method:http_requests:rate5m{method="del"} 34method:http_requests:rate5m{method="post"} 120
复制代码

Example query:

查询举例:

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 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:

这将返回一个结果向量,其中包含在过去 5 分钟内测量的(http)所有请求方法的状态码为 500 的 HTTP 请求部分。没有 ignoring(code) ,就不会有匹配,因为度量不共享同一组标签。方法为putdel的条目不匹配,不会显示在结果中:

{method="get"}  0.04            //  24 / 600{method="post"} 0.05            //   6 / 120
复制代码

Many-to-one and one-to-many vector matches

多对一 和 一对多 向量匹配

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.

多对一一对多匹配指的是“一”侧的每个向量元素可以与“多”侧的多个元素匹配的情况。必须使用group_leftgroup_right修饰符显式请求,其中 left/right 确定哪个向量具有更高的基数。


<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 "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 and arithmetic. Operations as andunless and or operations match with all possible entries in the right vector by default.

与组修饰符一起提供的标签列表包含“一”侧的其他标签,这些标签将包含在结果度量中。因为标签上的内容只能出现在其中一个列表中。结果向量的每个时间序列必须是唯一可识别的。

分组修饰符只能用于 comparison 和 arithmetic。运算为andunlessor 运算默认与右向量中所有可能的条目匹配。

Example query:

查询示例:

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. The elements from the right side are now matched with multiple elements with the same method label on the left:

在这种情况下,左向量每个methed标签值包含多个条目。因此,我们使用group_left来表示这一点。现在,右侧的元素与左侧具有相同方法标签的多个元素匹配:

{method="get", code="500"}  0.04            //  24 / 600{method="get", code="404"}  0.05            //  30 / 600{method="post", code="500"} 0.05            //   6 / 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 ignoring(<labels>) provides the desired outcome.

多对一和一对多匹配是应该仔细考虑的高级用例。通常,正确使用 ignoring(<labels>) 可以提供所需的结果。

Aggregation operators

聚合运算符

Prometheus supports the following built-in aggregation operators that can be used to aggregate the elements of a single instant vector, resulting in a new vector of fewer elements with aggregated values:

Prometheus 支持以下内置聚合运算符,可用于聚合单个瞬时向量的元素,从而生成具有聚合值的较少元素的新向量:

  • sum (calculate sum over dimensions) 计算和

  • min (select minimum over dimensions) 选择最小的

  • max (select maximum over dimensions) 选择最大的

  • avg (calculate the average over dimensions) 求平均值

  • group (all values in the resulting vector are 1)

  • stddev (calculate population standard deviation over dimensions)

  • stdvar (calculate population standard variance over dimensions)

  • count (count number of elements in the vector)

  • count_values (count number of elements with the same value)

  • bottomk (smallest k elements by sample value)

  • topk (largest k elements by sample value)

  • quantile (calculate φ-quantile (0 ≤ φ ≤ 1) over 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 clauses may be used before or after the expression.

<aggr-op> [without|by (<label list>)] ([parameter,] <vector expression>)
复制代码

or

<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]
复制代码

label list is a list of unquoted labels that may include a trailing comma, i.e. both (label1, label2) and (label1, label2,) are valid syntax.

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.

parameter is only required for count_valuesquantiletopk and bottomk.

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 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.

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.

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 aggregation parameter. For example, quantile(0.5, ...) calculates the median, quantile(0.95, ...) the 95th percentile.

Example:

If the metric http_requests_total had time series that fan out by applicationinstance, and group labels, we could calculate the total number of seen HTTP requests per application and group over all instances via:

sum without (instance) (http_requests_total)
复制代码

Which is equivalent to:

 sum by (application, group) (http_requests_total)
复制代码

If we are just interested in the total of HTTP requests we have seen in all applications, we could simply write:

sum(http_requests_total)
复制代码

To count the number of binaries running each build version we could write:

count_values("version", build_version)
复制代码

To get the 5 largest HTTP requests counts across all instances we could write:

topk(5, http_requests_total)
复制代码

Binary operator precedence

运算符优先级

The following list shows the precedence of binary operators in Prometheus, from highest to lowest.

  1. ^

  2. */%

  3. +-

  4. ==!=<=<>=>

  5. andunless

  6. or

Operators on the same precedence level are left-associative. For example, 2 * 3 % 2 is equivalent to (2 * 3) % 2. However ^ is right associative, so 2 ^ 3 ^ 2 is equivalent to 2 ^ (3 ^ 2).

 This documentation is open-source. Please help improve it by filing issues or pull requests.

本文档是开源的,任何人都可以通过提出问题或 pull requests 来改进该文档。


发布于: 2021 年 01 月 10 日阅读数: 31
用户头像

卓丁

关注

鸟过无痕 2017.12.10 加入

泰戈尔:虽然天空没有留下我的痕迹,但我已飞过。

评论

发布
暂无评论
Prometheus官方文档【查询篇-运算符】