PromQL operator

PromQL operator

In addition to using convenient PromQL than queries and filters according to the time series, PromQL supports rich operator, the user can use these operators for a further sequence of events for secondary processing. These operators include: mathematical, logical operators, Boolean operators and the like.

computation

For example, we can get the current host memory space available through indicators node_memory_free_bytes_total, its sample unit is Bytes. That is if the client requires the use of MB as a unit in response to the data, it would only need to query sample values ​​of the time series of unit conversion can be carried out:

node_memory_free_bytes_total / (1024 * 1024)

node_memory_free_bytes_total表达式会查询出所有满足表达式条件的时间序列，在上一小节中我们称该表达式为瞬时向量表达式，而返回的结果成为瞬时向量。

When the mathematical operation between the instantaneous vector and scalar, mathematical operators in turn scope each sample value of the instantaneous vector to obtain a new set of time series.

And if it is instantaneous when performing mathematical operations between vector and vector transient, the process will be relatively complex. For example, if we want to get the total amount of disk IO host according node_disk_bytes_written and node_disk_bytes_read, you can use the following expression:

node_disk_bytes_written + node_disk_bytes_read

This expression is that how it works? Turn left and find calculates vector element matching (label exactly) the right of vector elements, if no match is found elements, then discarded. At the same time new time series will not include the name index. Examples of the expression returns the results as follows:

{device="sda",instance="localhost:9100",job="node_exporter"}=>1634967552@1518146427.807 + 864551424@1518146427.807
{device="sdb",instance="localhost:9100",job="node_exporter"}=>0@1518146427.807 + 1744384@1518146427.807

PromQL supports all mathematical operators are shown below:

• + (addition)
• - (Subtraction)
• * (multiplication)
• / (division)
• % (Remainder)
• ^ (Exponentiation)

Booleans filtered time series

, The user may be queried by the tag in the matching mode PromQL feature dimensions of time series. Boolean operations and supports the user in accordance with time-series samples of the time series filter.

For example, by mathematical operators we can easily calculate the memory usage of all the current host node:

(node_memory_bytes_total - node_memory_free_bytes_total) / node_memory_bytes_total

And when troubleshooting system administrator might want to know the current memory usage exceeds 95% of the host it? You can easily access to the results obtained by using Boolean operators:

(node_memory_bytes_total - node_memory_free_bytes_total) / node_memory_bytes_total > 0.95

Instantaneous vector and scalar Boolean operations, PromQL sequentially comparing the time series values ​​of all the samples in the vector, if the comparison is true is retained, otherwise discarded.

Instantaneous vector and the instantaneous vector directly Boolean operations, following the same default match mode: turn to find the appropriate action with the left vector element matching (label exactly) the right of vector elements, if no match is found element will be discarded.?.

Currently, Prometheus supports the following Boolean operators are as follows:

• == (equal)
• != (not equal)
• > (more than the)
• < (Less than)
• >= (greater or equal to)
• <= (Or less)

Bool use Boolean operators Modifiers change behavior

Boolean operators default behavior time series data is filtered. In other cases we may need is a real Boolean result. For example, this module only needs to know whether the amount of HTTP request> = 1000, 1000 if greater than or equal Returns 1 (true) else return 0 (false). Then you can use modifiers to change the default behavior bool Boolean operations. E.g:

http_requests_total > bool 1000

After use modifier bool Boolean operations does not filter the time series, but direct comparison result for each sample sequentially instantaneous scalar data in the vector 0 or 1. To form a new time series.

http_requests_total{code="200",handler="query",instance="localhost:9090",job="prometheus",method="get"}  1
http_requests_total{code="200",handler="query_range",instance="localhost:9090",job="prometheus",method="get"}  0

Also note that if you are using Boolean operations between two scalar, you must use the modifier bool

2 == BOOL  2 # 1 results

 

Use set operators

Using a transient expression vector can obtain a set comprising a plurality of time series, we call the instantaneous vector. It can be set corresponding instantaneous operation between the two vectors by the instantaneous vector set operation. Currently, Prometheus supports the following set of operators:

• and (and)
• or (or)
• unless (exclude)

vector1 and vector2  will produce a new vector consists of vector1 composition. The vector contains vector1 vector2 completely matching elements in the composition.

vector1 or vector2  will produce a new vector that contains all of the? sample data, and sample data does not match the vector1 vector2 to vector1 in.

The unless vector1 vector2  produce a new vector, the new vector elements by the element does not match vector1 vector2 composition.

Operator precedence

For complex types of expressions, we need to understand the operational priority of arithmetic operations

For example, query the host CPU utilization, you can use the expression:

100 * (1 - avg (irate(node_cpu{mode='idle'}[5m])) by(job) )

其中irate是PromQL中的内置函数，用于计算区间向量中时间序列每秒的即时增长率。关于内置函数的部分，会在下一节详细介绍。

PromQL operator in descending order of priority:

1. ^
2. *, /, %
3. +, -
4. ==, !=, <=, <, >=, >
5. and, unless
6. or

Detailed match mode

Will be based on the default matching rules when operating between vector and vector arithmetic: turn left and find calculates vector element matching (label exactly) the right of vector elements, if no match is found elements, then discarded.

There will next be described in two typical pattern matching in PromQL: one (one-to-one), many to one (many-to-one) or many (one-to-many).

One match

One on one? Match mode from both sides of the transient expression vector operator acquired in order to compare and find a unique sample values ​​match (label exactly) of. By default, use the expression:

vector1 <operator> vector2

At both sides of operator expressions inconsistent case labels may be used on (label list) or ignoring (label list) matched to modify the behavior of the notes. Use ignoreing can ignore some notes in the match. And means for matching on the behavior within certain defined in the notes.

<vector expr> <bin-op> ignoring(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) <vector expr>

For example when the sample is present:

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
method:http_requests:rate5m{method="post"} 120

 

Use PromQL expression:

method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m

The expression returns in the last five minutes, HTTP request status code 500 in the proportion of all requests. If no ignoring (code), the transient expression in the sides of the operator returns a label identical vector could not find any matches.

Therefore, results are as follows:

{method="get"}  0.04            //  24 / 600
{method="post"} 0.05            //   6 / 120

And because the method is put and del of? Sample? No match is found, it will not appear in the results of them.

And many-to-many

And many-to-many two kinds of matching mode refers to the "a" side of each vector element may be "many" side of the plurality of matching elements. In this case, you must use the group modifier: group_left or group_right to determine which vector has a higher base (acting as "many" role).

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

And many-to-many modes must be present in case of inconsistency tag vector expression returns both the operator. Ignoring and on the use it is necessary to exclude or modifiers defined the matching tag list.

For example, use the expression:

method_code:http_errors:rate5m / ignoring(code) group_left method:http_requests:rate5m

The expression, left vector contains two tabs method and code. And the right vector contains only one label method, it is necessary to use the matching tag is defined ignoring code match. After defining the matching tag, a right vector elements may be matched to the plurality of element vectors left so that the expression pattern matching many to one, requires the use of the specified group modifier group_left left base vector has better.method_coderate5mmethodrate5m

The final operation result is as follows:

{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

Reminder: group modifier can only be used in comparing and mathematical operator. In the logical operation and, unless noted, and only operation or default matched with all the elements of the right vector.