Project: SkyWalking (Observability and Analysis / Observability)
File: promql-service.md

PromQL() Service exposes Prometheus Querying HTTP APIs including the bundled PromQL expression system. Third-party systems or visualization platforms that already support PromQL (such as Grafana), could obtain metrics through PromQL Service. As SkyWalking and Prometheus have fundamental differences in metrics classification, format, storage, etc. The PromQL Service supported will be a subset of the complete PromQL. 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. For example: select metric `service_cpm` which the service is `$service` and the layer is `$layer`. ```text service_cpm{service='$service', layer='$layer'} ``` Note: The label matching operators only support `=` instead of regular expressions. For example: select metric `service_cpm` which the service is `$service` and the layer is `$layer` within the last 5 minutes. ```text service_cpm{service='$service', layer='$layer'}[5m] ``` | Unit | Definition | Support | ||--|| | ms | milliseconds | yes | | s | seconds | yes | | m | minutes | yes | | h | hours | yes | | d | days | yes | | w | weeks | yes | | y | years | no | | Operator | Definition | Support | |-|-|| | + | addition | yes | | - | subtraction | yes | | * | multiplication | yes | | / | division | yes | | % | modulo | yes | | ^ | power/exponentiation | no | For example: ```text 1 + 2 ``` For example: ```text service_cpm{service='$service', layer='$layer'} / 100 ``` For example: ```text servicecpm{service='$service', layer='$layer'} + servicecpm{service='$service', layer='$layer'} ``` Note: The operations between vectors require the same metric and labels, and don't support . | Operator | Definition | Support | |-||| | == | equal | yes | | != | not-equal | yes | | \> | greater-than | yes | | < | less-than | yes | | \>= | greater-or-equal | yes | | <= | less-or-equal) | yes | For example: ```text 1 > bool 2 ``` For example: ```text service_cpm{service='$service', layer='$layer'} > 1 ``` For example: ```text servicecpm{service='serviceA', layer='$layer'} > servicecpm{service='serviceB', layer='$layer'} ``` ```text 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

| yes | yes | | timeout | evaluation timeout | no | ignore | For example: ```text /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" ] } ] } } ``` ```text 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: ```text /api/v1/queryrange?query=servicecpm{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" ] ] } ] } } ``` ```text 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: ```text /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 ```text GET|POST /api/v1/labels ``` | Parameter | Definition | Support | Optional | |--|||-| | match[] | series selector | yes | yes | | start | start timestamp | no | yes | | end | end timestamp, if end time is not present, use current time as default end time | yes | yes | For example: ```text /api/v1/labels?match[]=instancejvmcpu' ``` Result: ```json { "status": "success", "data": [ "layer", "service", "top_n", "order", "service_instance", "parent_service" ] } ``` ```text GET /api/v1/label/<label_name>/values ``` | Parameter | Definition | Support | Optional | |--|||-| | match[] | series selector | yes | yes | | start | start timestamp | no | yes | | end | end timestamp, if end time is not present, use current time as default end time | yes | yes | For example: ```text /api/v1/label/name/values ``` Result: ```json { "status": "success", "data": [ "metermysqlinstance_qps", "service_cpm", "envoyclusteruprqactive", "instancejvmclassloadedclass_count", "k8sclustermemory_requests", "metervmmemory_used", "meterapisixsvbandwidthunmatched", "metervmmemory_total", "instancejvmthreadlivecount", "instancejvmthreadtimedwaitingstatethread_count", "browserapppagefirstpack_percentile", "instanceclrmaxworkerthreads", ... ] } ``` ```text GET /api/v1/metadata ``` | Parameter | Definition | Support | Optional | |--|||-| | limit | maximum number of metrics to return | yes | yes | | metric | metric name, support regular expression | yes | yes | For example: ```text /api/v1/metadata?limit=10 ``` Result: ```json { "status": "success", "data": { "metermysqlinstance_qps": [ { "type": "gauge", "help": "", "unit": "" } ], "meterapisixsvbandwidthunmatched": [ { "type": "gauge", "help": "", "unit": "" } ], "service_cpm": [ { "type": "gauge", "help": "", "unit": "" } ],

} } ``` Not all scopes are supported for now, please check the following table: | Scope | Support | |-|| | Service | yes | | ServiceInstance | yes | | Endpoint | yes | | ServiceRelation | no | | ServiceInstanceRelation | no | | Process | no | | ProcessRelation | no | Each metric contains general labels: . Different metrics will have different labels depending on their Scope and metric value type. | Query Labels | Scope | Expression Example | |-|--|| | layer, service | Service | service_cpm{service='$service', layer='$layer'} | | layer, service, serviceinstance | ServiceInstance | serviceinstancecpm{service='$service', serviceinstance='$service_instance', layer='$layer'} | | layer, service, endpoint | Endpoint | endpoint_cpm{service='$service', endpoint='$endpoint', layer='$layer'} | Query Labels: ```text {General labels} ``` Expression Example: ```text service_cpm{service='agent::songs', layer='GENERAL'} ``` Result (Instant Query): ```json { "status": "success", "data": { "resultType": "vector", "result": [ { "metric": { "name": "service_cpm", "layer": "GENERAL", "scope": "Service", "service": "agent::songs" }, "value": [ 1677490740, "3" ] } ] } } ``` Query Labels: ```text --{General labels} --metric labels: Used to filter the value labels to be returned ``` Expression Example: ```text service_percentile{service='agent::songs', layer='GENERAL', p='50,75,90'} ``` Result (Instant Query): ```json { "status": "success", "data": { "resultType": "vector", "result": [ { "metric": { "name": "service_percentile", "p": "50", "layer": "GENERAL", "scope": "Service", "service": "agent::songs" }, "value": [ 1677493380, "0" ] }, { "metric": { "name": "service_percentile", "p": "75", "layer": "GENERAL", "scope": "Service", "service": "agent::songs" }, "value": [ 1677493380, "0" ] }, { "metric": { "name": "service_percentile", "p": "90", "layer": "GENERAL", "scope": "Service", "service": "agent::songs" }, "value": [ 1677493380, "0" ] } ] } } ``` Query Labels: ```text --parent_service: <optional> Name of the parent service. --top_n: The max number of the selected metric value --order: ASC/DES ``` Expression Example: ```text serviceinstancecpm{parentservice='agent::songs', layer='GENERAL', topn='10', order='DES'} ``` Result (Instant Query): ```json { "status": "success", "data": { "resultType": "vector", "result": [ { "metric": { "name": "serviceinstancecpm", "layer": "GENERAL", "scope": "ServiceInstance", "service_instance": "651db53c0e3843d8b9c4c53a90b4992a@10.4.0.28" }, "value": [ 1677494280, "14" ] }, { "metric": { "name": "serviceinstancecpm", "layer": "GENERAL", "scope": "ServiceInstance", "service_instance": "4c04cf44d6bd408880556aa3c2cfb620@10.4.0.232" }, "value": [ 1677494280, "6" ] }, { "metric": { "name": "serviceinstancecpm", "layer": "GENERAL", "scope": "ServiceInstance", "service_instance": "f5ac8ead31af4e6795cae761729a2742@10.4.0.236" }, "value": [ 1677494280, "5" ] } ] } } ``` Query Labels: ```text --parent_service: Name of the parent service --top_n: The max number of the selected records value --order: ASC/DES ``` Expression Example: ```text topndatabasestatement{parentservice='localhost:-1', layer='VIRTUALDATABASE', topn='10', order='DES'} ``` Result (Instant Query): ```json { "status": "success", "data": { "resultType": "vector", "result": [ { "metric": { "name": "topndatabase_statement", "layer": "VIRTUAL_DATABASE", "scope": "Service", "record": "select song0.id as id10, song0.artist as artist20, song0.genre as genre30, song0.liked as liked40, song0.name as name50 from song song0 where song0_.liked>?" }, "value": [ 1677501360, "1" ] }, { "metric": { "name": "topndatabase_statement", "layer": "VIRTUAL_DATABASE", "scope": "Service", "record": "select song0.id as id10, song0.artist as artist20, song0.genre as genre30, song0.liked as liked40, song0.name as name50 from song song0 where song0_.liked>?" }, "value": [ 1677501360, "1" ] }, { "metric": { "name": "topndatabase_statement", "layer": "VIRTUAL_DATABASE", "scope": "Service", "record": "select song0.id as id10, song0.artist as artist20, song0.genre as genre30, song0.liked as liked40, song0.name as name50 from song song0 where song0_.liked>?" }, "value": [ 1677501360, "1" ] } ] } } ```