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 2021/08/21 06:00:38 UTC
[skywalking] branch master updated: Refine backend doc (#1) (#7522)
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking.git
The following commit(s) were added to refs/heads/master by this push:
new 8f7d16a Refine backend doc (#1) (#7522)
8f7d16a is described below
commit 8f7d16a18eb23bb1b3b90208cf137572620c48b0
Author: Wing <69...@users.noreply.github.com>
AuthorDate: Fri Aug 20 23:00:26 2021 -0700
Refine backend doc (#1) (#7522)
* Refine dynamic-config.md
* Refine dynamical-logging.md
* Refine endpoint-grouping-rules.md
---
docs/en/setup/backend/dynamic-config.md | 42 +++++++--------
docs/en/setup/backend/dynamical-logging.md | 24 ++++-----
docs/en/setup/backend/endpoint-grouping-rules.md | 68 ++++++++++++------------
3 files changed, 67 insertions(+), 67 deletions(-)
diff --git a/docs/en/setup/backend/dynamic-config.md b/docs/en/setup/backend/dynamic-config.md
index eab8442..3e7e073 100755
--- a/docs/en/setup/backend/dynamic-config.md
+++ b/docs/en/setup/backend/dynamic-config.md
@@ -1,20 +1,20 @@
# Dynamic Configuration
-SkyWalking Configurations mostly are set through `application.yml` and OS system environment variables.
-At the same time, some of them are supporting dynamic settings from upstream management system.
+SkyWalking Configurations are mostly set through `application.yml` and OS system environment variables.
+At the same time, some of them support dynamic settings from upstream management system.
-Right now, SkyWalking supports following dynamic configurations.
+Currently, SkyWalking supports the following dynamic configurations.
| Config Key | Value Description | Value Format Example |
|:----:|:----:|:----:|
-|agent-analyzer.default.slowDBAccessThreshold| Thresholds of slow Database statement, override `receiver-trace/default/slowDBAccessThreshold` of `application.yml`. | default:200,mongodb:50|
-|agent-analyzer.default.uninstrumentedGateways| The uninstrumented gateways, override `gateways.yml`. | same as [`gateways.yml`](uninstrumented-gateways.md#configuration-format) |
-|alarm.default.alarm-settings| The alarm settings, will override `alarm-settings.yml`. | same as [`alarm-settings.yml`](backend-alarm.md) |
-|core.default.apdexThreshold| The apdex threshold settings, will override `service-apdex-threshold.yml`. | same as [`service-apdex-threshold.yml`](apdex-threshold.md) |
-|core.default.endpoint-name-grouping| The endpoint name grouping setting, will override `endpoint-name-grouping.yml`. | same as [`endpoint-name-grouping.yml`](endpoint-grouping-rules.md) |
-|core.default.log4j-xml| The log4j xml configuration, will override `log4j2.xml`. | same as [`log4j2.xml`](dynamical-logging.md) |
-|agent-analyzer.default.sampleRate| Trace sampling , override `receiver-trace/default/sampleRate` of `application.yml`. | 10000 |
-|agent-analyzer.default.slowTraceSegmentThreshold| Setting this threshold about the latency would make the slow trace segments sampled if they cost more time, even the sampling mechanism activated. The default value is `-1`, which means would not sample slow traces. Unit, millisecond. override `receiver-trace/default/slowTraceSegmentThreshold` of `application.yml`. | -1 |
-|configuration-discovery.default.agentConfigurations| The ConfigurationDiscovery settings | look at [`configuration-discovery.md`](../service-agent/java-agent/configuration-discovery.md) |
+|agent-analyzer.default.slowDBAccessThreshold| Thresholds of slow Database statement. Overrides `receiver-trace/default/slowDBAccessThreshold` of `application.yml`. | default:200,mongodb:50|
+|agent-analyzer.default.uninstrumentedGateways| The uninstrumented gateways. Overrides `gateways.yml`. | Same as [`gateways.yml`](uninstrumented-gateways.md#configuration-format). |
+|alarm.default.alarm-settings| The alarm settings. Overrides `alarm-settings.yml`. | Same as [`alarm-settings.yml`](backend-alarm.md). |
+|core.default.apdexThreshold| The apdex threshold settings. Overrides `service-apdex-threshold.yml`. | Same as [`service-apdex-threshold.yml`](apdex-threshold.md). |
+|core.default.endpoint-name-grouping| The endpoint name grouping setting. Overrides `endpoint-name-grouping.yml`. | Same as [`endpoint-name-grouping.yml`](endpoint-grouping-rules.md). |
+|core.default.log4j-xml| The log4j xml configuration. Overrides `log4j2.xml`. | Same as [`log4j2.xml`](dynamical-logging.md). |
+|agent-analyzer.default.sampleRate| Trace sampling. Overrides `receiver-trace/default/sampleRate` of `application.yml`. | 10000 |
+|agent-analyzer.default.slowTraceSegmentThreshold| Setting this threshold on latency (in milliseconds) would cause slow trace segments to be sampled if they use up more time, even if the sampling mechanism is activated. The default value is `-1`, which means slow traces will not be sampled. Overrides `receiver-trace/default/slowTraceSegmentThreshold` of `application.yml`. | -1 |
+|configuration-discovery.default.agentConfigurations| The ConfigurationDiscovery settings. | See [`configuration-discovery.md`](../service-agent/java-agent/configuration-discovery.md). |
This feature depends on upstream service, so it is **DISABLED** by default.
@@ -32,8 +32,8 @@ configuration:
## Dynamic Configuration Service, DCS
[Dynamic Configuration Service](../../../../oap-server/server-configuration/grpc-configuration-sync/src/main/proto/configuration-service.proto)
-is a gRPC service, which requires the upstream system implemented.
-The SkyWalking OAP fetches the configuration from the implementation(any system), after you open this implementation like this.
+is a gRPC service which requires implementation of the upstream system.
+The SkyWalking OAP fetches the configuration from the implementation (any system), after you open the implementation like this:
```yaml
configuration:
@@ -46,7 +46,7 @@ configuration:
```
## Dynamic Configuration Zookeeper Implementation
-[Zookeeper](https://github.com/apache/zookeeper) is also supported as DCC(Dynamic Configuration Center), to use it, please configure as follows:
+[Zookeeper](https://github.com/apache/zookeeper) is also supported as Dynamic Configuration Center (DCC). To use it, please configure as follows:
```yaml
configuration:
@@ -64,7 +64,7 @@ The **nameSpace** is the ZooKeeper path. The config key and value are the proper
## Dynamic Configuration Etcd Implementation
-[Etcd](https://github.com/etcd-io/etcd) is also supported as DCC(Dynamic Configuration Center), to use it, please configure as follows:
+[Etcd](https://github.com/etcd-io/etcd) is also supported as Dynamic Configuration Center (DCC). To use it, please configure as follows:
```yaml
configuration:
@@ -78,11 +78,11 @@ configuration:
password: ${SW_CONFIG_ETCD_password:}
```
-**NOTICE**, only the v3 protocol is supported since 8.7.0.
+**NOTE**: Only the v3 protocol is supported since 8.7.0.
## Dynamic Configuration Consul Implementation
-[Consul](https://github.com/rickfast/consul-client) is also supported as DCC(Dynamic Configuration Center), to use it, please configure as follows:
+[Consul](https://github.com/rickfast/consul-client) is also supported as Dynamic Configuration Center (DCC). To use it, please configure as follows:
```yaml
configuration:
@@ -98,7 +98,7 @@ configuration:
## Dynamic Configuration Apollo Implementation
-[Apollo](https://github.com/ctripcorp/apollo/) is also supported as DCC(Dynamic Configuration Center), to use it, just configured as follows:
+[Apollo](https://github.com/ctripcorp/apollo/) is also supported as Dynamic Configuration Center (DCC). To use it, please configure as follows:
```yaml
configuration:
@@ -113,7 +113,7 @@ configuration:
## Dynamic Configuration Kuberbetes Configmap Implementation
-[configmap](https://kubernetes.io/docs/concepts/configuration/configmap/) is also supported as DCC(Dynamic Configuration Center), to use it, just configured as follows:
+[configmap](https://kubernetes.io/docs/concepts/configuration/configmap/) is also supported as Dynamic Configuration Center (DCC). To use it, please configure as follows:
```yaml
configuration:
@@ -129,7 +129,7 @@ configuration:
```
## Dynamic Configuration Nacos Implementation
-[Nacos](https://github.com/alibaba/nacos) is also supported as DCC(Dynamic Configuration Center), to use it, please configure as follows:
+[Nacos](https://github.com/alibaba/nacos) is also supported as Dynamic Configuration Center (DCC). To use it, please configure as follows:
```yaml
configuration:
diff --git a/docs/en/setup/backend/dynamical-logging.md b/docs/en/setup/backend/dynamical-logging.md
index d143167..50766a2 100644
--- a/docs/en/setup/backend/dynamical-logging.md
+++ b/docs/en/setup/backend/dynamical-logging.md
@@ -1,26 +1,24 @@
# Dynamical Logging
-OAP server leverage the log4j2 to manage the logging system. The log4j2 supports changing the configuration
-at the runtime, but you have to update the XML configuration file manually, which could waste you much time and
-easy to make mistakes.
+The OAP server leverages `log4j2` to manage the logging system. `log4j2` supports changing the configuration
+at runtime, but you have to update the XML configuration file manually, which could be time-consuming and prone to manmade mistakes.
-The dynamical logging, which depends on the dynamic configuration, provides us an agile way to update all OAP log4j
+Dynamical logging, which depends on dynamic configuration, provides us with an agile way to update all OAP `log4j`
configurations through a single operation.
-The key of the configuration item is `core.default.log4j-xml`, and you can select any one of the configuration implements
-to store the content of log4j.xml. In the booting phase, once the core module gets started, the `core.default.log4j-xml`
+The key of the configuration item is `core.default.log4j-xml`, and you can select any of the configuration implements
+to store the content of `log4j.xml`. In the booting phase, once the core module gets started, `core.default.log4j-xml`
would come into the OAP log4j context.
-Supposing changing the configuration after OAP started, you have to wait a while to get the changes applied.
-The default value is `60` seconds which you could change through `configuration.<configuration implement>.peroid` in application.yaml.
+If the configuration is changed after the OAP has started, you have to wait for a while for the changes to be applied.
+The default value is `60` seconds, which you could change through `configuration.<configuration implement>.peroid` in `application.yaml`.
-If you remove `core.default.log4j-xml` from the configuration center or disable the configuration module, the `log4j.xml`
-laid in `config` directory would get the effect.
+If you remove `core.default.log4j-xml` from the configuration center or disable the configuration module, `log4j.xml` in the `config` directory would be affected.
-> Caveat: OAP only supports XML configuration format.
+> Caveat: The OAP only supports the XML configuration format.
-There is an example to show how to config dynamical logging through a ConfigMap in a Kubernetes cluster. Other configuration
-clusters could follow the same convention to set up.
+This is an example on how to config dynamical logging through a ConfigMap in a Kubernetes cluster. You may set up other configuration
+clusters following the same procedures.
```yaml
apiVersion: v1
diff --git a/docs/en/setup/backend/endpoint-grouping-rules.md b/docs/en/setup/backend/endpoint-grouping-rules.md
index e4eda52..f79be96 100644
--- a/docs/en/setup/backend/endpoint-grouping-rules.md
+++ b/docs/en/setup/backend/endpoint-grouping-rules.md
@@ -1,33 +1,35 @@
# Group Parameterized Endpoints
-In most cases, the endpoint should be detected automatically through the language agents, service mesh observability solution,
-or configuration of meter system.
+In most cases, endpoints are detected automatically through language agents, service mesh observability solutions,
+or meter system configurations.
-There are some special cases, especially when people use REST style URI, the application codes put the parameter in the endpoint name,
-such as putting order id in the URI, like `/prod/ORDER123` and `/prod/ORDER123`. But logically, people expect they could
-have an endpoint name like `prod/{order-id}`. This is the feature of parameterized endpoint grouping designed for.
+There are some special cases, especially when REST style URI is used, where the application codes include the parameter in the endpoint name,
+such as putting order ID in the URI. Examples are `/prod/ORDER123` and `/prod/ORDER123`. But logically, most would expect to
+have an endpoint name like `prod/{order-id}`. This is a specially designed feature in parameterized endpoint grouping.
-If the incoming endpoint name hit the rules, SkyWalking will grouping the endpoint by rules.
+If the incoming endpoint name accords with the rules, SkyWalking will group the endpoint by rules.
-SkyWalking provides 2 ways to support endpoint grouping:
+There are two approaches in which SkyWalking supports endpoint grouping:
1. Endpoint name grouping by OpenAPI definitions.
-2. Endpoint name grouping by custom configuration.
+2. Endpoint name grouping by custom configurations.
+
+Both grouping approaches can work together in sequence.
-The 2 grouping features can work together in sequence.
## Endpoint name grouping by OpenAPI definitions
-The OpenAPI definitions are the documents based on The [OpenAPI Specification (OAS)](https://www.openapis.org/) which used to define a standard, language-agnostic interface for HTTP APIs.
-SkyWalking now support `OAS v2.0+`, could parse the documents `(yaml)` and build the grouping rules from them automatically.
+The OpenAPI definitions are documents based on the [OpenAPI Specification (OAS)](https://www.openapis.org/), which is used to define a standard, language-agnostic interface for HTTP APIs.
+
+SkyWalking now supports `OAS v2.0+`. It could parse the documents `(yaml)` and build grouping rules from them automatically.
### How to use
-1. Add some `Specification Extensions` for SkyWalking config in the OpenAPI definition documents, otherwise, all configs are default:<br />
- `${METHOD}` is a reserved placeholder which represents the HTTP method eg. `POST/GET...` <br />
- `${PATH}` is a reserved placeholder which represents the path eg. `/products/{id}`.
+1. Add `Specification Extensions` for SkyWalking config in the OpenAPI definition documents; otherwise, all configs are default:<br />
+ `${METHOD}` is a reserved placeholder which represents the HTTP method, e.g. `POST/GET...` <br />.
+ `${PATH}` is a reserved placeholder which represents the path, e.g. `/products/{id}`.
| Extension Name | Required | Description | Default Value |
|-----|-----|-----|-----|
- | x-sw-service-name | false | The service name which these endpoints belong to | The directory name which the OpenAPI definition documents belong to |
- | x-sw-endpoint-name-match-rule | false | The rule used to match the endpoint.| `${METHOD}:${PATH}` |
- | x-sw-endpoint-name-format | false | The endpoint name after grouping.| `${METHOD}:${PATH}` |
+ | x-sw-service-name | false | The service name to which these endpoints belong. | The directory name to which the OpenAPI definition documents belong. |
+ | x-sw-endpoint-name-match-rule | false | The rule used to match the endpoint. | `${METHOD}:${PATH}` |
+ | x-sw-endpoint-name-format | false | The endpoint name after grouping. | `${METHOD}:${PATH}` |
These extensions are under `OpenAPI Object`. For example, the document below has a full custom config:
@@ -44,10 +46,10 @@ info:
...
```
- We highly recommend using the default config, the custom config (`x-sw-endpoint-name-match-rule/x-sw-endpoint-name-format`) would be considered as part of the match rules (regex pattern).
- We provide some cases in `org.apache.skywalking.oap.server.core.config.group.openapi.EndpointGroupingRuleReader4OpenapiTest`, you could validate your custom config as well.
+ We highly recommend using the default config. The custom config (`x-sw-endpoint-name-match-rule/x-sw-endpoint-name-format`) is considered part of the match rules (regex pattern).
+ We have provided some use cases in `org.apache.skywalking.oap.server.core.config.group.openapi.EndpointGroupingRuleReader4OpenapiTest`. You may validate your custom config as well.
-2. All OpenAPI definition documents should be located in the `openapi-definitions` directory, with at most two levels directories. Recommend using the service name as the subDirectory name then you are not required to set `x-sw-service-name`. For example:
+2. All OpenAPI definition documents are located in the `openapi-definitions` directory, with directories having at most two levels. We recommend using the service name as the subDirectory name, as you will then not be required to set `x-sw-service-name`. For example:
```
├── openapi-definitions
│ ├── serviceA
@@ -56,18 +58,18 @@ info:
│ └── serviceB
│ └── productAPI-v2.yaml
```
-3. The feature is enabled by default, you can disable it by setting the `Core Module` configuration `${SW_CORE_ENABLE_ENDPOINT_NAME_GROUPING_BY_OPAENAPI:false}`
+3. The feature is enabled by default. You can disable it by setting the `Core Module` configuration `${SW_CORE_ENABLE_ENDPOINT_NAME_GROUPING_BY_OPAENAPI:false}`.
### Rules match priority
-We recommend designing the API path as clear as possible. If the API path is fuzzy and an endpoint name might match multiple paths, SkyWalking would follow the match priority to select one as below orders:
-1. The exact path matched first.
- Eg. `/products or /products/inventory`
-2. The path which has the less variables.
- Eg. `/products/{var1}/{var2} and /products/{var1}/abc`, endpoint name `/products/123/abc` will match the second one.
-3. If the paths have the same number of variables, match the longest path, and the vars are considered to be `1`.
- Eg. `/products/abc/{var1} and products/{var12345}/ef`, endpoint name `/products/abc/ef` will match the first one, because `length("abc") = 3` is larger than `length("ef") = 2`.
+We recommend designing the API path as clearly as possible. If the API path is fuzzy and an endpoint name matches multiple paths, SkyWalking would select a path according to the match priority set out below:
+1. The exact path being matched.
+ E.g. `/products or /products/inventory`
+2. The path which has less variables.
+ E.g. In the case of `/products/{var1}/{var2} and /products/{var1}/abc`, endpoint name `/products/123/abc` will match the second one.
+3. If the paths have the same number of variables, the longest path is matched, and the vars are considered to be `1`.
+ E.g. In the case of `/products/abc/{var1} and products/{var12345}/ef`, endpoint name `/products/abc/ef` will match the first one, because `length("abc") = 3` is larger than `length("ef") = 2`.
### Examples
-If we have an OpenAPI definition doc `productAPI-v2.yaml` in directory `serviceB` like this:
+If we have an OpenAPI definition doc `productAPI-v2.yaml` in directory `serviceB`, it will look like this:
```yaml
openapi: 3.0.0
@@ -268,7 +270,7 @@ components:
```
-Here are some cases:
+Here are some use cases:
| Incoming Endpiont | Incoming Service | x-sw-service-name | x-sw-endpoint-name-match-rule | x-sw-endpoint-name-format | Matched | Grouping Result |
|-----|-----|-----|-----|-----|-----|-----|
@@ -285,11 +287,11 @@ Here are some cases:
## Endpoint name grouping by custom configuration
-Current, user could set up grouping rules through the static YAML file, named `endpoint-name-grouping.yml`,
-or use [Dynamic Configuration](dynamic-config.md) to initial and update the endpoint grouping rule.
+Currently, a user could set up grouping rules through the static YAML file named `endpoint-name-grouping.yml`,
+or use [Dynamic Configuration](dynamic-config.md) to initialize and update endpoint grouping rules.
### Configuration Format
-No matter in static local file or dynamic configuration value, they are sharing the same YAML format.
+Both the static local file and dynamic configuration value share the same YAML format.
```yaml
grouping: