PromQL Service: traffic query support limit and regex match. (#13162)

Author: wankai123

docs/en/api/promql-service.md

@@ -268,10 +268,31 @@ GET|POST /api/v1/series
 | match[]   | series selector                                     | yes     | no       |
 | start     | start, format: RFC3399 or unix_timestamp in seconds | yes     | no       |
 | end       | end, format: RFC3399 or unix_timestamp in seconds   | yes     | no       |
+| limit     | integer, maximum number of returned series          | yes     | yes      |
+
+**For metadata metrics**:
+**Note: SkyWalking's metadata exists in the following metrics(traffics):**
+
+| Name             | Require Labels | Optional Labels          | Support Label Match                                 |
+|------------------|----------------|--------------------------|-----------------------------------------------------|
+| service_traffic  | layer          | service, limit           | =, (only service label support !=, =~, !~)          |
+| instance_traffic | layer, service | service_instance, limit  | =, (only service_instance label support !=, =~, !~) |
+| endpoint_traffic | layer, service | endpoint, keyword, limit | =, (only endpoint label support !=, =~, !~)         |
+
+- **=**: Label value equals the provided string.
+- **!=**: Label value does not equal the provided string.
+- **=~**: Label value regex-match the provided string.
+- **!~**: Label value does not regex-match the provided string
+
+**If the `limit` is not set by parameter or label, the default value is 100. If the `limit ' is also set in the query parameter, it returns the minimum of the two.**
 
 For example:
 ```text
-/api/v1/series?match[]=service_traffic{layer='GENERAL'}&start=1677479336&end=1677479636
+/api/v1/series?match[]=service_traffic{layer='GENERAL'}&start=1677479336&end=1677479636&limit=5
+```
+or
+```text
+/api/v1/series?match[]=service_traffic{layer='GENERAL', limit='5'}&start=1677479336&end=1677479636
 ```
 
 Result:
@@ -313,10 +334,23 @@ Result:
 }
 ```
 
-**Note: SkyWalking's metadata exists in the following metrics(traffics):**
-- service_traffic
-- instance_traffic
-- endpoint_traffic
+- You can use the `service` label to filter the service_traffic result.
+```text
+/api/v1/series?match[]=service_traffic{layer='GENERAL', service='agent::songs'}&start=1677479336&end=1677479636
+```
+use regex:
+```text
+/api/v1/series?match[]=service_traffic{layer='GENERAL', service=~'agent::songs|agent::recommendation'}&start=1677479336&end=1677479636
+```
+- You can use the `service_instance` label to filter the instance_traffic result.
+```text
+/api/v1/series?match[]=service_traffic{layer='GENERAL', service='agent::songs', service_instance=~'instance1|instance2'}&start=1677479336&end=1677479636
+```
+- You can use the `endpoint` label to filter the endpoint_traffic result.
+```text
+/api/v1/series?match[]=service_traffic{layer='GENERAL', service='agent::songs', endpoint=~'endpoint1|endpoint2'}&start=1677479336&end=1677479636
+```
+
 
 #### Getting label names
 [Prometheus Docs Reference](https://prometheus.io/docs/prometheus/latest/querying/api/#getting-label-names)
@@ -330,6 +364,7 @@ GET|POST /api/v1/labels
 | match[]   | series selector                                                                 | yes     | yes      |
 | start     | start, format: RFC3399 or unix_timestamp in seconds                             | **no**  | yes      |
 | end       | end timestamp, if end time is not present, use current time as default end time | yes     | yes      |
+| limit     | integer, maximum number of returned labels, default 100                         | yes     | yes      |
 
 For example:
 ```text
@@ -363,11 +398,12 @@ GET /api/v1/label/<label_name>/values
 | match[]   | series selector                                                                                                     | yes     | yes      |
 | start     | start, format: RFC3399 or unix_timestamp in seconds                                                                 | **no**  | yes      |
 | end       | end, format: RFC3399 or unix_timestamp in seconds, if end time is not present, use current time as default end time | yes     | yes      |
+| limit     | integer, maximum number of returned label values, default 100                                                       | yes     | yes      |
 
 For example:
 ```text
 /api/v1/label/__name__/values
-```
+``` 
 
 Result:
 ```json
@@ -391,6 +427,39 @@ Result:
 }
 ```
 
+**For metadata metrics**:
+
+| Name             | Require Labels | Optional Labels          | Support Label Match                                 |
+|------------------|----------------|--------------------------|-----------------------------------------------------|
+| service_traffic  | layer          | service, limit           | =, (only service label support !=, =~, !~)          |
+| instance_traffic | layer, service | service_instance, limit  | =, (only service_instance label support !=, =~, !~) |
+| endpoint_traffic | layer, service | endpoint, keyword, limit | =, (only endpoint label support !=, =~, !~)         |
+
+- **=**: Label value equal to the provided string.
+- **!=**: Label value not equal to the provided string.
+- **=~**: Label value regex-match the provided string.
+- **!~**: Label value do not regex-match the provided string
+
+**If the `limit` is not set by parameter or label, the default value is 100. And If the `limit` also set in the query parameter, will return the min number of the two.**
+
+For example:
+- If you want to query the label values of the `service` label in the `service_traffic` metric:
+```text
+/api/v1/label/service/values?match[]=service_traffic{layer='GENERAL', service='agent::songs|agent::recommendation'}&limit=1
+```
+or
+```text
+/api/v1/label/service/values?match[]=service_traffic{layer='GENERAL', service='agent::songs|agent::recommendation',limit='1'}
+```
+- If you want to query the label values of the `service_instance` label in the `instance_traffic` metric:
+```text
+/api/v1/label/service_instance/values?match[]=instance_traffic{layer='GENERAL', service='agent::songs', service_instance='instance1|instance2'}
+```
+- If you want to query the label values of the `endpoint` label in the `endpoint_traffic` metric:
+```text
+/api/v1/label/endpoint/values?match[]=endpoint_traffic{layer='GENERAL', service='agent::songs', endpoint='endpoint1|endpoint2'}
+```
+
 #### Querying metric metadata
 [Prometheus Docs Reference](https://prometheus.io/docs/prometheus/latest/querying/api/#querying-metric-metadata)
 

docs/en/changes/changes.md

@@ -7,6 +7,7 @@
 * BanyanDB: Support `hot/warm/cold` stages configuration.
 * Fix query continues profiling policies error when the policy is already in the cache.
 * Support `hot/warm/cold` stages TTL query in the status API.
+* PromQL Service: traffic query support `limit` and regex match.
 
 #### UI
 

oap-server/server-query-plugin/promql-plugin/src/main/antlr4/org/apache/skywalking/promql/rt/grammar/PromQLLexer.g4

@@ -32,6 +32,11 @@ L_BRACE:     '{';
 R_BRACE:     '}';
 EQ:          '=';
 
+//regex-match
+RM:          '=~';
+//regex-not-match
+NRM:         '!~';
+
 // Scalar Binary operators
 SUB:         '-';
 ADD:         '+';

oap-server/server-query-plugin/promql-plugin/src/main/antlr4/org/apache/skywalking/promql/rt/grammar/PromQLParser.g4

@@ -50,10 +50,12 @@ metricRange:     metricInstant L_BRACKET DURATION R_BRACKET;
 
 labelName:       NAME_STRING;
 labelValue:      VALUE_STRING;
-label:           labelName EQ labelValue;
+label:           labelName matchOp labelValue;
 labelList:       label (COMMA label)*;
 labelNameList:   labelName (COMMA labelName)*;
 
+matchOp:        EQ | NEQ | RM | NRM;
+
 numberLiteral:   NUMBER;
 
 badRange:        NUMBER L_BRACKET DURATION R_BRACKET;

oap-server/server-query-plugin/promql-plugin/src/main/java/org/apache/skywalking/oap/query/promql/entity/response/LabelsQueryRsp.java

@@ -26,5 +26,5 @@
 @EqualsAndHashCode(callSuper = true)
 @Data
 public class LabelsQueryRsp extends QueryResponse {
-    private final List<String> data = new ArrayList<>();
+    private List<String> data = new ArrayList<>();
 }

oap-server/server-query-plugin/promql-plugin/src/main/java/org/apache/skywalking/oap/query/promql/entity/response/QueryFormatRsp.java

@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.apache.skywalking.oap.query.promql.entity.response;
+
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+@EqualsAndHashCode(callSuper = true)
+@Data
+public class QueryFormatRsp extends QueryResponse {
+    private String data;
+}