[skywalking] 01/01: Add a guidance doc about the logic endpoint

[wu...@apache.org]

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

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

commit 1876fea52ce654e561c5102f522ee5e3008383be
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Tue Nov 30 21:00:08 2021 +0800

    Add a guidance doc about the logic endpoint
---
 CHANGES.md                            |  1 +
 docs/en/guides/backend-oal-scripts.md | 32 ++++++++++++++++++++++++++++++--
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index b8aa70d..674ebf5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -88,6 +88,7 @@ Release Notes.
 * Restructure documents about receivers and fetchers.
     1. Remove general receiver and fetcher docs
     2. Add more specific menu with docs to help users to find documents easier.
+* Add a guidance doc about the logic endpoint. 
 
 All issues and pull requests are [here](https://github.com/apache/skywalking/milestone/101?closed=1)
 
diff --git a/docs/en/guides/backend-oal-scripts.md b/docs/en/guides/backend-oal-scripts.md
index 5698422..811addc 100644
--- a/docs/en/guides/backend-oal-scripts.md
+++ b/docs/en/guides/backend-oal-scripts.md
@@ -1,7 +1,35 @@
 # Official OAL script
-First, read the [OAL introduction](../concepts-and-designs/oal.md).
+First, read the [OAL introduction](../concepts-and-designs/oal.md) to learn the OAL script grammar and the source concept.
 
 From 8.0.0, you may find the OAL script at `/config/oal/*.oal` of the SkyWalking dist.
 You could change it, such as by adding filter conditions or new metrics. Then, reboot the OAP server, and it will come into effect.
 
-All metrics named in this script may be used in alarm and UI query.
+All metrics named in this script could be used in alarm and UI query.
+
+# Extension
+
+## Logic Endpoint
+In default, SkyWalking only treats the operation name of entry span as the endpoint, which are used in the OAL engine.
+Users could declare their custom endpoint names by adding the `logic endpoint` tag manually through agent's plugins or manual APIs.
+
+The logic endpoint is a concept that doesn't represent a real RPC call, but requires the statistic.
+The value of `x-le` should be in JSON format. There are two options:
+1. Define a new logic endpoint in the entry span as a separate new endpoint. Provide its own endpoint name, latency and status. Suitable for entry and local span.
+```json
+{
+  "name": "GraphQL-service",
+  "latency": 100,
+  "status": true
+}
+```
+2. Declare the current local span representing a logic endpoint.
+```json
+{
+  "logic-span": true
+}
+``` 
+
+### References
+1. [Java plugin API](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/java-plugin-development-guide/#extension-logic-endpoint-tag-key-x-le) guides users to write plugins with logic endpoint.
+2. Java agent's plugins include native included logic endpoints, also it provides ways to set the tag of logic span. The document could be found [here](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/logic-endpoint/).
+