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 7fa06c028b Polish docs of `Concepts and Designs` (#11457)
7fa06c028b is described below
commit 7fa06c028b13013c5cc5987e02b747c9402e04b7
Author: 吴晟 Wu Sheng <wu.sh...@foxmail.com>
AuthorDate: Thu Oct 26 10:06:33 2023 +0800
Polish docs of `Concepts and Designs` (#11457)
---
docs/en/changes/changes.md | 1 +
docs/en/concepts-and-designs/backend-overview.md | 5 ++--
docs/en/concepts-and-designs/oal.md | 20 +++++++++++--
docs/en/concepts-and-designs/overview.md | 5 ++--
docs/en/concepts-and-designs/probe-introduction.md | 35 +++++++++++-----------
docs/menu.yml | 2 +-
6 files changed, 42 insertions(+), 26 deletions(-)
diff --git a/docs/en/changes/changes.md b/docs/en/changes/changes.md
index 8f8480031b..a30321c614 100644
--- a/docs/en/changes/changes.md
+++ b/docs/en/changes/changes.md
@@ -51,5 +51,6 @@
* Separate storage docs to different files, and add an estimated timeline for
BanyanDB(end of 2023).
* Add topology configuration in UI-Grafana doc.
* Add missing metrics to the `OpenTelemetry Metrics` doc.
+* Polish docs of `Concepts and Designs`.
All issues and pull requests are
[here](https://github.com/apache/skywalking/milestone/193?closed=1)
diff --git a/docs/en/concepts-and-designs/backend-overview.md
b/docs/en/concepts-and-designs/backend-overview.md
index d53440ca69..f68d123884 100644
--- a/docs/en/concepts-and-designs/backend-overview.md
+++ b/docs/en/concepts-and-designs/backend-overview.md
@@ -4,8 +4,9 @@ SkyWalking is an Observability Analysis Platform that provides
full observabilit
## Capabilities
SkyWalking covers all 3 areas of observability, including, **Tracing**,
**Metrics** and **Logging**.
-- **Tracing**. SkyWalking native data formats, including Zipkin v1 and v2, as
well as Jaeger.
-- **Metrics**. SkyWalking integrates with Service Mesh platforms, such as
Istio, Envoy, and Linkerd, to build observability into the data plane
+- **Tracing**. SkyWalking native data formats, and Zipkin traces of v1 and v2
formats are supported.
+- **Metrics**. SkyWalking supports mature metrics formats, including native
meter format, OTEL metrics format, and Telegraf format.
+SkyWalking integrates with Service Mesh platforms, typically Istio and Envoy,
to build observability into the data plane
or control plane. Also, SkyWalking native agents can run in the metrics mode,
which greatly improves performances.
- **Logging**. Includes logs collected from disk or through network. Native
agents could bind the tracing context with logs automatically,
or use SkyWalking to bind the trace and log through the text content.
diff --git a/docs/en/concepts-and-designs/oal.md
b/docs/en/concepts-and-designs/oal.md
index 5a0b8d2856..704529a246 100644
--- a/docs/en/concepts-and-designs/oal.md
+++ b/docs/en/concepts-and-designs/oal.md
@@ -1,13 +1,27 @@
+# Analysis Native Streaming Traces and Service Mesh Traffic
+
+The traces in SkyWalking native format and Service Mesh Traffic(Access Log in
gRPC) are able to be analyzed by OAL,
+to build metrics of services, service instances and endpoints, and to build
topology/dependency of services, service
+instances and endpoints(traces-oriented analysis only).
+
+The spans of traces relative with RPC, such as HTTP, gRPC, Dubbo, RocketMQ,
Kafka, would be converted to service input/output
+traffic, like access logs collected from service mesh. Both of those traffic
would be cataloged as the defined sources
+in the `Observability Analysis Language` engine.
+
+The metrics are customizable through Observability Analysis Language(OAL)
scripts,
+and the topology/dependency is built by the SkyWalking OAP kernel
automatically without
+explicit OAL scripts.
+
# Observability Analysis Language
OAL(Observability Analysis Language) serves to analyze incoming data in
streaming mode.
OAL focuses on metrics in Service, Service Instance and Endpoint. Therefore,
the language is easy to
learn and use.
-
-Since 6.3, the OAL engine is embedded in OAP server runtime as `oal-rt`(OAL
Runtime).
OAL scripts are now found in the `/config` folder, and users could simply
change and reboot the server to run them.
-However, the OAL script is a compiled language, and the OAL Runtime generates
java codes dynamically.
+However, the OAL script is a compiled language, and the OAL Runtime generates
java codes dynamically. Don't expect to mount
+the changes of those scripts in the runtime.
+If your OAP servers are running in a cluster mode, these script defined
metrics should be aligned.
You can open set `SW_OAL_ENGINE_DEBUG=Y` at system env to see which classes
are generated.
diff --git a/docs/en/concepts-and-designs/overview.md
b/docs/en/concepts-and-designs/overview.md
index 03da50ff64..6b6f376b9a 100644
--- a/docs/en/concepts-and-designs/overview.md
+++ b/docs/en/concepts-and-designs/overview.md
@@ -31,9 +31,8 @@ Kubernetes(k8s layer). All detected instances belong to a
layer to represent the
the service would have one or multiple layer definitions according to its
instances.
In addition, you can integrate
-1. Other distributed tracing using SkyWalking native agents and SDKs with
Zipkin and Jaeger.
-1. Other metrics systems, such as Prometheus, Sleuth(Micrometer),
OpenTelemetry.
-
+1. Other distributed tracing using Zipkin.
+1. Other metrics systems, such as Prometheus, Sleuth(Micrometer),
OpenTelemetry, Telegraf.
## Architecture
diff --git a/docs/en/concepts-and-designs/probe-introduction.md
b/docs/en/concepts-and-designs/probe-introduction.md
index 04b6736052..9407fd909f 100644
--- a/docs/en/concepts-and-designs/probe-introduction.md
+++ b/docs/en/concepts-and-designs/probe-introduction.md
@@ -9,39 +9,40 @@ On a high level, there are four typical categories in all
SkyWalking probes.
- **Language based native agent**. These agents run in target service user
spaces, such as a part of user codes. For
example, the SkyWalking Java agent uses the `-javaagent` command line
argument to manipulate codes in runtime,
- where `manipulate` means to change and inject user's codes. Another kind of
agents uses certain hook or intercept
- mechanism provided by target libraries. As you can see, these agents are
based on languages and libraries.
+ where `manipulate` means to change and inject user's codes. Another example
is SkyWalking agent, which leverage Golang
+ compiling mechanism to weaves codes in the compiling time. For some static
compilation languages, such as C++, manual
+ library is the only choice.
+ As you can see, these agents are based on languages and libraries, no matter
we provide auto instrument or manual agents.
- **Service Mesh probes**. Service Mesh probes collect data from sidecar,
control plane in service mesh or proxy. In the
old days, proxy is only used as an ingress of the whole cluster, but with
the Service Mesh and sidecar, we can now
perform observability functions.
-- **3rd-party instrument library**. SkyWalking accepts many widely used
instrument libraries data formats. It analyzes
- the data, transfers it to SkyWalking's formats of trace, metrics or both.
This feature starts with accepting Zipkin
- span data. See
- [Receiver for Zipkin traces](../setup/backend/zipkin-trace.md) for more
information.
+- **3rd-party instrument library**. SkyWalking accepts many widely used
instrument libraries data formats.
+ SkyWalking community is connected closely with Zipkin community, it could
work as an alternative server for both v1 and
+ v2 Zipkin traces. Also, OTEL trace format in gRPC is supported, and
converted to Zipkin format inside SkyWalking.
+ As an alternative Zipkin server, Zipkin lens UI could be used to visualize
accepted traces when they are in Zipkin format.
+ See [Receiver for Zipkin traces](../setup/backend/zipkin-trace.md) and
[Receiver for OTEL traces](../setup/backend/otlp-trace.md) for more information.
- **eBPF agent**. The eBPF agent collects metrics and profiling the target
service powered by the eBPF technology of Linux kernel.
-You don't need to use **Language based native agent** and **Service Mesh
probe** at the same time, since they both serve
-to collect metrics data. Otherwise, your system will suffer twice the payload,
and the analytic numbers will be doubled.
-
+You don't have to install all probes to make SkyWalking up and running.
There are several recommended ways on how to use these probes:
-1. Use **Language based native agent** only.
+1. Use **Language based native agent** only to build topology and metrics for
your business application.
1. Use **3rd-party instrument library** only, like the Zipkin instrument
ecosystem.
-1. Use **Service Mesh probe** only.
-1. Use **Service Mesh probe** with **Language based native agent** or
**3rd-party instrument library** in tracing
+1. Use **Service Mesh probe** if you prefer Service Mesh stack and don't want
to use native agents.
+1. Use **Service Mesh probe** with **Language based native agent** or
**3rd-party instrument library** in pure tracing
status. (Advanced usage)
-1. Use **eBPF agent** only.
-1. Use **eBPF agent** with **Language based native agent** collaboratively.
+1. Use **eBPF agent** only if you only want to profile on demand and/or
activating automatic performance analysis.
+1. Use **eBPF agent** with **Language based native agent** collaboratively.
Enhance the traces with the eBPF agent to collect extra information.
What is the meaning of **in tracing status**?
By default, **Language based native agent** and **3rd-party instrument
library** both send distributed traces to the
-backend, where analyses and aggregation on those traces are performed. **In
tracing status** means that the backend
-considers these traces as something like logs. In other words, the backend
saves them, and builds the links between
-traces and metrics, like `which endpoint and service does the trace belong?`.
+backend, where analyses and aggregation on those traces are performed. **In
pure tracing status** means that the backend
+considers these traces as something like logs. In other words, the backend
saves them, but doesn't run the metrics analysis from
+traces. As a result, there would not have data of `service/instance/endpoint
metrics and relationships`.
## What is next?
diff --git a/docs/menu.yml b/docs/menu.yml
index 4f9b92c16d..4e5203a8cc 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -38,7 +38,7 @@ catalog:
catalog:
- name: "Overview"
path: "/en/concepts-and-designs/backend-overview"
- - name: "Analysis Streaming Traces and Mesh Traffic"
+ - name: "Analysis Traces and Mesh Traffic"
path: "/en/concepts-and-designs/oal"
- name: "Analysis Metrics and Meters"
path: "/en/concepts-and-designs/mal"
