You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@skywalking.apache.org by wu...@apache.org on 2018/07/10 06:03:44 UTC
[incubator-skywalking] branch 6.0 updated: Finish more documents
about high level design of SkyWalking 6.
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch 6.0
in repository https://gitbox.apache.org/repos/asf/incubator-skywalking.git
The following commit(s) were added to refs/heads/6.0 by this push:
new a26e6af Finish more documents about high level design of SkyWalking 6.
a26e6af is described below
commit a26e6af6c70f7a453ff0a32ebcfdacd00328fd77
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Mon Jul 9 23:03:35 2018 -0700
Finish more documents about high level design of SkyWalking 6.
---
docs/README.md | 6 ++--
docs/en/concepts-and-designs/README.md | 3 +-
docs/en/concepts-and-designs/manual-sdk.md | 21 ++++++++++++
docs/en/concepts-and-designs/probe-introduction.md | 6 ++--
docs/en/concepts-and-designs/service-agent.md | 39 +++++++++++++++++++++-
docs/en/concepts-and-designs/service-mesh-probe.md | 32 ++++++++++++++++++
.../{zipkin.md => trace-receiver.md} | 0
docs/en/setup/README.md | 5 +--
8 files changed, 103 insertions(+), 9 deletions(-)
diff --git a/docs/README.md b/docs/README.md
index 4c0a176..00ce567 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,7 +1,7 @@
# Welcome
**SkyWalking 6 documents and codes are still on building, Status: WIP. Of course, we welcome everyone to join us.**
-From here you can learn all about **SkyWalking**’s architecture, how to deploy and use SkyWalking, even develop something based on SkyWalking.
+From here you can learn all about **SkyWalking**’s architecture, how to deploy and use SkyWalking, even develop based on SkyWalking.
- [Concepts and Designs](en/concepts-and-designs/README.md). Concepts and designs explain the most important core ideas about
SkyWalking. You can learn from here if you want to understand what is going on under our cool features and visualization.
@@ -17,10 +17,10 @@ you are facing a problem, check here first.
In addition, you might find these links interesting:
-- The latest and old releases are all available in [Apache SkyWalking release page](http://skywalking.apache.org/downloads/). The change logs are [here](../CHANGES.md).
+- The latest and old releases are all available at [Apache SkyWalking release page](http://skywalking.apache.org/downloads/). The change logs are [here](../CHANGES.md).
- You can find the speaking schedules at Conf, online videos and articles about SkyWalking in [Community resource catalog](https://github.com/OpenSkywalking/Community).
Also, if you have some related to us, welcome to submit a pull request to add.
- We’re always looking for help improving our documentation and codes, so please don’t hesitate to [file an issue](https://github.com/apache/incubator-skywalking/issues/new)
if you see some problem.
-Or better yet, submit your own contributions to help make them better.
+Or better yet, submit your own contributions through pull request to help make them better.
diff --git a/docs/en/concepts-and-designs/README.md b/docs/en/concepts-and-designs/README.md
index 15e9cac..7380685 100644
--- a/docs/en/concepts-and-designs/README.md
+++ b/docs/en/concepts-and-designs/README.md
@@ -15,10 +15,11 @@ why need them.
SkyWalking already support.
- [Manual instrument SDK](manual-sdk.md). Introduce the role of the manual instrument SDKs in SkyWalking ecosystem.
- [Service Mesh probe](service-mesh-probe.md). Introduce why and how SkyWalking receive telemetry data from Service mesh and proxy probe.
- - [Zipkin receiver](zipkin.md). Helps you to know the purposes of receiving other libs data. Also how to process this kind of data format.
- Backend
- [Overview](backend-overview.md). Provides a high level introduction about the OAP backend.
- [Observability Analysis Language](oal.md). Introduces the core languages, which is designed for aggregation behaviour definition.
- [Query in OAP](query-oap.md). Introduces how to query data from backend, whether a simple metric data or topology map, even trace or log.
+ - [Receiver for other tracers](trace-receiver.md). Helps you to know the purposes of receiving other libs(such as Zipkin, Jeager, OpenCensus) data.
+Also how to process this kind of data format.
- UI
- [Overview](ui-overview.md).
diff --git a/docs/en/concepts-and-designs/manual-sdk.md b/docs/en/concepts-and-designs/manual-sdk.md
new file mode 100644
index 0000000..a246857
--- /dev/null
+++ b/docs/en/concepts-and-designs/manual-sdk.md
@@ -0,0 +1,21 @@
+# Manual instrument SDK
+We haven't provided any manual instrument SDK yet.
+
+Welcome to consider contributing in following languages:
+- Go
+- Python
+- C++
+
+## What is SkyWalking formats and propagation protocols?
+See these protocols in [protocols document](../protocols/README.md).
+
+## Can SkyWalking provide OpenCensus exporter in above languages?
+At the moment I am writing this document, **NO**. Because, OC(OpenCensus) don't support context extendable
+mechanism, and no hook mechanism when manipulate spans. SkyWalking relied on those to propagate more things
+than trace id and span id.
+
+We are already in the middle of discussion, see https://github.com/census-instrumentation/opencensus-specs/issues/70.
+After OC provides this officially, we can.
+
+## How about Zipkin instrument SDKs?
+See [Zipkin receiver](trace-receiver.md) in backend section. It is different
\ No newline at end of file
diff --git a/docs/en/concepts-and-designs/probe-introduction.md b/docs/en/concepts-and-designs/probe-introduction.md
index e439f4c..af38025 100644
--- a/docs/en/concepts-and-designs/probe-introduction.md
+++ b/docs/en/concepts-and-designs/probe-introduction.md
@@ -14,7 +14,7 @@ is only used as ingress of the whole cluster, but with the Service Mesh and side
- **3rd-party instrument library**. SkyWalking accepts other popular used instrument libraries data format. It analysis the
data, transfer it to SkyWalking formats of trace, metric or both. This feature starts with accepting Zipkin span data. See
-[Zipkin receiver](zipkin.md) to know more.
+[Receiver for other tracers](trace-receiver.md) to know more.
You don't need to use **Language based native agent** and **Service Mesh probe** at the same time, because they both collect
metric data. As a result of that, your system suffers twice payloads, and the analytic numbers are doubled.
@@ -32,5 +32,7 @@ which do analysis and aggregate on those traces. **In tracing status** means, ba
like logs, just save them, and build the links between traces and metrics, like `which endpoint and service does the trace belong?`.
## What is next?
-After understand the probe, read [backend overview](backend-overview.md) for understanding analysis and persistence.
+- Learn the SkyWalking supported probes in [Service auto instrument agent](service-agent.md), [Manual instrument SDK](manual-sdk.md),
+[Service Mesh probe](service-mesh-probe.md) and [Zipkin receiver](trace-receiver.md).
+- After understand the probe, read [backend overview](backend-overview.md) for understanding analysis and persistence.
diff --git a/docs/en/concepts-and-designs/service-agent.md b/docs/en/concepts-and-designs/service-agent.md
index 5621384..f91c938 100644
--- a/docs/en/concepts-and-designs/service-agent.md
+++ b/docs/en/concepts-and-designs/service-agent.md
@@ -1,2 +1,39 @@
# Service Auto Instrument Agent
-Service auto instrument agent is a subset of Language based native agents.
\ No newline at end of file
+Service auto instrument agent is a subset of Language based native agents. In this kind of agent, it is based on
+some language specific features, usually a VM based languages.
+
+## What does Auto Instrument mean?
+Many users know these agents from hearing
+`They say don't need to change any single line of codes`, SkyWalking used to put these words in our readme page too.
+But actually, it is right and wrong. For end user, **YES**, they don't need to change codes, at least for most cases.
+But also **NO**, the codes are still changed by agent, usually called `manipulate codes at runtime`. Underlying, it is just
+auto instrument agent including codes about how to change codes through VM interface, such as change class in Java through
+`javaagent premain`.
+
+Also, we said that the most auto instrument agents are VM based, but actually, you can build a tool at compiling time, rather than
+runtime.
+
+## What are limits?
+Auto instrument is so cool, then you can create those in compiling time, that you don't depend on VM features, then is there
+any limit?
+
+The answer definitely **YES**. And they are:
+- **In process propagation possible in most cases**. In many high level languages, they are used to build business system,
+such as Java and .NET. Most codes of business logic are running in the same thread for per request, which make the propagation
+could be based on thread Id, and stack module to make sure the context is safe.
+
+- **Just effect frameworks or libraries**. Because of the changing codes by agents, it also means the codes are already known
+by agent plugin developers. So, there is always a supported list in this kind of probes.
+Like [SkyWalking Java agent supported list](../setup/service-agent/java-agent/Supported-list.md).
+
+- **Across thread can't be supported all the time**. Like we said about **in process propagation**, most codes
+run in a single thread per request. But in some other scenarios, they do things in different threads, such as
+job assignment, task pool or batch process. Or some languages provide coroutine or similar thing like `Goroutine`, then
+developer could run async process with low payload, even been encouraged. In those cases, auto instrument will face problems.
+
+So, no mystery for auto instrument, in short words, agent developers write an activation to make
+instrument codes work you. That is all.
+
+## What is next?
+If you want to learn about manual instrument libs in SkyWalking, see [Manual instrument SDK](manual-sdk.md) section.
+
diff --git a/docs/en/concepts-and-designs/service-mesh-probe.md b/docs/en/concepts-and-designs/service-mesh-probe.md
new file mode 100644
index 0000000..c474b32
--- /dev/null
+++ b/docs/en/concepts-and-designs/service-mesh-probe.md
@@ -0,0 +1,32 @@
+# Server Mesh Probe
+Service Mesh probes use the extendable mechanism provided in Service Mesh implementor, like Istio.
+
+## What is Service Mesh?
+The following explanation came from Istio documents.
+> The term service mesh is often used to describe the network of microservices that make up such applications and the interactions between them.
+As a service mesh grows in size and complexity, it can become harder to understand and manage.
+Its requirements can include discovery, load balancing, failure recovery, metrics, and monitoring, and often more complex operational requirements
+such as A/B testing, canary releases, rate limiting, access control, and end-to-end authentication.
+
+## Where does the probe collect data from?
+Istio is a very typical Service Mesh design and implementor. It defines **Control Panel** and **Data Panel**,
+which are wide used. Here is Istio Architecture:
+
+<img src="https://istio.io/docs/concepts/what-is-istio/img/overview/arch.svg"/>
+
+Service Mesh probe can choose to collect data from **Control Panel** or **Data Panel**. In Istio,
+it means collecting telemetry data from Mixer(Control Panel) or Envoy sidecar(Data Panel). Underlying
+they are same data, the probe collects two telemetry entities from client side and server side per request.
+
+## How does Service Mesh make backend work?
+From the probe, you can see there must have no trace related in this kind of probe, so why SkyWalking
+platform still works?
+
+Service Mesh probes collects telemetry data from each request, so it knows the source, destination,
+endpoint, latency and status. By those, backend can tell the whole topology map by combining these call
+as lines, and also the metric of each nodes through their incoming request. Backend asked for the same
+metric data from parsing tracing data. So, the right expression is:
+**Service Mesh metric are exact the metric, what the traces parsers generate. They are same.**
+
+## What is Next?
+- If you want to use the service mesh probe, read [set SkyWalking on Service Mesh](../setup/README.md#on-service-mesh) document.
diff --git a/docs/en/concepts-and-designs/zipkin.md b/docs/en/concepts-and-designs/trace-receiver.md
similarity index 100%
rename from docs/en/concepts-and-designs/zipkin.md
rename to docs/en/concepts-and-designs/trace-receiver.md
diff --git a/docs/en/setup/README.md b/docs/en/setup/README.md
index c51e5a1..ca23bd6 100644
--- a/docs/en/setup/README.md
+++ b/docs/en/setup/README.md
@@ -1,12 +1,13 @@
# Setup
Setup based on which kind of probes are you going to use. If you don't understand, please read [Concepts and Designs](../concepts-and-designs/README.md) first.
-- Language agents in Service
+## Language agents in Service
- Install agents
- [Java agent](service-agent/java-agent/README.md). Introduce how to install java agent to your application, without change any codes.
- [.NET Core agent](https://github.com/OpenSkywalking/skywalking-netcore). See .NET Core agent project document for more details.
- [Node.js agent](https://github.com/OpenSkywalking/skywalking-nodejs). See Node.js server side agent project document for more details.
- [Setup backend](service-agent/backend-setup.md). Set the backend for language agents scenario.
-- On Service Mesh
+
+## On Service Mesh
- Istio
- [SkyWalking on Istio](istio/README.md). Introduce how to use Istio Mixer SkyWalking Adapter to work with SkyWalking.
\ No newline at end of file