diff --git a/README.md b/README.md index 47b1eac4d6bff0482d690f061d8a1f601854c602..96208c91c37438e65f774241f5864463b21be178 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ This project adheres to the Contributor Covenant [code of conduct](CODE_OF_CONDU - [See all screenshots](/docs/Screenshots.md) # Compiling project -Follow this [document](https://github.com/apache/incubator-skywalking/blob/master/docs/en/How-to-build.md). +Follow this [document](docs/en/guides/How-to-build.md). # Contact Us * Submit an issue diff --git a/docs/en/setup/backend/Component-library-settings.md b/docs/en/guides/Component-library-settings.md similarity index 98% rename from docs/en/setup/backend/Component-library-settings.md rename to docs/en/guides/Component-library-settings.md index c90457675f9fa406e691a121d6e76d6db14ccf47..966771286d480a50970fb593672ee140c245c145 100644 --- a/docs/en/setup/backend/Component-library-settings.md +++ b/docs/en/guides/Component-library-settings.md @@ -27,6 +27,7 @@ This is a both-way mapping, agent or SDK could use the value(ID) to represent th - Node.js Platform reserved: (4000, 5000] - Go reserved: (5000, 6000] - PHP reserved: (6000, 7000] +- Python reserved: (7000, 8000] Example ```yaml diff --git a/docs/en/How-to-build.md b/docs/en/guides/How-to-build.md similarity index 100% rename from docs/en/How-to-build.md rename to docs/en/guides/How-to-build.md diff --git a/docs/en/guides/Java-Plugin-Development-Guide.md b/docs/en/guides/Java-Plugin-Development-Guide.md index 9d9cf4bb13ec23cc3077c1a6324b7214611533e4..37c14723fb4610254d6069fef2e4715c6086e93d 100644 --- a/docs/en/guides/Java-Plugin-Development-Guide.md +++ b/docs/en/guides/Java-Plugin-Development-Guide.md @@ -158,7 +158,7 @@ SpanLayer is the catalog of span. Here are 5 values: 1. MQ Component IDs are defined and reserved by SkyWalking project. -For component name/ID extension, please follow [component library setting document](../setup/backend/Component-library-settings.md). +For component name/ID extension, please follow [cComponent library definition and extension](Component-library-settings.md) document. ## Develop a plugin ### Abstract @@ -275,6 +275,7 @@ public interface InstanceMethodsAroundInterceptor { ``` Use the core APIs in before, after and exception handle stages. + ### Contribute plugins into Apache SkyWalking repository We are welcome everyone to contribute plugins. diff --git a/docs/en/guides/README.md b/docs/en/guides/README.md index b9e882f72395e3f515cf7e6eb7a8afe8c81fae71..a4c3c10e63a30df58505b2945bfad1ac6398ee3d 100644 --- a/docs/en/guides/README.md +++ b/docs/en/guides/README.md @@ -2,7 +2,7 @@ Guides help everyone developer, including PPMC member, committer and contributor, to understand the project structure. Also learn to build the project, even to release the official Apache version(If you have been accepted as the formal committer). -- [Compiling Guide](../How-to-build.md). Teaches developer how to build the project in local. +- [Compiling Guide](How-to-build.md). Teaches developer how to build the project in local. - [Apache Release Guide](How-to-release.md). Apache license allows everyone to redistribute if you keep our licenses and NOTICE in your redistribution. This document introduces to the committer team about doing official Apache version release, to avoid breaking any Apache rule. @@ -14,4 +14,15 @@ read the following guides. - [Java agent plugin development guide](Java-Plugin-Development-Guide.md). This guide helps you to develop SkyWalking agent plugin to support more frameworks. Both open source plugin and private plugin developer should read this. -- [Storage extension development guide](storage-extention.md) +- If you want to build a new probe or plugin in any language, please read [Component library definition and extension](Component-library-settings.md) document. +- [Storage extension development guide](storage-extention.md). Help potential contributors to build a new +storage implementor besides the official. + + +## UI developer +Our UI is constituted by static pages and web container. + +- **Static pages** is built based on [Ant Design Pro](https://pro.ant.design/), which source codes are +hosted in our [UI repository](https://github.com/apache/incubator-skywalking-ui). +- **Web container** source codes are in `apm-webapp` module. This is a just an easy zuul proxy to host +static resources and send GraphQL query requests to backend. diff --git a/docs/en/guides/backend-oal-scripts.md b/docs/en/guides/backend-oal-scripts.md new file mode 100644 index 0000000000000000000000000000000000000000..93eea9902f99edd2d9293804fd6ad87f7710ee95 --- /dev/null +++ b/docs/en/guides/backend-oal-scripts.md @@ -0,0 +1,16 @@ +# Official OAL script +First, read [OAL introduction](../concepts-and-designs/oal.md). + +Here is the official scrips is the `server-core-x.y.z.jar/official_analysis.oal` file in distribution, +also the `server-core` module's **src/main/resources/official_analysis.oal** in source code repository. + +**Notice**, this file doesn't effect anything in runtime, although included in distribution. +You need to use OAL tool code generator to build the real analysis codes from it. +All generated codes are under **org.apache.skywalking.oap.server.core.analysis.generated** package +in `server-core` module. + +All metrics named in this script could be used in alarm and UI query. Of course, you can change this +scripts and re-generate the analysis process and metric, such as adding filter condition. + +If you try to add or remove some metric, UI may break, we only recommend you to do this when you plan +to build your own UI based on the customization analysis core. \ No newline at end of file diff --git a/docs/en/setup/backend/backend-alarm.md b/docs/en/setup/backend/backend-alarm.md index 497e2565c38b3083bb3324ff94c712698662bcaf..2e5e6cf061bb4cfdd473d06a17caad498a320af3 100644 --- a/docs/en/setup/backend/backend-alarm.md +++ b/docs/en/setup/backend/backend-alarm.md @@ -1 +1,40 @@ -# Alarm \ No newline at end of file +# Alarm +Alarm core is driven a collection of rules, which are defined in `config/alarm-settings.yml`. +There are two parts in alarm rule definition. +1. Alarm rules. They define how metric alarm should be triggered, what conditions should be considered. +1. Webhooks. The list of web service endpoint, which should be called after the alarm is triggered. + +## Rules +Alarm rule is constituted by following keys +- **Rule name**. Unique name, show in alarm message. Must end with `_rule`. +- **Indicator name**。A.K.A. metric name in oal script. Only long, double, int types are supported. See +[List of all potential indicator](#list-of-all-potential-indicator-name). +- **Threshold**. The target value. +- **OP**. Operator, support `>`, `<`, `=`. Welcome to contribute all OPs. +- **Period**. How long should the alarm rule should be checked. This is a time window, which goes with the +backend deployment env time. +- **Count**. In the period window, if the number of **value**s over threshold(by OP), reaches count, alarm +should send. +- **Silence period**. After alarm is triggered in Time-N, then keep silence in the **TN -> TN + period**. +By default, it is as same as **Period**, which means in a period, same alarm(same ID in same +indicator name) will be trigger once. + + +```yaml +rules: + # Rule unique name, must be ended with `_rule`. + endpoint_percent_rule: + # Indicator value need to be long, double or int + indicator-name: endpoint_percent + threshold: 75 + op: < + # The length of time to evaluate the metric + period: 10 + # How many times after the metric match the condition, will trigger alarm + count: 3 + # How many times of checks, the alarm keeps silence after alarm triggered, default as same as period. + silence-period: 10 +``` + + +## List of all potential indicator name diff --git a/docs/en/setup/backend/backend-oal-scripts.md b/docs/en/setup/backend/backend-oal-scripts.md deleted file mode 100644 index 5945ee4da2dfecfa70a101e30f7397622f771d47..0000000000000000000000000000000000000000 --- a/docs/en/setup/backend/backend-oal-scripts.md +++ /dev/null @@ -1 +0,0 @@ -# Official OAL scripts \ No newline at end of file diff --git a/docs/en/setup/backend/backend-receivers.md b/docs/en/setup/backend/backend-receivers.md index 056a2559efa992119085c6f0e2d1ed3f61ff6906..8e776e88ad49e3963cfe278d04bc83d2f136ba64 100644 --- a/docs/en/setup/backend/backend-receivers.md +++ b/docs/en/setup/backend/backend-receivers.md @@ -4,5 +4,8 @@ or tracing data from other being monitored system, are all being called **Receiv receivers are using gRPC or HTTPRestful to provide service, actually, whether listening mode or pull mode could be receiver. Such as a receiver could base on pull data from remote, like Kakfa MQ. -We have following receivers -1. \ No newline at end of file +We have following receivers, and `default` implementors are provided in our Apache distribution.zzz +1. **receiver-register**. gRPC and HTTPRestful services to provide service, service instance and endpoint register. +1. **service-mesh**. gRPC services accept data from inbound mesh probes. +1. **istio-telemetry**. Istio telemetry is from Istio official bypass adaptor, this receiver match its gRPC services. +1. **receiver-jvm**. gRPC services accept JVM metric data. diff --git a/docs/en/setup/backend/backend-setup.md b/docs/en/setup/backend/backend-setup.md index 429cadd7af4e95177723388b5306f13e706f9216..50fa38706669aee034127da6e834f7fa9f575df8 100644 --- a/docs/en/setup/backend/backend-setup.md +++ b/docs/en/setup/backend/backend-setup.md @@ -57,7 +57,7 @@ DB. But clearly, it doesn't fit the product env. In here, you could find what ot Choose the one you like, we are also welcome anyone to contribute new storage implementor, 1. [Set receivers](backend-receivers.md). You could choose receivers by your requirements, most receivers are harmless, at least our default receivers are. You would set and active all receivers provided. -1. Official [OAL scripts](backend-oal-scripts.md). As you known from our [OAL introduction](../../concepts-and-designs/oal.md), +1. Official [OAL scripts](../../guides/backend-oal-scripts.md). As you known from our [OAL introduction](../../concepts-and-designs/oal.md), most of backend analysis capabilities based on the scripts. Here is the description of official scripts, which helps you to understand which metric data are in process, also could be used in alarm. 1. [Alarm](backend-alarm.md). Alarm provides a time-series based check mechanism. You could set alarm diff --git a/docs/en/setup/backend/ui-setup.md b/docs/en/setup/backend/ui-setup.md index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..ae0438b9384b7b4bdc4847d93e7d0d47f8196ba0 100644 --- a/docs/en/setup/backend/ui-setup.md +++ b/docs/en/setup/backend/ui-setup.md @@ -0,0 +1,13 @@ +# UI +SkyWalking UI distribution is already included in our Apache official release. + +## Startup +Startup script is also in `/bin/webappService.sh`(.bat). UI runs as an OS Java process, powered-by Zuul. + +## Settings +Setting file of UI is `webapp/webapp.yml` in distribution package. It is constituted by three parts. + +1. Listening port. +1. Backend connect info. +1. Auth setting. + diff --git a/oap-server/server-core/src/main/resources/oal_ui.oal b/oap-server/server-core/src/main/resources/official_analysis.oal similarity index 100% rename from oap-server/server-core/src/main/resources/oal_ui.oal rename to oap-server/server-core/src/main/resources/official_analysis.oal