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/09/01 06:46:01 UTC
[skywalking] branch master updated: refine backend doc (#7629)
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 29c3804 refine backend doc (#7629)
29c3804 is described below
commit 29c38043915a92fe6e8da214e443fd711e4ca69f
Author: Wing <69...@users.noreply.github.com>
AuthorDate: Tue Aug 31 23:45:49 2021 -0700
refine backend doc (#7629)
---
docs/en/setup/envoy/als_setting.md | 51 ++++++++++++--------------
docs/en/setup/envoy/examples/metrics/README.md | 6 +--
docs/en/setup/envoy/metrics_service_setting.md | 34 ++++++++---------
3 files changed, 43 insertions(+), 48 deletions(-)
diff --git a/docs/en/setup/envoy/als_setting.md b/docs/en/setup/envoy/als_setting.md
index c23298b..93ff4ed 100644
--- a/docs/en/setup/envoy/als_setting.md
+++ b/docs/en/setup/envoy/als_setting.md
@@ -1,22 +1,22 @@
# Observe Service Mesh through ALS
[Envoy Access Log Service (ALS)](https://www.envoyproxy.io/docs/envoy/v1.18.2/api-v2/service/accesslog/v2/als.proto) provides
-full logs about RPC routed, including HTTP and TCP.
+full logs on routed RPC, including HTTP and TCP.
## Background
-The solution was initialized and firstly implemented by [Sheng Wu](https://github.com/wu-sheng), [Hongtao Gao](https://github.com/hanahmily), [Lizan Zhou](https://github.com/lizan),
-and [Dhi Aurrahman](https://github.com/dio) at 17 May. 2019, and was presented on [KubeCon China 2019](https://kccncosschn19eng.sched.com/event/NroB/observability-in-service-mesh-powered-by-envoy-and-apache-skywalking-sheng-wu-lizan-zhou-tetrate).
-Here is the recorded [video](https://www.youtube.com/watch?v=tERm39ju9ew).
+The solution was initialized and first implemented by [Sheng Wu](https://github.com/wu-sheng), [Hongtao Gao](https://github.com/hanahmily), [Lizan Zhou](https://github.com/lizan),
+and [Dhi Aurrahman](https://github.com/dio) on May 17, 2019, and was presented at [KubeCon China 2019](https://kccncosschn19eng.sched.com/event/NroB/observability-in-service-mesh-powered-by-envoy-and-apache-skywalking-sheng-wu-lizan-zhou-tetrate).
+Here is a [video recording of the presentation](https://www.youtube.com/watch?v=tERm39ju9ew).
-SkyWalking is the first open source project introducing this ALS based solution to the world. This provides a new way with very low payload to service mesh, but the same observability.
+SkyWalking is the first open source project that introduced an ALS-based solution to the world. This solution provides a new take on observability with a lightweight payload on the service mesh.
## Enable ALS and SkyWalking Receiver
You need the following steps to set up ALS.
-- Enable [`envoyAccessLogService` in ProxyConfig](https://istio.io/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig) and set the ALS address to where SkyWalking OAP listens.
-On Istio version 1.6.0+, if Istio is installed with [`demo` profile](https://istio.io/latest/docs/setup/additional-setup/config-profiles/), you can enable ALS with command:
+- Enable [`envoyAccessLogService` in ProxyConfig](https://istio.io/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig) and set the ALS address to where the SkyWalking OAP listens.
+In Istio version 1.6.0+, if Istio is installed with [`demo` profile](https://istio.io/latest/docs/setup/additional-setup/config-profiles/), you can enable ALS with this command:
```shell
istioctl manifest apply \
@@ -29,10 +29,9 @@ On Istio version 1.6.0+, if Istio is installed with [`demo` profile](https://ist
- Activate SkyWalking [Envoy Receiver](../backend/backend-receivers.md). This is activated by default.
-- Choose an ALS analyzer. There are two available analyzers, `k8s-mesh` and `mx-mesh` for both HTTP access logs and TCP access logs.
- Set the system environment variable **SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS** and **SW_ENVOY_METRIC_ALS_TCP_ANALYSIS**
- such as `SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS=mx-mesh`, `SW_ENVOY_METRIC_ALS_TCP_ANALYSIS=mx-mesh`
- or in the `application.yaml` to activate the analyzer. For more about the analyzers, see [SkyWalking ALS Analyzers](#skywalking-als-analyzers)
+- Choose an ALS analyzer. There are two available analyzers for both HTTP access logs and TCP access logs: `k8s-mesh` and `mx-mesh`.
+ Set the system environment variables **SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS** and **SW_ENVOY_METRIC_ALS_TCP_ANALYSIS**,
+ such as `SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS=mx-mesh` and `SW_ENVOY_METRIC_ALS_TCP_ANALYSIS=mx-mesh`, or in `application.yaml` to activate the analyzers. For more about the analyzers, see [SkyWalking ALS Analyzers](#skywalking-als-analyzers).
```yaml
envoy-metric:
@@ -43,11 +42,11 @@ On Istio version 1.6.0+, if Istio is installed with [`demo` profile](https://ist
alsTCPAnalysis: ${SW_ENVOY_METRIC_ALS_TCP_ANALYSIS:""}
```
- To use multiple analyzers as a fallbackļ¼please use `,` to concatenate.
+ To use multiple analyzers as a fallback, please use `,` to concatenate.
## Example
-Here's an example to install Istio and deploy SkyWalking by Helm chart.
+Here's an example on installing Istio and deploying SkyWalking by Helm chart.
```shell
istioctl install \
@@ -69,42 +68,38 @@ helm install 8.1.0 skywalking -n istio-system \
--set oap.envoy.als.enabled=true
```
-You can use `kubectl -n istio-system logs -l app=skywalking | grep "K8sALSServiceMeshHTTPAnalysis"` to ensure OAP ALS `mx-mesh` analyzer has been activated.
+You can use `kubectl -n istio-system logs -l app=skywalking | grep "K8sALSServiceMeshHTTPAnalysis"` to ensure that OAP ALS `mx-mesh` analyzer has been activated.
## SkyWalking ALS Analyzers
-There are several available analyzers, `k8s-mesh`, `mx-mesh` and `persistence`, you can specify one or more
+There are several available analyzers: `k8s-mesh`, `mx-mesh`, and `persistence`. You can specify one or more
analyzers to analyze the access logs. When multiple analyzers are specified, it acts as a fast-success mechanism:
-SkyWalking loops over the analyzers and use it to analyze the logs, once there is an analyzer that is able to produce a
+SkyWalking loops over the analyzers and use them to analyze the logs. Once there is an analyzer that is able to produce a
result, it stops the loop.
### `k8s-mesh`
`k8s-mesh` uses the metadata from Kubernetes cluster, hence in this analyzer OAP needs access roles to `Pod`, `Service`, and `Endpoints`.
-The [blog](https://skywalking.apache.org/blog/2020-12-03-obs-service-mesh-with-sw-and-als/) illustrates the detail of how it works, and a step-by-step tutorial to apply it into the `bookinfo` application.
+The [blog](https://skywalking.apache.org/blog/2020-12-03-obs-service-mesh-with-sw-and-als/) illustrates the details of how it works, and a step-by-step tutorial to apply it into the `bookinfo` application.
### `mx-mesh`
-`mx-mesh` uses the Envoy metadata exchange mechanism to get the service name, etc.,
-this analyzer requires Istio to enable the metadata exchange plugin (you can enable it by `--set values.telemetry.v2.enabled=true`,
-or if you're using Istio 1.7+ and installing it with profile `demo`/`preview`, it should be enabled then).
+`mx-mesh` uses the Envoy metadata exchange mechanism to get the service name, etc.
+This analyzer requires Istio to enable the metadata exchange plugin (you can enable it by `--set values.telemetry.v2.enabled=true`,
+or if you're using Istio 1.7+ and installing it with profile `demo`/`preview`, it should already be enabled).
-The [blog](https://skywalking.apache.org/blog/obs-service-mesh-vm-with-sw-and-als/) illustrates the detail of how it works, and a step-by-step tutorial to apply it into the [Online Boutique](https://github.com/GoogleCloudPlatform/microservices-demo) system.
+The [blog](https://skywalking.apache.org/blog/obs-service-mesh-vm-with-sw-and-als/) illustrates the details of how it works, and a step-by-step tutorial to apply it into the [Online Boutique](https://github.com/GoogleCloudPlatform/microservices-demo) system.
### `persistence`
`persistence` analyzer adapts the Envoy access log format to
-SkyWalking's [native log format](https://github.com/apache/skywalking-data-collect-protocol/blob/master/logging/Logging.proto)
-, and forwards the formatted logs to [LAL](../../concepts-and-designs/lal.md), where you can configure persistent
+SkyWalking's [native log format](https://github.com/apache/skywalking-data-collect-protocol/blob/master/logging/Logging.proto), and forwards the formatted logs to [LAL](../../concepts-and-designs/lal.md), where you can configure persistent
conditions, such as `sampler`, only persist error logs, etc. SkyWalking provides a default configuration
file [`envoy-als.yaml`](../../../../oap-server/server-bootstrap/src/main/resources/lal/envoy-als.yaml) that you can
adjust as per your needs. Please make sure to activate this rule via adding the rule name `envoy-als`
into config item `log-analyzer/default/lalFiles` (or environment variable `SW_LOG_LAL_FILES`,
e.g. `SW_LOG_LAL_FILES=envoy-als`).
-**Attention**: because `persistence` analyzer also needs a mechanism to map the logs into responding services, hence,
-you need to configure at least one of `k8s-mesh` or `mx-mesh` as its antecedent so that `persistence` analyzer knows
-which service the logs belong to. For example, you should set `envoy-metric/default/alsHTTPAnalysis` (or environment
-variable `SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS`) to something like `k8s-mesh,persistence`, `mx-mesh,persistence`
-or `mx-mesh,k8s-mesh,persistence`.
+**Attention**: Since the `persistence` analyzer also needs a mechanism to map the logs into responding services, you need to configure at least one of `k8s-mesh` or `mx-mesh` as its antecedent so that `persistence` analyzer knows which service the logs belong to. For example, you should set `envoy-metric/default/alsHTTPAnalysis` (or environment
+variable `SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS`) to something like `k8s-mesh,persistence`, `mx-mesh,persistence`, or `mx-mesh,k8s-mesh,persistence`.
diff --git a/docs/en/setup/envoy/examples/metrics/README.md b/docs/en/setup/envoy/examples/metrics/README.md
index 9b75236..ee67df5 100644
--- a/docs/en/setup/envoy/examples/metrics/README.md
+++ b/docs/en/setup/envoy/examples/metrics/README.md
@@ -5,11 +5,11 @@ through [Metric Service](https://www.envoyproxy.io/docs/envoy/v1.18.2/api-v2/con
## Running the example
-The example requires `docker` and `docker-compose` to be installed in your local. It fetches images from Docker Hub.
+The example requires `docker` and `docker-compose` to be installed in your local system. It fetches images from Docker Hub.
-Note that in ths setup, we override the [`log4j2.xml`](log4j2.xml) config to set the `org.apache.skywalking.oap.server.receiver.envoy` logger level to `DEBUG`. This enables us to see the messages sent by Envoy to SkyWalking OAP server.
+Note that in this setup, we override the [`log4j2.xml`](log4j2.xml) config to set the `org.apache.skywalking.oap.server.receiver.envoy` logger level to `DEBUG`. This enables us to see the messages sent by Envoy to SkyWalking OAP server.
-You can also find Envoy Metric Service V3 API example in [docker-compose-envoy-v3-api.yaml](./docker-compose-envoy-v3-api.yaml)
+You can also find the Envoy Metric Service V3 API example in [docker-compose-envoy-v3-api.yaml](./docker-compose-envoy-v3-api.yaml)
```
$ make up
$ docker-compose logs -f skywalking
diff --git a/docs/en/setup/envoy/metrics_service_setting.md b/docs/en/setup/envoy/metrics_service_setting.md
index 6574ba8..8356c19 100644
--- a/docs/en/setup/envoy/metrics_service_setting.md
+++ b/docs/en/setup/envoy/metrics_service_setting.md
@@ -1,22 +1,22 @@
# Send Envoy metrics to SkyWalking with / without Istio
-Envoy defines a gRPC service to emit the metrics, whatever implements this protocol can be used to receive the metrics.
-SkyWalking has a built-in receiver that implements this protocol so that you can configure Envoy to emit its metrics to SkyWalking.
+Envoy defines a gRPC service to emit metrics, and whatever is used to implement this protocol can be used to receive the metrics.
+SkyWalking has a built-in receiver that implements this protocol, so you can configure Envoy to emit its metrics to SkyWalking.
-As an APM system, SkyWalking does not only receive and store the metrics emitted by Envoy, it also analyzes the topology of services and service instances.
+As an APM system, SkyWalking does not only receive and store the metrics emitted by Envoy, but it also analyzes the topology of services and service instances.
-**Attention:** There are two versions of Envoy metrics service protocol up to date,
+**Attention:** There are two versions of Envoy metrics service protocol currently:
[v2](https://www.envoyproxy.io/docs/envoy/v1.18.2/api-v2/api/v2/core/grpc_service.proto#envoy-api-msg-core-grpcservice) and
-[v3](https://www.envoyproxy.io/docs/envoy/v1.18.2/api-v3/config/metrics/v3/metrics_service.proto), SkyWalking (8.3.0+) supports both of them.
+[v3](https://www.envoyproxy.io/docs/envoy/v1.18.2/api-v3/config/metrics/v3/metrics_service.proto). SkyWalking (8.3.0+) supports both of them.
## Configure Envoy to send metrics to SkyWalking without Istio
-Envoy can be used with / without Istio's control. This section introduces how to configure the standalone Envoy to send the metrics to SkyWalking.
+Envoy can be used with / without Istio. This section explains how you can configure the standalone Envoy to send metrics to SkyWalking.
-In order to let Envoy send metrics to SkyWalking, we need to feed Envoy with a configuration which contains `stats_sinks` that includes `envoy.metrics_service`.
+In order to let Envoy send metrics to SkyWalking, we need to feed Envoy with a configuration that contains `stats_sinks`, which in turn includes `envoy.metrics_service`.
This `envoy.metrics_service` should be configured as a [`config.grpc_service`](https://www.envoyproxy.io/docs/envoy/v1.18.2/api-v2/api/v2/core/grpc_service.proto#envoy-api-msg-core-grpcservice) entry.
-The interesting parts of the config is shown in the config below:
+The noteworthy parts of the config are shown below:
```yaml
stats_sinks:
@@ -48,11 +48,11 @@ static_resources:
port_value: 11800
```
-A more complete static configuration, can be observed [here](config.yaml).
+The comprehensive static configuration can be found [here](config.yaml).
Note that Envoy can also be configured dynamically through [xDS Protocol](https://github.com/envoyproxy/envoy/blob/v1.18.2/api/xds_protocol.rst).
-As mentioned above, SkyWalking also builds the topology of services from the metrics, this is because Envoy also carries the service metadata along with the metrics, to feed the Envoy such metadata, another configuration part is as follows:
+As mentioned above, SkyWalking also builds the topology of services from the metrics, since Envoy also carries service metadata along with the metrics. To feed Envoy such metadata, see the other part of the configuration as follows:
```yaml
node:
@@ -65,10 +65,10 @@ node:
## Configure Envoy to send metrics to SkyWalking with Istio
-Typically, Envoy can be also used under Istio's control, where the configurations are much more simple because Istio composes the configurations for you and sends them to Envoy via [xDS Protocol](https://github.com/envoyproxy/envoy/blob/v1.18.2/api/xds_protocol.rst).
-Istio also automatically injects the metadata such as service name and instance name into the bootstrap configurations.
+Typically, Envoy can also be used with Istio. In this case, the configurations are much simpler because Istio composes the configurations for you and sends them to Envoy via [xDS Protocol](https://github.com/envoyproxy/envoy/blob/v1.18.2/api/xds_protocol.rst).
+Istio also automatically injects the metadata, such as service name and instance name, into the bootstrap configurations.
-Under this circumstance, emitting the metrics to SyWalking is as simple as adding the option `--set meshConfig.defaultConfig.envoyMetricsService.address=<skywalking.address.port.11800>` to Istio install command, for example:
+Emitting the metrics to SkyWalking is as simple as adding the option `--set meshConfig.defaultConfig.envoyMetricsService.address=<skywalking.address.port.11800>` to Istio install command, like this:
```shell
istioctl install -y \
@@ -87,9 +87,9 @@ istioctl manifest install -y \
```
Note:
-`proxyStatsMatcher` only supported by `Istio 1.8+`.
-We recommend using `inclusionRegexps` to reserve the specific metrics which need to analyze that can reduce Memory and CPU overhead.
-For example, OAP used these metrics:
+`proxyStatsMatcher` is only supported by `Istio 1.8+`.
+We recommend using `inclusionRegexps` to reserve specific metrics which need to be analyzed, in order to reduce memory usage and avoid CPU overhead.
+For example, OAP uses these metrics:
```shell
istioctl manifest install -y \
@@ -107,4 +107,4 @@ istioctl manifest install -y \
# Metrics data
-Some Envoy statistics are listed in this [list](https://www.envoyproxy.io/docs/envoy/v1.17.0/configuration/upstream/cluster_manager/cluster_stats#config-cluster-manager-cluster-stats). A sample data that contains identifier can be found [here](identify.json), while the metrics only can be observed [here](metrics.json).
+Some Envoy statistics are [listed here](https://www.envoyproxy.io/docs/envoy/v1.17.0/configuration/upstream/cluster_manager/cluster_stats#config-cluster-manager-cluster-stats). Sample data that contain identifiers can be found [here](identify.json), while the metrics can be found [here](metrics.json).