diff --git a/docs/README.md b/docs/README.md index 4c0a176af9786c76d05bc16ebe482dc5ec9066ca..00ce567c7d27ae7f5437319f84822196981e50a8 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 15e9cacc2ee9957916529d75e902f27e873050af..7380685fdd39617c8a045c30d82a73d526a52ecc 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 0000000000000000000000000000000000000000..a246857a2018de296cf44605ebb064843f682621 --- /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 e439f4c08b9e75080043914b8d9ed1f34559ad55..af3802542481cad55bc2f6476b55776b40d4af75 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 56213847c594a03b3898c260077d543221b784b9..f91c9386d048c61ffebea82b053a1379d21983cc 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 0000000000000000000000000000000000000000..c474b32ae7c262d35350f7754f755f28808e24cb --- /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: + + + +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 c51e5a10b0d60cb9a59f51baa34d92c9c312658a..ca23bd633897a5f5facaa4a8746f2569ecd9754e 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