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 <[email protected]>
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 <[email protected]>
---
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.
