SkyWalking内置MQE语法

此文档出自SkyWalking官方git https://github.com/apache/skywalking
docs/en/api/metrics-query-expression.md

Metrics Query Expression(MQE) Syntax

MQE is a string that consists of one or more expressions. Each expression could be a combination of one or more operations.

The expression allows users to do simple query-stage calculation through V3 APIs.

text 复制代码
Expression = <Operation> Expression1 <Operation> Expression2 <Operation> Expression3 ...

The following document lists the operations supported by MQE.

Metrics Expression

Metrics Expression will return a collection of time-series values.

Common Value Metrics

Expression:

text 复制代码
<metric_name>

For example:

If we want to query the service_sla metric, we can use the following expression:

text 复制代码
service_sla
Result Type

The ExpressionResultType of the expression is TIME_SERIES_VALUES.

Labeled Value Metrics

For now, we only have a single anonymous label with multi label values in a labeled metric.

To be able to use it in expressions, define _ as the anonymous label name (key).

Expression:

text 复制代码
<metric_name>{_='<label_value_1>,...'}

{_='<label_value_1>,...'} is the selected label value of the metric. If is not specified, all label values of the metric will be selected.

For example:

If we want to query the service_percentile metric with the label values 0,1,2,3,4, we can use the following expression:

text 复制代码
service_percentile{_='0,1,2,3,4'}

If we want to rename the label values to P50,P75,P90,P95,P99, see [Relabel Operation](#Relabel Operation).

Result Type

The ExpressionResultType of the expression is TIME_SERIES_VALUES and with labels.

Binary Operation

The Binary Operation is an operation that takes two expressions and performs a calculation on their results.

The following table lists the binary operations supported by MQE.

Expression:

text 复制代码
Expression1 <Binary-Operator> Expression2
Operator Definition
+ addition
- subtraction
* multiplication
/ division
% modulo

For example:

If we want to transform the service_sla metric value to percent, we can use the following expression:

text 复制代码
service_sla / 100

Result Type

For the result type of the expression, please refer to the following table.

Binary Operation Rules

The following table lists if the different result types of the input expressions could do this operation and the result type after the operation.

The expression could be on the left or right side of the operator.
Note : If the expressions on both sides of the operator are the TIME_SERIES_VALUES with labels, they should have the same labels for calculation.

Expression Expression Yes/No ExpressionResultType
SINGLE_VALUE SINGLE_VALUE Yes SINGLE_VALUE
SINGLE_VALUE TIME_SERIES_VALUES Yes TIME_SERIES_VALUES
SINGLE_VALUE SORTED_LIST/RECORD_LIST Yes SORTED_LIST/RECORD_LIST
TIME_SERIES_VALUES TIME_SERIES_VALUES Yes TIME_SERIES_VALUES
TIME_SERIES_VALUES SORTED_LIST/RECORD_LIST no
SORTED_LIST/RECORD_LIST SORTED_LIST/RECORD_LIST no

Compare Operation

Compare Operation takes two expressions and compares their results.

The following table lists the compare operations supported by MQE.

Expression:

text 复制代码
Expression1 <Compare-Operator> Expression2
Operator Definition
> greater than
>= greater than or equal
< less than
<= less than or equal
== equal
!= not equal

The result of the compare operation is an int value:

  • 1: true
  • 0: false

For example:

Compare the service_resp_time metric value if greater than 3000, if the service_resp_time result is:

json 复制代码
{
  "data": {
    "execExpression": {
      "type": "TIME_SERIES_VALUES",
      "error": null,
      "results": [
        {
          "metric": {
            "labels": []
          },
          "values": [{"id": "1691658000000", "value": "2500", "traceID": null}, {"id": "1691661600000", "value": 3500, "traceID": null}]
        }
      ]
    }
  }
}

we can use the following expression:

text 复制代码
service_resp_time > 3000

and get result:

json 复制代码
{
  "data": {
    "execExpression": {
      "type": "TIME_SERIES_VALUES",
      "error": null,
      "results": [
        {
          "metric": {
            "labels": []
          },
          "values": [{"id": "1691658000000", "value": "0", "traceID": null}, {"id": "1691661600000", "value": 1, "traceID": null}]
        }
      ]
    }
  }
}

Compare Operation Rules and Result Type

Same as the [Binary Operation Rules](#Binary Operation Rules).

Aggregation Operation

Aggregation Operation takes an expression and performs aggregate calculations on its results.

Expression:

text 复制代码
<Aggregation-Operator>(Expression)
Operator Definition ExpressionResultType
avg average the result SINGLE_VALUE
count count number of the result SINGLE_VALUE
latest select the latest non-null value from the result SINGLE_VALUE
sum sum the result SINGLE_VALUE
max select maximum from the result SINGLE_VALUE
min select minimum from the result SINGLE_VALUE

For example:

If we want to query the average value of the service_cpm metric, we can use the following expression:

text 复制代码
avg(service_cpm)

Result Type

The different operators could impact the ExpressionResultType, please refer to the above table.

Mathematical Operation

Mathematical Operation takes an expression and performs mathematical calculations on its results.

Expression:

text 复制代码
<Mathematical-Operator>(Expression, parameters)
Operator Definition parameters ExpressionResultType
abs returns the absolute value of the result follow the input expression
ceil returns the smallest integer value that is greater or equal to the result follow the input expression
floor returns the largest integer value that is greater or equal to the result follow the input expression
round returns result round to specific decimal places places: a positive integer specific decimal places of the result follow the input expression

For example:

If we want to query the average value of the service_cpm metric in seconds,

and round the result to 2 decimal places, we can use the following expression:

text 复制代码
round(service_cpm / 60 , 2)

Result Type

The different operators could impact the ExpressionResultType, please refer to the above table.

TopN Operation

TopN Operation takes an expression and performs TopN calculation on its results.

Expression:

text 复制代码
top_n(<metric_name>, <top_number>, <order>)

top_number is the number of the top results, should be a positive integer.

order is the order of the top results. The value of order can be asc or des.

For example:

If we want to query the top 10 services with the highest service_cpm metric value, we can use the following expression:

text 复制代码
top_n(service_instance_cpm, 10, des)

Result Type

According to the type of the metric, the ExpressionResultType of the expression will be SORTED_LIST or RECORD_LIST.

Relabel Operation

Relabel Operation takes an expression and replaces the label values with new label values on its results.

Expression:

text 复制代码
relabel(Expression, _='<new_label_value_1>,...')

_ is the new label of the metric after the label is relabeled, the order of the new label values should be the same as the order of the label values in the input expression result.

For example:

If we want to query the service_percentile metric with the label values 0,1,2,3,4, and rename the label values to P50,P75,P90,P95,P99, we can use the following expression:

text 复制代码
relabel(service_percentile{_='0,1,2,3,4'}, _='P50,P75,P90,P95,P99')

Result Type

Follow the input expression.

AggregateLabels Operation

AggregateLabels Operation takes an expression and performs an aggregate calculation on its Labeled Value Metrics results. It aggregates a group of TIME_SERIES_VALUES into a single TIME_SERIES_VALUES.

Expression:

text 复制代码
aggregate_labels(Expression, parameter)
parameter Definition ExpressionResultType
avg calculate avg value of a Labeled Value Metrics TIME_SERIES_VALUES
sum calculate sum value of a Labeled Value Metrics TIME_SERIES_VALUES
max select the maximum value from a Labeled Value Metrics TIME_SERIES_VALUES
min select the minimum value from a Labeled Value Metrics TIME_SERIES_VALUES

For example:

If we want to query all Redis command total rates, we can use the following expression(total_commands_rate is a metric which recorded every command rate in labeled value):

text 复制代码
aggregate_labels(total_commands_rate, SUM)

Result Type

The ExpressionResultType of the aggregateLabels operation is TIME_SERIES_VALUES.

Logical Operation

ViewAsSequence Operation

ViewAsSequence operation represents the first not-null metric from the listing metrics in the given prioritized sequence(left to right). It could also be considered as a short-circuit of given metrics for the first value existing metric.

Expression:

text 复制代码
view_as_seq([<expression_1>, <expression_2>, ...])

For example:

if the first expression value is empty but the second one is not empty, it would return the result from the second expression.

The following example would return the content of the service_cpm metric.

text 复制代码
view_as_seq(not_existing, service_cpm)
Result Type

The result type is determined by the type of selected not-null metric expression.

Expression Query Example

Labeled Value Metrics

text 复制代码
service_percentile{_='0,1'}

The example result is:

json 复制代码
{
  "data": {
    "execExpression": {
      "type": "TIME_SERIES_VALUES",
      "error": null,
      "results": [
        {
          "metric": {
            "labels": [{"key": "_", "value": "0"}]
          },
          "values": [{"id": "1691658000000", "value": "1000", "traceID": null}, {"id": "1691661600000", "value": 2000, "traceID": null}]
        },
        {
          "metric": {
            "labels": [{"key": "_", "value": "1"}]
          },
          "values": [{"id": "1691658000000", "value": "2000", "traceID": null}, {"id": "1691661600000", "value": 3000, "traceID": null}]
        }
      ]
    }
  }
}

If we want to transform the percentile value unit from ms to s the expression is:

text 复制代码
service_percentile{_='0,1'} / 1000
json 复制代码
{
  "data": {
    "execExpression": {
      "type": "TIME_SERIES_VALUES",
      "error": null,
      "results": [
        {
          "metric": {
            "labels": [{"key": "_", "value": "0"}]
          },
          "values": [{"id": "1691658000000", "value": "1", "traceID": null}, {"id": "1691661600000", "value": 2, "traceID": null}]
        },
        {
          "metric": {
            "labels": [{"key": "_", "value": "1"}]
          },
          "values": [{"id": "1691658000000", "value": "2", "traceID": null}, {"id": "1691661600000", "value": 3, "traceID": null}]
        }
      ]
    }
  }
}

Get the average value of each percentile, the expression is:

text 复制代码
avg(service_percentile{_='0,1'})
json 复制代码
{
  "data": {
    "execExpression": {
      "type": "SINGLE_VALUE",
      "error": null,
      "results": [
        {
          "metric": {
            "labels": [{"key": "_", "value": "0"}]
          },
          "values": [{"id": null, "value": "1500", "traceID": null}]
        },
        {
          "metric": {
            "labels": [{"key": "_", "value": "1"}]
          },
          "values": [{"id": null, "value": "2500", "traceID": null}]
        }
      ]
    }
  }
}

Calculate the difference between the percentile and the average value, the expression is:

text 复制代码
service_percentile{_='0,1'} - avg(service_percentile{_='0,1'})
json 复制代码
{
  "data": {
    "execExpression": {
      "type": "TIME_SERIES_VALUES",
      "error": null,
      "results": [
        {
          "metric": {
            "labels": [{"key": "_", "value": "0"}]
          },
          "values": [{"id": "1691658000000", "value": "-500", "traceID": null}, {"id": "1691661600000", "value": 500, "traceID": null}]
        },
        {
          "metric": {
            "labels": [{"key": "_", "value": "1"}]
          },
          "values": [{"id": "1691658000000", "value": "-500", "traceID": null}, {"id": "1691661600000", "value": 500, "traceID": null}]
        }
      ]
    }
  }
}

Calculate the difference between the service_resp_time and the service_percentile, if the service_resp_time result is:

json 复制代码
{
  "data": {
    "execExpression": {
      "type": "TIME_SERIES_VALUES",
      "error": null,
      "results": [
        {
          "metric": {
            "labels": []
          },
          "values": [{"id": "1691658000000", "value": "2500", "traceID": null}, {"id": "1691661600000", "value": 3500, "traceID": null}]
        }
      ]
    }
  }
}

The expression is:

text 复制代码
service_resp_time - service_percentile{_='0,1'}
json 复制代码
{
  "data": {
    "execExpression": {
      "type": "TIME_SERIES_VALUES",
      "error": null,
      "results": [
        {
          "metric": {
            "labels": [{"key": "_", "value": "0"}]
          },
          "values": [{"id": "1691658000000", "value": "1500", "traceID": null}, {"id": "1691661600000", "value": "1500", "traceID": null}]
        },
        {
          "metric": {
            "labels": [{"key": "_", "value": "1"}]
          },
          "values": [{"id": "1691658000000", "value": "500", "traceID": null}, {"id": "1691661600000", "value": "500", "traceID": null}]
        }
      ]
    }
  }
}
相关推荐
老三牛擦7 小时前
熟悉Docker及Docker-Compose。熟悉Linux常用命令,编写基本Shell脚本。可搭建Jenkins进行Dev/Ops。
skywalking
老三牛擦3 天前
熟练掌握RabbitMQ和Kafka的使用及相关应用场景。异步通知与解耦,流量削峰,配合本地消息表实现事务的最终一致性并解决消息可靠、顺序消费和错误重试等问题
skywalking
老三牛擦4 天前
熟悉多线程与并发编程,理解各类锁机制,熟悉JUC并发多线程及线程池,熟练异步编排编码,熟悉Redisson在分布式场景下各类锁的应用场景和并发控制原理。
skywalking
5007014 天前
SkyWalking 部署与应用(Windows)
windows·skywalking
递归尽头是星辰1 个月前
SkyWalking架构深度解析:分布式系统监控的利器
skywalking·分布式链路追踪·可观测性·云原生监控·微服务监控
·云扬·1 个月前
【PmHub面试篇】性能监控与分布式追踪利器Skywalking面试专题分析
分布式·面试·skywalking
XMYX-02 个月前
SkyWalking 报错:sw_profile_task 索引缺失问题分析与解决
运维·jenkins·skywalking
神雕大侠mu2 个月前
skywalking使用教程
skywalking
杰克逊的日记2 个月前
SkyWalking的工作原理和搭建过程
云原生·监控·skywalking
醇氧2 个月前
【skywalking】index“:“skywalking_metrics-all“},“status“:404}
skywalking