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"