From 00ffdf77da2b272ff65963bfa79d669f2d90feee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=90=B4=E6=99=9F=20Wu=20Sheng?= Date: Tue, 30 Nov 2021 21:06:47 +0800 Subject: [PATCH] Add a guidance doc about the logic endpoint (#8216) --- 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 b8aa70dbf0..674ebf5b1e 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 5698422d4d..811addce92 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/). + -- GitLab