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