doc: polish the documentations on ALS and MS (#6292)

* doc: polish the documentations on ALS and MS

* Update als_setting.md
Co-authored-by: 吴晟 Wu Sheng <wu.sheng@foxmail.com>

docs/README.md

@@ -67,11 +67,11 @@ If you are already familiar with SkyWalking, you could use this catalog to find
     * Browser performance monitoring
       * Track the performance of the browser, such as latency of redirect, dns, ttfb. For more information, [click here](https://github.com/apache/skywalking-client-js).
   * Service Mesh
-    * [SkyWalking on Istio](en/setup/istio/README.md). Introduces how to use Istio Mixer bypass Adapter to work with SkyWalking.
-    * Use [ALS (access log service)](https://www.envoyproxy.io/docs/envoy/latest/api-v2/service/accesslog/v2/als.proto) to observe service mesh, without Mixer. Follow [document](en/setup/envoy/als_setting.md) to open it.
+    * [Observe Istio Control Plane](en/setup/istio/README.md). Introduces how to use SkyWalking to observe the Istio control plane.
+    * [Observe Service Mesh](en/setup/envoy/als_setting.md). Introduces how to use SkyWalking and [Envoy Access Log Service (ALS)](https://www.envoyproxy.io/docs/envoy/latest/api-v2/service/accesslog/v2/als.proto) to observe service mesh.
   * Proxy
     * [Envoy Proxy](https://www.envoyproxy.io/)
-      * [Sending metrics to Skywalking from Envoy](en/setup/envoy/metrics_service_setting.md). How to send metrics from Envoy to SkyWalking using [Metrics service](https://www.envoyproxy.io/docs/envoy/latest/api-v2/config/metrics/v2/metrics_service.proto.html).
+      * [Send Envoy metrics to SkyWalking with / without Istio](en/setup/envoy/metrics_service_setting.md).
   * [Backend, UI and CLI setup document](en/setup/backend/backend-ui-setup.md).
     * [Backend setup document](en/setup/backend/backend-setup.md).
       * [Configuration Vocabulary](en/setup/backend/configuration-vocabulary.md). Configuration Vocabulary lists all available configurations provided by `application.yml`.

docs/en/setup/envoy/als_setting.md

-# Observe service mesh through ALS
-Envoy [ALS(access log service)](https://www.envoyproxy.io/docs/envoy/latest/api-v2/service/accesslog/v2/als.proto) provides
+# Observe Service Mesh through ALS
+
+[Envoy Access Log Service (ALS)](https://www.envoyproxy.io/docs/envoy/latest/api-v2/service/accesslog/v2/als.proto) provides
 full logs about RPC routed, including HTTP and TCP.
 
-The solution is 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 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).
+## 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).
 
 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.
 
-You need three steps to open ALS.
-1. Open envoyAccessLogService in istio by [enabling **envoyAccessLogService** in ProxyConfig](https://istio.io/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig).
+## 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:
+
+   ```shell
+   istioctl manifest apply \
+     --set profile=demo \
+     --set meshConfig.enableEnvoyAccessLogService=true \
+     --set meshConfig.defaultConfig.envoyAccessLogService.address=<skywalking-oap.skywalking.svc:11800>
+   ```
 
-    Upper istio 1.6.0, if istio installed by demo profile, you can open ALS ues command:
-    ```
-    istioctl manifest apply --set profile=demo --set meshConfig.defaultConfig.envoyAccessLogService.address=skywalking-oap.skywalking.svc:11800 --set meshConfig.enableEnvoyAccessLogService=true
-    ```
-    Note: SkyWalking OAP service is at skywalking namespace, and the port of gRPC service is 11800
+   Note: Replace `<skywalking-oap.skywalking.svc:11800>` with the real address where SkyWalking OAP is deployed.
     
-2. (Default is ACTIVATED) Activate SkyWalking [envoy receiver](../backend/backend-receivers.md). 
-3. Active ALS analyzer, there are two available analyzers, `k8s-mesh` and `mx-mesh`,
-`k8s-mesh` uses the metadata from Kubernetes cluster, hence in this analyzer OAP needs access roles to `Pod`, `Service`, and `Endpoints`;
-`mx-mesh` uses the Envoy metadata exchange mechanism to get the service name, etc.,
-this analyzer requires Istio to enable the metadata exchange filter(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).
-Setting system env variable **SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS** to activate the analyzer,
-such as `SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS=k8s-mesh`.
-```yaml
-envoy-metric:
-  selector: ${SW_ENVOY_METRIC:default}
-  default:
-    acceptMetricsService: ${SW_ENVOY_METRIC_SERVICE:true}
-    alsHTTPAnalysis: ${SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS:""} # Setting the system env variable would override this. 
-```
-For multiple values，please use `,` symbol to concatenate.
+- Activate SkyWalking [Envoy Receiver](../backend/backend-receivers.md). This is activated by default. 
 
-Here's an example to deploy SkyWalking by Helm chart.
+- Choose an ALS analyzer. There are two available analyzers, `k8s-mesh` and `mx-mesh`.
+  Set the system environment variable **SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS** such as `SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS=k8s-mesh`
+  or in the `application.yaml` to activate the analyzer. For more about the analyzers, see [SkyWalking ALS Analyzers](#skywalking-als-analyzers)
 
-```
-istioctl install --set profile=demo --set meshConfig.defaultConfig.envoyAccessLogService.address=skywalking-oap.istio-system:11800 --set meshConfig.enableEnvoyAccessLogService=true
+   ```yaml
+   envoy-metric:
+     selector: ${SW_ENVOY_METRIC:default}
+     default:
+       acceptMetricsService: ${SW_ENVOY_METRIC_SERVICE:true}
+       alsHTTPAnalysis: ${SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS:""} # Setting the system env variable would override this. 
+   ```
+
+   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.
+
+```shell
+istioctl install \
+  --set profile=demo \
+  --set meshConfig.enableEnvoyAccessLogService=true \
+  --set meshConfig.defaultConfig.envoyAccessLogService.address=skywalking-oap.istio-system:11800
 
 git clone https://github.com/apache/skywalking-kubernetes.git
 cd skywalking-kubernetes/chart
@@ -48,9 +60,29 @@ helm repo add elastic https://helm.elastic.co
 
 helm dep up skywalking
 
-helm install 8.1.0 skywalking -n istio-system --set oap.env.SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS=k8s-mesh --set fullnameOverride=skywalking --set oap.envoy.als.enabled=true
+helm install 8.1.0 skywalking -n istio-system \
+  --set oap.env.SW_ENVOY_METRIC_ALS_HTTP_ANALYSIS=k8s-mesh \
+  --set fullnameOverride=skywalking \
+  --set oap.envoy.als.enabled=true
 ```
 
-Notice, only use this when Envoy is under Istio's control, and they are in k8s environment. The OAP requires the read right to k8s API server for all pods IPs.
+You can use `kubectl -n istio-system logs -l app=skywalking | grep "K8sALSServiceMeshHTTPAnalysis"` to ensure OAP ALS `k8s-mesh` analyzer has been activated.
+
+## SkyWalking ALS Analyzers
+
+There are two available analyzers, `k8s-mesh` and `mx-mesh`, 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 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.
+
+### `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).
 
-You can use `kubectl -n istio-system logs -l app=skywalking | grep "K8sALSServiceMeshHTTPAnalysis"` to ensure OAP ALS k8s-mesh analysis has been active.

docs/en/setup/envoy/metrics_service_setting.md

-# Configuring Envoy to send metrics to SkyWalking
+# Send Envoy metrics to SkyWalking with / without Istio
 
-In order to let Envoy to send metrics to SkyWalking, we need to feed Envoy with a configuration which contains `stats_sinks` that includes `envoy.metrics_service`.
+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.
+
+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.
+
+**Attention:** There are two versions of Envoy metrics service protocol up to date,
+[v2](https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/core/grpc_service.proto#envoy-api-msg-core-grpcservice) and
+[v3](https://www.envoyproxy.io/docs/envoy/latest/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.
+
+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`.
 This `envoy.metrics_service` should be configured as a [`config.grpc_service`](https://www.envoyproxy.io/docs/envoy/latest/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:
@@ -39,7 +52,7 @@ A more complete static configuration, can be observed [here](config.yaml).
 
 Note that Envoy can also be configured dynamically through [xDS Protocol](https://github.com/envoyproxy/data-plane-api/blob/master/XDS_PROTOCOL.md).
 
-**Attention**: Only use this when Envoy is under Istio's control, because SkyWalking needs to parse the service name and service instance name from the metadata that is injected by Istio. However, if you want to use this without Istio, you need to inject the metadata yourself like this:
+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:
 
 ```yaml
 node:
@@ -50,6 +63,27 @@ node:
     NAME: service-instance-name
 ```
 
+## 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/data-plane-api/blob/master/XDS_PROTOCOL.md).
+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:
+
+```shell
+istioctl install -y \
+  --set profile=demo `# replace the profile as per your need` \
+  --set meshConfig.defaultConfig.envoyMetricsService.address=<skywalking.address.port.11800> # replace <skywalking.address.port.11800> with your actual SkyWalking OAP address
+```
+
+If you already have Istio installed, you can use the following command to apply the config without re-installing Istio:
+
+```shell
+istioctl manifest install -y \
+  --set profile=demo `# replace the profile as per your need` \
+  --set meshConfig.defaultConfig.envoyMetricsService.address=<skywalking.address.port.11800> # replace <skywalking.address.port.11800> with your actual SkyWalking OAP address
+```
+
 # Metrics data
 
-Some of the Envoy statistics are listed in this [list](https://www.envoyproxy.io/docs/envoy/latest/configuration/statistics). 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 in this [list](https://www.envoyproxy.io/docs/envoy/latest/configuration/statistics). A sample data that contains identifier can be found [here](identify.json), while the metrics only can be observed [here](metrics.json).

docs/en/setup/istio/README.md

@@ -4,13 +4,13 @@ Instructions for transport Istio's metrics to the SkyWalking OAP server.
 
 ## Prerequisites
 
-Istio should be installed in the kubernetes cluster. Follow [Istio getting start](https://istio.io/docs/setup/getting-started/)
+Istio should be installed in the Kubernetes cluster. Follow [Istio getting start](https://istio.io/docs/setup/getting-started/)
 to finish it.
 
-## Deploy Skywalking backend
+## Deploy SkyWalking backend
 
-Follow the [deploying backend in kubernetes](../backend/backend-k8s.md) to install the OAP server in the kubernetes cluster.
-Referring to [OpenTelemetry receiver](../backend/backend-receivers.md#OpenTelemetry-receiver) to ingest metrics.
+Follow the [deploying backend in Kubernetes](../backend/backend-k8s.md) to install the OAP server in the kubernetes cluster.
+Refer to [OpenTelemetry receiver](../backend/backend-receivers.md#OpenTelemetry-receiver) to ingest metrics.
 `otel-receiver` defaults to be inactive. Set env var `SW_OTEL_RECEIVER` to `default` to enable it.