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/01/31 23:55:27 UTC
[skywalking] branch master updated: doc: polish the documentations
on ALS and MS (#6292)
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 74ef595 doc: polish the documentations on ALS and MS (#6292)
74ef595 is described below
commit 74ef5959f0e834880d3e34870906c0c261dfd233
Author: Zhenxu Ke <ke...@apache.org>
AuthorDate: Mon Feb 1 07:55:00 2021 +0800
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...@foxmail.com>
---
docs/README.md | 6 +-
docs/en/setup/envoy/als_setting.md | 104 ++++++++++++++++---------
docs/en/setup/envoy/metrics_service_setting.md | 42 +++++++++-
docs/en/setup/istio/README.md | 8 +-
4 files changed, 113 insertions(+), 47 deletions(-)
diff --git a/docs/README.md b/docs/README.md
index 4294031..9430ae6 100644
--- a/docs/README.md
+++ b/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`.
diff --git a/docs/en/setup/envoy/als_setting.md b/docs/en/setup/envoy/als_setting.md
index 811fe0d..6f0837d 100644
--- a/docs/en/setup/envoy/als_setting.md
+++ b/docs/en/setup/envoy/als_setting.md
@@ -1,45 +1,57 @@
-# 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.
diff --git a/docs/en/setup/envoy/metrics_service_setting.md b/docs/en/setup/envoy/metrics_service_setting.md
index 430ad81..9dae395 100644
--- a/docs/en/setup/envoy/metrics_service_setting.md
+++ b/docs/en/setup/envoy/metrics_service_setting.md
@@ -1,6 +1,19 @@
-# 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).
diff --git a/docs/en/setup/istio/README.md b/docs/en/setup/istio/README.md
index facb7e8..3e2794b 100644
--- a/docs/en/setup/istio/README.md
+++ b/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.