You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2024/12/12 06:32:23 UTC

(skywalking) 01/01: Add Status APIs docs.

This is an automated email from the ASF dual-hosted git repository.

wusheng pushed a commit to branch status-api-doc
in repository https://gitbox.apache.org/repos/asf/skywalking.git

commit dc71b73cb7575a8f2a3a2bf886c624b4f1528906
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Thu Dec 12 14:32:12 2024 +0800

    Add Status APIs docs.
---
 docs/en/changes/changes.md       |  1 +
 docs/en/debugging/config_dump.md | 12 +-----------
 docs/en/status/status_apis.md    | 32 ++++++++++++++++++++++++++++++++
 docs/menu.yml                    |  2 ++
 4 files changed, 36 insertions(+), 11 deletions(-)

diff --git a/docs/en/changes/changes.md b/docs/en/changes/changes.md
index d83c74f369..7666e96950 100644
--- a/docs/en/changes/changes.md
+++ b/docs/en/changes/changes.md
@@ -64,5 +64,6 @@
 * Improve component-libraries documentation.
 * Improve configuration-vocabulary documentation.
 * Add `Get Effective TTL Configurations` API documentation.
+* Add Status APIs docs.
 
 All issues and pull requests are [here](https://github.com/apache/skywalking/milestone/224?closed=1)
diff --git a/docs/en/debugging/config_dump.md b/docs/en/debugging/config_dump.md
index 51ffdad918..128640487c 100644
--- a/docs/en/debugging/config_dump.md
+++ b/docs/en/debugging/config_dump.md
@@ -62,14 +62,4 @@ By default, we mask the config keys through the following configurations.
 ```yaml
 # Include the list of keywords to filter configurations including secrets. Separate keywords by a comma.
 keywords4MaskingSecretsOfConfig: ${SW_DEBUGGING_QUERY_KEYWORDS_FOR_MASKING_SECRETS:user,password,token,accessKey,secretKey,authentication}
-```
-
-## Disable The Config Dump Service
-
-By default, this service is open for helping users to debug and diagnose. If you want to disable it, you need to diable the whole
-`debugging-query` module through setting `selector=-`.
-
-```yaml
-debugging-query:
-  selector: ${SW_DEBUGGING_QUERY:-}
-```
+```
\ No newline at end of file
diff --git a/docs/en/status/status_apis.md b/docs/en/status/status_apis.md
new file mode 100644
index 0000000000..fb0748a565
--- /dev/null
+++ b/docs/en/status/status_apis.md
@@ -0,0 +1,32 @@
+# Status APIs
+
+Status APIs are a set of APIs that allow you to get the status of the OAP status and measurements of queries.
+They are useful for monitoring the health of the OAP server and to diagnose and troubleshoot issues caused by
+configurations and performance bottlenecks.
+
+Since v10, we begin to add status APIs to help users to understand the status of the OAP server, besides looking the raw
+logs and self-observability solutions.
+
+- [Dump Effective Initial Configurations API](../debugging/config_dump.md)
+- [Tracing Query Execution APIs](../debugging/query-tracing.md)
+- [Get Effective TTL Configurations API](query_ttl_setup.md)
+
+If you have a proposal about new status API, please don't hesitate
+to [create a discussion](https://github.com/apache/skywalking/discussions/new?category=ideas).
+The basic principles for a status API are
+
+1. It should be useful for users to understand the status of the OAP server or the reason of the performance behavior,
+   rather than a function feature.
+2. It should be on-demand and not impact the performance of the OAP server too much, especially in the production
+   environment.
+3. HTTP APIs are preferred unless there is a special reason to use other.
+
+## Disable Status APIs
+
+By default, this service is open for helping users to debug and diagnose. If you want to disable it, you need to disable
+the whole `status-query` module through setting `selector=-`.
+
+```yaml
+status-query:
+  selector: ${SW_STATUS_QUERY:default}
+```
diff --git a/docs/menu.yml b/docs/menu.yml
index c97281b0e1..cbd6f8f994 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -336,6 +336,8 @@ catalog:
             path: "/en/api/health-check"
           - name: "Status APIs"
             catalog:
+              - name: "Introduction"
+                path: "/en/status/status_apis"
               - name: "Dump Effective Initial Configurations"
                 path: "/en/debugging/config_dump"
               - name: "Tracing Query Execution"