You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by "wankai123 (via GitHub)" <gi...@apache.org> on 2026/05/29 03:15:06 UTC
[PR] add back status query example [skywalking]
wankai123 opened a new pull request, #13886:
URL: https://github.com/apache/skywalking/pull/13886
(no comment)
--
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
Re: [PR] add back status query example [skywalking]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13886:
URL: https://github.com/apache/skywalking/pull/13886#discussion_r3321927898
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
+
+- HTTP GET method.
+
```bash
curl http://oap:17128/status/cluster/nodes
```
-### `/status/alarm/rules`
+```json
+{
+ "nodes": [
+ {
+ "host": "10.0.12.23",
+ "port": 11800,
+ "self": true
+ },
+ {
+ "host": "10.0.12.25",
+ "port": 11800,
+ "self": false
+ },
+ {
+ "host": "10.0.12.37",
+ "port": 11800,
+ "self": false
+ }
+ ]
+}
+```
+
+The `nodes` list all the nodes in the cluster. The size of the list should be exactly same as your cluster setup. The `host` and `port` are the address of the OAP node, which are used for OAP nodes communicating with each other. The `self` is a flag to indicate whether the node is the current node, others are remote nodes.
+
+### Alarm Runtime Status
+
+OAP calculates the alarm conditions in the memory based on the alarm rules and the metrics data. If the OAP cluster has multiple instances, each instance will calculate the alarm conditions independently. You can query from any OAP instance to get the all instances' alarm running status.
+
+The following APIs are exposed to make the alerting running kernel visible.
+
+#### /status/alarm/rules
+
+Return the list of alarm running rules.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ }
+ ]
+}
+```
+
+#### /status/alarm/rules/{ruleId}
+
+Return the detailed information of the alarm running rule.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_b_service",
+ "formattedMessage": "Service mock_b_service response time is more than 1000ms of last 10 minutes"
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_a_service",
+ "formattedMessage": "Service mock_a_service response time is more than 1000ms of last 10 minutes."
+ },
+ {
+ "scope": "SERVICE",
+ "name": "mock_c_service",
+ "formattedMessage": "Service mock_c_service response time is more than 1000ms of last 10 minutes."
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ }
+ ]
+}
+```
+
+- `additonalPeriod` is the additional period if the expression includes the [increase/rate function](../../../api/metrics-query-expression.md#trend-operation). This additional period is used to enlarge window size for calculating the trend value.
+- `runningEntities` is the entities that have metrics data and being calculated by the alarm rule.
+- `formattedMessages` is the result message according to the message template and the affected running entities.
Review Comment:
The field names in this explanation don’t match the JSON examples: `additionalPeriod` is misspelled as `additonalPeriod`, and the JSON uses `formattedMessage` (singular) rather than `formattedMessages`. This can confuse users who copy/paste field names.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
+
+- HTTP GET method.
+
```bash
curl http://oap:17128/status/cluster/nodes
```
-### `/status/alarm/rules`
+```json
+{
+ "nodes": [
+ {
+ "host": "10.0.12.23",
+ "port": 11800,
+ "self": true
+ },
+ {
+ "host": "10.0.12.25",
+ "port": 11800,
+ "self": false
+ },
+ {
+ "host": "10.0.12.37",
+ "port": 11800,
+ "self": false
+ }
+ ]
+}
+```
+
+The `nodes` list all the nodes in the cluster. The size of the list should be exactly same as your cluster setup. The `host` and `port` are the address of the OAP node, which are used for OAP nodes communicating with each other. The `self` is a flag to indicate whether the node is the current node, others are remote nodes.
+
+### Alarm Runtime Status
+
+OAP calculates the alarm conditions in the memory based on the alarm rules and the metrics data. If the OAP cluster has multiple instances, each instance will calculate the alarm conditions independently. You can query from any OAP instance to get the all instances' alarm running status.
+
+The following APIs are exposed to make the alerting running kernel visible.
+
+#### /status/alarm/rules
+
+Return the list of alarm running rules.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ }
+ ]
+}
+```
+
+#### /status/alarm/rules/{ruleId}
+
+Return the detailed information of the alarm running rule.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_b_service",
+ "formattedMessage": "Service mock_b_service response time is more than 1000ms of last 10 minutes"
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_a_service",
+ "formattedMessage": "Service mock_a_service response time is more than 1000ms of last 10 minutes."
+ },
+ {
+ "scope": "SERVICE",
+ "name": "mock_c_service",
+ "formattedMessage": "Service mock_c_service response time is more than 1000ms of last 10 minutes."
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ }
+ ]
+}
+```
+
+- `additonalPeriod` is the additional period if the expression includes the [increase/rate function](../../../api/metrics-query-expression.md#trend-operation). This additional period is used to enlarge window size for calculating the trend value.
+- `runningEntities` is the entities that have metrics data and being calculated by the alarm rule.
+- `formattedMessages` is the result message according to the message template and the affected running entities.
-Lists registered alarm rules.
+#### `/status/alarm/{ruleId}/{entityName}`
-### `/status/alarm/{ruleId}`
+Return the running context of the alarm rule.
-Per-rule runtime status — current window state, last evaluation, the
-entities the rule has triggered against.
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "endTime": "2025-11-19T15:20:00.000",
+ "additionalPeriod": 0,
+ "size": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 0,
+ "silenceCountdown": 10,
+ "recoveryObservationCountdown": 0,
+ "currentState": "FIRING",
+ "entityName": "mock_b_service",
+ "windowValues": [
+ {
+ "index": 0,
+ "metrics": []
+ },
+ {
+ "index": 1,
+ "metrics": []
+ },
+ {
+ "index": 2,
+ "metrics": []
+ },
+ {
+ "index": 3,
+ "metrics": []
+ },
+ {
+ "index": 4,
+ "metrics": []
+ },
+ {
+ "index": 5,
+ "metrics": []
+ },
+ {
+ "index": 6,
+ "metrics": []
+ },
+ {
+ "index": 7,
+ "metrics": []
+ },
+ {
+ "index": 8,
+ "metrics": [
+ {
+ "name": "service_resp_time",
+ "timeBucket": 202511191519,
+ "value": "6000"
+ }
+ ]
+ },
+ {
+ "index": 9,
+ "metrics": []
+ }
+ ],
+ "mqeMetricsSnapshot": {
+ "service_resp_time": "[{\"metric\":{\"labels\":[]},\"values\":[{\"id\":\"202511191511\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191512\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191513\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191514\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191515\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191516\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191517\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191518\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191519\",\"doubleValue\":6000.0,\"isEmptyValue\":false},{\"id\":\"202511191520\",\"doubleValue\":0.0,\"isEmptyValue\":true}]}]"
+ },
+ "lastAlarmTime": "1763536823628",
Review Comment:
`lastAlarmTime` is a `long` in the status payload, but this example shows it as a JSON string. The second instance in the same example uses a numeric value (`0`), so this is inconsistent and may mislead clients about the field type.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Review Comment:
Endpoint headings are formatted inconsistently: some are wrapped in backticks (code style) while others are plain text. Consistent formatting makes the endpoint list easier to scan and avoids accidental Markdown rendering issues.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
+
+- HTTP GET method.
+
```bash
curl http://oap:17128/status/cluster/nodes
```
-### `/status/alarm/rules`
+```json
+{
+ "nodes": [
+ {
+ "host": "10.0.12.23",
+ "port": 11800,
+ "self": true
+ },
+ {
+ "host": "10.0.12.25",
+ "port": 11800,
+ "self": false
+ },
+ {
+ "host": "10.0.12.37",
+ "port": 11800,
+ "self": false
+ }
+ ]
+}
+```
+
+The `nodes` list all the nodes in the cluster. The size of the list should be exactly same as your cluster setup. The `host` and `port` are the address of the OAP node, which are used for OAP nodes communicating with each other. The `self` is a flag to indicate whether the node is the current node, others are remote nodes.
+
+### Alarm Runtime Status
+
+OAP calculates the alarm conditions in the memory based on the alarm rules and the metrics data. If the OAP cluster has multiple instances, each instance will calculate the alarm conditions independently. You can query from any OAP instance to get the all instances' alarm running status.
+
+The following APIs are exposed to make the alerting running kernel visible.
+
+#### /status/alarm/rules
+
+Return the list of alarm running rules.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ }
+ ]
+}
+```
+
+#### /status/alarm/rules/{ruleId}
+
+Return the detailed information of the alarm running rule.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_b_service",
+ "formattedMessage": "Service mock_b_service response time is more than 1000ms of last 10 minutes"
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_a_service",
+ "formattedMessage": "Service mock_a_service response time is more than 1000ms of last 10 minutes."
+ },
+ {
+ "scope": "SERVICE",
+ "name": "mock_c_service",
+ "formattedMessage": "Service mock_c_service response time is more than 1000ms of last 10 minutes."
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ }
+ ]
+}
+```
+
+- `additonalPeriod` is the additional period if the expression includes the [increase/rate function](../../../api/metrics-query-expression.md#trend-operation). This additional period is used to enlarge window size for calculating the trend value.
+- `runningEntities` is the entities that have metrics data and being calculated by the alarm rule.
+- `formattedMessages` is the result message according to the message template and the affected running entities.
-Lists registered alarm rules.
+#### `/status/alarm/{ruleId}/{entityName}`
-### `/status/alarm/{ruleId}`
+Return the running context of the alarm rule.
-Per-rule runtime status — current window state, last evaluation, the
-entities the rule has triggered against.
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "endTime": "2025-11-19T15:20:00.000",
+ "additionalPeriod": 0,
+ "size": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 0,
+ "silenceCountdown": 10,
+ "recoveryObservationCountdown": 0,
+ "currentState": "FIRING",
+ "entityName": "mock_b_service",
+ "windowValues": [
+ {
+ "index": 0,
+ "metrics": []
+ },
+ {
+ "index": 1,
+ "metrics": []
+ },
+ {
+ "index": 2,
+ "metrics": []
+ },
+ {
+ "index": 3,
+ "metrics": []
+ },
+ {
+ "index": 4,
+ "metrics": []
+ },
+ {
+ "index": 5,
+ "metrics": []
+ },
+ {
+ "index": 6,
+ "metrics": []
+ },
+ {
+ "index": 7,
+ "metrics": []
+ },
+ {
+ "index": 8,
+ "metrics": [
+ {
+ "name": "service_resp_time",
+ "timeBucket": 202511191519,
+ "value": "6000"
+ }
+ ]
+ },
+ {
+ "index": 9,
+ "metrics": []
+ }
+ ],
+ "mqeMetricsSnapshot": {
+ "service_resp_time": "[{\"metric\":{\"labels\":[]},\"values\":[{\"id\":\"202511191511\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191512\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191513\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191514\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191515\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191516\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191517\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191518\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191519\",\"doubleValue\":6000.0,\"isEmptyValue\":false},{\"id\":\"202511191520\",\"doubleValue\":0.0,\"isEmptyValue\":true}]}]"
+ },
+ "lastAlarmTime": "1763536823628",
Review Comment:
`lastAlarmTime` is a `long` in the status payload, but this example shows it as a JSON string. The second instance in the same example uses a numeric value (`0`), so this is inconsistent and may mislead clients about the field type.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Review Comment:
Endpoint headings are formatted inconsistently: some are wrapped in backticks (code style) while others are plain text. Consistent formatting makes the endpoint list easier to scan and avoids accidental Markdown rendering issues.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
Review Comment:
The cluster node list description has several grammatical issues (e.g., singular/plural mismatch, awkward phrasing) that make the documentation harder to understand.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
Review Comment:
The cluster node list description has several grammatical issues (e.g., singular/plural mismatch, awkward phrasing) that make the documentation harder to understand.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Review Comment:
Endpoint headings are formatted inconsistently: some are wrapped in backticks (code style) while others are plain text. Consistent formatting makes the endpoint list easier to scan and avoids accidental Markdown rendering issues.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
Review Comment:
The cluster node list description has several grammatical issues (e.g., singular/plural mismatch, awkward phrasing) that make the documentation harder to understand.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
+
+- HTTP GET method.
+
```bash
curl http://oap:17128/status/cluster/nodes
```
-### `/status/alarm/rules`
+```json
+{
+ "nodes": [
+ {
+ "host": "10.0.12.23",
+ "port": 11800,
+ "self": true
+ },
+ {
+ "host": "10.0.12.25",
+ "port": 11800,
+ "self": false
+ },
+ {
+ "host": "10.0.12.37",
+ "port": 11800,
+ "self": false
+ }
+ ]
+}
+```
+
+The `nodes` list all the nodes in the cluster. The size of the list should be exactly same as your cluster setup. The `host` and `port` are the address of the OAP node, which are used for OAP nodes communicating with each other. The `self` is a flag to indicate whether the node is the current node, others are remote nodes.
+
+### Alarm Runtime Status
+
+OAP calculates the alarm conditions in the memory based on the alarm rules and the metrics data. If the OAP cluster has multiple instances, each instance will calculate the alarm conditions independently. You can query from any OAP instance to get the all instances' alarm running status.
+
+The following APIs are exposed to make the alerting running kernel visible.
+
+#### /status/alarm/rules
+
+Return the list of alarm running rules.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ }
+ ]
+}
+```
+
+#### /status/alarm/rules/{ruleId}
+
+Return the detailed information of the alarm running rule.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_b_service",
+ "formattedMessage": "Service mock_b_service response time is more than 1000ms of last 10 minutes"
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_a_service",
+ "formattedMessage": "Service mock_a_service response time is more than 1000ms of last 10 minutes."
+ },
+ {
+ "scope": "SERVICE",
+ "name": "mock_c_service",
+ "formattedMessage": "Service mock_c_service response time is more than 1000ms of last 10 minutes."
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ }
+ ]
+}
+```
+
+- `additonalPeriod` is the additional period if the expression includes the [increase/rate function](../../../api/metrics-query-expression.md#trend-operation). This additional period is used to enlarge window size for calculating the trend value.
+- `runningEntities` is the entities that have metrics data and being calculated by the alarm rule.
+- `formattedMessages` is the result message according to the message template and the affected running entities.
Review Comment:
The field names in this explanation don’t match the JSON examples: `additionalPeriod` is misspelled as `additonalPeriod`, and the JSON uses `formattedMessage` (singular) rather than `formattedMessages`. This can confuse users who copy/paste field names.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
+
+- HTTP GET method.
+
```bash
curl http://oap:17128/status/cluster/nodes
```
-### `/status/alarm/rules`
+```json
+{
+ "nodes": [
+ {
+ "host": "10.0.12.23",
+ "port": 11800,
+ "self": true
+ },
+ {
+ "host": "10.0.12.25",
+ "port": 11800,
+ "self": false
+ },
+ {
+ "host": "10.0.12.37",
+ "port": 11800,
+ "self": false
+ }
+ ]
+}
+```
+
+The `nodes` list all the nodes in the cluster. The size of the list should be exactly same as your cluster setup. The `host` and `port` are the address of the OAP node, which are used for OAP nodes communicating with each other. The `self` is a flag to indicate whether the node is the current node, others are remote nodes.
+
+### Alarm Runtime Status
+
+OAP calculates the alarm conditions in the memory based on the alarm rules and the metrics data. If the OAP cluster has multiple instances, each instance will calculate the alarm conditions independently. You can query from any OAP instance to get the all instances' alarm running status.
+
+The following APIs are exposed to make the alerting running kernel visible.
+
+#### /status/alarm/rules
+
+Return the list of alarm running rules.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ }
+ ]
+}
+```
+
+#### /status/alarm/rules/{ruleId}
+
+Return the detailed information of the alarm running rule.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_b_service",
+ "formattedMessage": "Service mock_b_service response time is more than 1000ms of last 10 minutes"
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_a_service",
+ "formattedMessage": "Service mock_a_service response time is more than 1000ms of last 10 minutes."
+ },
+ {
+ "scope": "SERVICE",
+ "name": "mock_c_service",
+ "formattedMessage": "Service mock_c_service response time is more than 1000ms of last 10 minutes."
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ }
+ ]
+}
+```
+
+- `additonalPeriod` is the additional period if the expression includes the [increase/rate function](../../../api/metrics-query-expression.md#trend-operation). This additional period is used to enlarge window size for calculating the trend value.
+- `runningEntities` is the entities that have metrics data and being calculated by the alarm rule.
+- `formattedMessages` is the result message according to the message template and the affected running entities.
-Lists registered alarm rules.
+#### `/status/alarm/{ruleId}/{entityName}`
-### `/status/alarm/{ruleId}`
+Return the running context of the alarm rule.
-Per-rule runtime status — current window state, last evaluation, the
-entities the rule has triggered against.
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "endTime": "2025-11-19T15:20:00.000",
+ "additionalPeriod": 0,
+ "size": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 0,
+ "silenceCountdown": 10,
+ "recoveryObservationCountdown": 0,
+ "currentState": "FIRING",
+ "entityName": "mock_b_service",
+ "windowValues": [
+ {
+ "index": 0,
+ "metrics": []
+ },
+ {
+ "index": 1,
+ "metrics": []
+ },
+ {
+ "index": 2,
+ "metrics": []
+ },
+ {
+ "index": 3,
+ "metrics": []
+ },
+ {
+ "index": 4,
+ "metrics": []
+ },
+ {
+ "index": 5,
+ "metrics": []
+ },
+ {
+ "index": 6,
+ "metrics": []
+ },
+ {
+ "index": 7,
+ "metrics": []
+ },
+ {
+ "index": 8,
+ "metrics": [
+ {
+ "name": "service_resp_time",
+ "timeBucket": 202511191519,
+ "value": "6000"
+ }
+ ]
+ },
+ {
+ "index": 9,
+ "metrics": []
+ }
+ ],
+ "mqeMetricsSnapshot": {
+ "service_resp_time": "[{\"metric\":{\"labels\":[]},\"values\":[{\"id\":\"202511191511\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191512\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191513\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191514\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191515\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191516\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191517\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191518\",\"doubleValue\":0.0,\"isEmptyValue\":true},{\"id\":\"202511191519\",\"doubleValue\":6000.0,\"isEmptyValue\":false},{\"id\":\"202511191520\",\"doubleValue\":0.0,\"isEmptyValue\":true}]}]"
+ },
+ "lastAlarmTime": "1763536823628",
Review Comment:
`lastAlarmTime` is a `long` in the status payload, but this example shows it as a JSON string. The second instance in the same example uses a numeric value (`0`), so this is inconsistent and may mislead clients about the field type.
##########
docs/en/setup/backend/admin-api/status.md:
##########
@@ -36,36 +36,395 @@ to redact configuration values whose key contains any listed substring.
## Endpoints
-### `/status/cluster/nodes`
+### /status/cluster/nodes
Returns the OAP cluster peer list as the cluster module sees it. Useful
for confirming that every node has joined and is reporting back.
+The OAP cluster is a set of OAP servers that work together to provide a scalable and reliable service. The OAP cluster supports [various cluster coordinator](../backend-cluster.md) to manage the cluster membership and the communication. This API provides capability to query the node list in the cluster from every OAP node perspective. If the cluster coordinator doesn't work properly, the node list may be incomplete or incorrect. So, we recommend you to check the node list when set up a cluster.
+
+- HTTP GET method.
+
```bash
curl http://oap:17128/status/cluster/nodes
```
-### `/status/alarm/rules`
+```json
+{
+ "nodes": [
+ {
+ "host": "10.0.12.23",
+ "port": 11800,
+ "self": true
+ },
+ {
+ "host": "10.0.12.25",
+ "port": 11800,
+ "self": false
+ },
+ {
+ "host": "10.0.12.37",
+ "port": 11800,
+ "self": false
+ }
+ ]
+}
+```
+
+The `nodes` list all the nodes in the cluster. The size of the list should be exactly same as your cluster setup. The `host` and `port` are the address of the OAP node, which are used for OAP nodes communicating with each other. The `self` is a flag to indicate whether the node is the current node, others are remote nodes.
+
+### Alarm Runtime Status
+
+OAP calculates the alarm conditions in the memory based on the alarm rules and the metrics data. If the OAP cluster has multiple instances, each instance will calculate the alarm conditions independently. You can query from any OAP instance to get the all instances' alarm running status.
+
+The following APIs are exposed to make the alerting running kernel visible.
+
+#### /status/alarm/rules
+
+Return the list of alarm running rules.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleList": [
+ {
+ "id": "service_percentile_rule"
+ },
+ {
+ "id": "service_resp_time_rule"
+ }
+ ]
+ }
+ }
+ ]
+}
+```
+
+#### /status/alarm/rules/{ruleId}
+
+Return the detailed information of the alarm running rule.
+
+- HTTP GET method.
+
+```json
+{
+ "oapInstances": [
+ {
+ "address": "127.0.0.1_11800",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_b_service",
+ "formattedMessage": "Service mock_b_service response time is more than 1000ms of last 10 minutes"
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ },
+ {
+ "address": "127.0.0.1_11801",
+ "status": {
+ "ruleId": "service_resp_time_rule",
+ "expression": "sum(service_resp_time > 1000) >= 1",
+ "period": 10,
+ "silencePeriod": 10,
+ "recoveryObservationPeriod": 2,
+ "additionalPeriod": 0,
+ "includeEntityNames": [],
+ "excludeEntityNames": [],
+ "includeEntityNamesRegex": "",
+ "excludeEntityNamesRegex": "",
+ "runningEntities": [
+ {
+ "scope": "SERVICE",
+ "name": "mock_a_service",
+ "formattedMessage": "Service mock_a_service response time is more than 1000ms of last 10 minutes."
+ },
+ {
+ "scope": "SERVICE",
+ "name": "mock_c_service",
+ "formattedMessage": "Service mock_c_service response time is more than 1000ms of last 10 minutes."
+ }
+ ],
+ "tags": [
+ {
+ "key": "level",
+ "value": "WARNING"
+ }
+ ],
+ "hooks": [
+ "webhook.default",
+ "wechat.default"
+ ],
+ "includeMetrics": [
+ "service_resp_time"
+ ]
+ }
+ }
+ ]
+}
+```
+
+- `additonalPeriod` is the additional period if the expression includes the [increase/rate function](../../../api/metrics-query-expression.md#trend-operation). This additional period is used to enlarge window size for calculating the trend value.
+- `runningEntities` is the entities that have metrics data and being calculated by the alarm rule.
+- `formattedMessages` is the result message according to the message template and the affected running entities.
Review Comment:
The field names in this explanation don’t match the JSON examples: `additionalPeriod` is misspelled as `additonalPeriod`, and the JSON uses `formattedMessage` (singular) rather than `formattedMessages`. This can confuse users who copy/paste field names.
--
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
Re: [PR] add back status query example [skywalking]
Posted by "wu-sheng (via GitHub)" <gi...@apache.org>.
wu-sheng merged PR #13886:
URL: https://github.com/apache/skywalking/pull/13886
--
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