You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by "kezhenxu94 (via GitHub)" <gi...@apache.org> on 2023/02/28 09:42:16 UTC
[GitHub] [skywalking] kezhenxu94 commented on a diff in pull request #10459: Add PromQL Service doc and how to use in Grafana.
kezhenxu94 commented on code in PR #10459:
URL: https://github.com/apache/skywalking/pull/10459#discussion_r1119799037
##########
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 |
+|-----------|-------------------------------------------------------------------------------------------------------------------------------------|---------|------------|
+| query | prometheus expression | yes | no |
+| time | **The latest metrics value from current time to this time is returned. If time is empty, the default look-back time is 2 minutes.** | yes | yes |
+| timeout | evaluation timeout | **no** | **ignore** |
+
+For example:
+```shell
+/api/v1/query?query=service_cpm{service='agent::songs', layer='GENERAL'}
+```
+
+Result:
+```json
+{
+ "status": "success",
+ "data": {
+ "resultType": "vector",
+ "result": [
+ {
+ "metric": {
+ "__name__": "service_cpm",
+ "layer": "GENERAL",
+ "scope": "Service",
+ "service": "agent::songs"
+ },
+ "value": [
+ 1677548400,
+ "6"
+ ]
+ }
+ ]
+ }
+}
+```
+
+##### [Range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries)
+```shell
+GET|POST /api/v1/query_range
+```
+
+| Parameter | Definition | Support | Optional |
+|-----------|--------------------------------------------------------------------------------------|---------|------------|
+| query | prometheus expression | yes | no |
+| start | start timestamp, **seconds** | yes | no |
+| end | end timestamp, **seconds** | yes | no |
+| step | **SkyWalking will automatically fit Step(DAY, HOUR, MINUTE) through start and end.** | **no** | **ignore** |
+| timeout | evaluation timeout | **no** | **ignore** |
+
+For example:
+```shell
+/api/v1/query_range?query=service_cpm{service='agent::songs', layer='GENERAL'}&start=1677479336&end=1677479636
+```
+
+Result:
+```json
+{
+ "status": "success",
+ "data": {
+ "resultType": "matrix",
+ "result": [
+ {
+ "metric": {
+ "__name__": "service_cpm",
+ "layer": "GENERAL",
+ "scope": "Service",
+ "service": "agent::songs"
+ },
+ "values": [
+ [
+ 1677479280,
+ "18"
+ ],
+ [
+ 1677479340,
+ "18"
+ ],
+ [
+ 1677479400,
+ "18"
+ ],
+ [
+ 1677479460,
+ "18"
+ ],
+ [
+ 1677479520,
+ "18"
+ ],
+ [
+ 1677479580,
+ "18"
+ ]
+ ]
+ }
+ ]
+ }
+}
+```
+
+#### Querying metadata
+
+##### [Finding series by label matchers](https://prometheus.io/docs/prometheus/latest/querying/api/#finding-series-by-label-matchers)
+```shell
+GET|POST /api/v1/series
+```
+
+| Parameter | Definition | Support | Optional |
+|-----------|------------------------------|---------|----------|
+| match[] | series selector | yes | no |
+| start | start timestamp, **seconds** | yes | no |
+| end | end timestamp, **seconds** | yes | no |
+
+For example:
+```shell
+/api/v1/series?match[]=service_traffic{layer='GENERAL'}&start=1677479336&end=1677479636
+```
+
+Result:
+```json
+{
+ "status": "success",
+ "data": [
+ {
+ "__name__": "service_traffic",
+ "service": "agent::songs",
+ "scope": "Service",
+ "layer": "GENERAL"
+ },
+ {
+ "__name__": "service_traffic",
+ "service": "agent::recommendation",
+ "scope": "Service",
+ "layer": "GENERAL"
+ },
+ {
+ "__name__": "service_traffic",
+ "service": "agent::app",
+ "scope": "Service",
+ "layer": "GENERAL"
+ },
+ {
+ "__name__": "service_traffic",
+ "service": "agent::gateway",
+ "scope": "Service",
+ "layer": "GENERAL"
+ },
+ {
+ "__name__": "service_traffic",
+ "service": "agent::frontend",
+ "scope": "Service",
+ "layer": "GENERAL"
+ }
+ ]
+}
+```
+
+**Note: SkyWalking's metadata exists in the following metrics(traffics):**
+- service_traffic
+- instance_traffic
+- endpoint_traffic
+
+#### [Getting label names](https://prometheus.io/docs/prometheus/latest/querying/api/#getting-label-names)
+```shell
+GET|POST /api/v1/labels
+```
+
+| Parameter | Definition | Support | Optional |
+|-----------|-----------------|---------|----------|
+| match[] | series selector | yes | yes |
+| start | start timestamp | **no** | yes |
+| end | end timestamp | **no** | yes |
+
+For example:
+```shell
+/api/v1/labels?match[]=instance_jvm_cpu'
+```
+
+Result:
+```json
+{
+ "status": "success",
+ "data": [
+ "layer",
+ "scope",
+ "top_n",
+ "order",
+ "service_instance",
+ "parent_service"
+ ]
+}
+```
+
+#### [Querying label values](https://prometheus.io/docs/prometheus/latest/querying/api/#querying-label-values)
+```shell
+GET /api/v1/label/<label_name>/values
+```
+
+| Parameter | Definition | Support | Optional |
+|-----------|-----------------|---------|----------|
+| match[] | series selector | yes | no |
+| start | start timestamp | **no** | yes |
+| end | end timestamp | **no** | yes |
+
+For example:
+```shell
+/api/v1/label/__name__/values'
Review Comment:
Look like a typo, and there are the same typos in other places, please check
```suggestion
/api/v1/label/__name__/values
```
--
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