You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@skywalking.apache.org by wu...@apache.org on 2018/09/03 07:46:14 UTC
[incubator-skywalking] branch 6.0 updated: Add more ducoments.
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch 6.0
in repository https://gitbox.apache.org/repos/asf/incubator-skywalking.git
The following commit(s) were added to refs/heads/6.0 by this push:
new f281180 Add more ducoments.
f281180 is described below
commit f2811800b2549ea08410782262f2fb17bc6ef37a
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Mon Sep 3 15:46:04 2018 +0800
Add more ducoments.
---
README.md | 2 +-
.../Component-library-settings.md | 1 +
docs/en/{ => guides}/How-to-build.md | 0
docs/en/guides/Java-Plugin-Development-Guide.md | 3 +-
docs/en/guides/README.md | 15 ++++++--
docs/en/guides/backend-oal-scripts.md | 16 +++++++++
docs/en/setup/backend/backend-alarm.md | 41 +++++++++++++++++++++-
docs/en/setup/backend/backend-oal-scripts.md | 1 -
docs/en/setup/backend/backend-receivers.md | 7 ++--
docs/en/setup/backend/backend-setup.md | 2 +-
docs/en/setup/backend/ui-setup.md | 13 +++++++
.../{oal_ui.oal => official_analysis.oal} | 0
12 files changed, 92 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index 47b1eac..96208c9 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 c904576..9667712 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 9d9cf4b..37c1472 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 b9e882f..a4c3c10 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 0000000..93eea99
--- /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 497e256..2e5e6cf 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 5945ee4..0000000
--- 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 056a255..8e776e8 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 429cadd..50fa387 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 e69de29..ae0438b 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