[GitHub] [skywalking] wankai123 commented on a diff in pull request #10459: Add PromQL Service doc and how to use in Grafana.

["wankai123 (via GitHub)" <gi...@apache.org>]

wankai123 commented on code in PR #10459:
URL: https://github.com/apache/skywalking/pull/10459#discussion_r1119846765


##########
docs/en/api/promql-service.md:
##########
@@ -0,0 +1,632 @@
+# PromQL Service
+PromQL([Prometheus Query Language](https://prometheus.io/docs/prometheus/latest/querying/basics/)) Service
+provide Promql-based expression language and HTTP API.
+Third-party systems or visualization platforms that already support PromQL (such as Grafana),
+If metrics data are required for integration, they can be obtained directly from SkyWalking through the PromQL Service.
+
+Since SkyWalking and Prometheus have different mechanisms for metrics including classification, format, storage, etc.
+The PromQL Service supported will be a subset of the full PromQL.
+
+## Details Of Supported Protocol
+The following doc describes the details of the supported protocol and compared it to the PromQL official documentation.
+If not mentioned, it will not be supported by default.
+
+### Time series Selectors
+#### [Instant Vector Selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#instant-vector-selectors)
+For example: select metric `service_cpm` which the service is `$service` and the layer is `$layer`.
+```shell
+service_cpm{service='$service', layer='$layer'}
+```
+**Note: The label matching operators only support `=` instead of regular expressions.**
+
+#### [Range Vector Selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#range-vector-selectors)
+For example: select metric `service_cpm` which the service is `$service` and the layer is `$layer` within the last 5 minutes.
+```shell
+service_cpm{service='$service', layer='$layer'}[5m]
+```
+
+#### [Time Durations](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations)
+| Unit | Definition   | Support |
+|------|--------------|---------|
+| ms   | milliseconds | yes     |
+| s    | seconds      | yes     |
+| m    | minutes      | yes     |
+| h    | hours        | yes     |
+| d    | days         | yes     |
+| w    | weeks        | yes     |
+| y    | years        | **no**  |
+
+### Binary operators
+#### [Arithmetic binary operators](https://prometheus.io/docs/prometheus/latest/querying/operators/#arithmetic-binary-operators)
+| Operator | Definition           | Support |
+|----------|----------------------|---------|
+| +        | addition             | yes     |
+| -        | subtraction          | yes     |
+| *        | multiplication       | yes     |
+| /        | division             | yes     |
+| %        | modulo               | yes     |
+| ^        | power/exponentiation | **no**  |
+
+##### Between two scalars
+For example:
+```shell
+1 + 2
+```
+
+##### Between an instant vector and a scalar
+For example:
+```shell
+service_cpm{service='$service', layer='$layer'} / 100
+```
+
+##### Between two instant vectors
+For example:
+```shell
+service_cpm{service='$service', layer='$layer'} + service_cpm{service='$service', layer='$layer'}
+```
+
+**Note: The operations between vectors require the same metric and labels, and don't support [Vector matching](https://prometheus.io/docs/prometheus/latest/querying/operators/#vector-matching).**
+
+#### [Comparison binary operators](https://prometheus.io/docs/prometheus/latest/querying/operators/#comparison-binary-operators)
+| Operator | Definition       | Support |
+|----------|------------------|---------|
+| ==       | equal            | yes     |
+| !=       | not-equal        | yes     |
+| \>       | greater-than     | yes     |
+| <        | less-than        | yes     |
+| \>=      | greater-or-equal | yes     |
+| <=       | less-or-equal)   | yes     |
+##### Between two scalars
+For example:
+```shell
+1 > bool 2
+```
+
+##### Between an instant vector and a scalar
+For example:
+```shell
+service_cpm{service='$service', layer='$layer'} > 1
+```
+
+##### Between two instant vectors
+For example:
+```shell
+service_cpm{service='service_A', layer='$layer'} > service_cpm{service='service_B', layer='$layer'}
+```
+
+### HTTP API
+
+#### Expression queries
+
+##### [Instant queries](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries)
+```shell
+GET|POST /api/v1/query
+```
+
+| Parameter | Definition                                                                                                                          | Support | Optional   |

Review Comment:
   In the Prometheus official doc, use `Optional` so I think follow this is better.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org