You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2022/02/26 13:26:57 UTC
[skywalking] 01/01: Add STAM paper to doc and Academy menu for listing important articles.
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/skywalking.git
commit 3c46ae2081e84d1536099e45ca61b326e4e6d98c
Author: Wu Sheng <wu...@foxmail.com>
AuthorDate: Sat Feb 26 21:26:33 2022 +0800
Add STAM paper to doc and Academy menu for listing important articles.
---
README.md | 4 --
docs/en/academy/list.md | 13 ++++
docs/en/papers/stam-cn.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++
docs/en/papers/stam.md | 156 ++++++++++++++++++++++++++++++++++++++++++++
docs/menu.yml | 4 ++
5 files changed, 333 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index c89788c..f4e59bb 100644
--- a/README.md
+++ b/README.md
@@ -51,10 +51,6 @@ for better performance. Read [the paper of STAM](https://wu-sheng.github.io/STAM
# Documentation
- [Official documentation](https://skywalking.apache.org/docs/#SkyWalking)
-- [The paper of STAM](https://wu-sheng.github.io/STAM/), Streaming Topology Analysis Method.
-- [Blog](https://skywalking.apache.org/blog/2020-04-13-apache-skywalking-profiling/) about Use Profiling to Fix the Blind Spot of Distributed Tracing
-- [Blog](https://skywalking.apache.org/blog/2020-12-03-obs-service-mesh-with-sw-and-als/) about observing Istio + Envoy service mesh with ALS solution.
-- [Blog](https://skywalking.apache.org/blog/obs-service-mesh-vm-with-sw-and-als/) about observing Istio + Envoy service mesh with ALS Metadata-Exchange mechanism (in VMs and / or Kubernetes).
NOTICE, SkyWalking 8.0+ uses [v3 protocols](docs/en/protocols/README.md). They are incompatible with previous releases.
diff --git a/docs/en/academy/list.md b/docs/en/academy/list.md
new file mode 100644
index 0000000..05d7cad
--- /dev/null
+++ b/docs/en/academy/list.md
@@ -0,0 +1,13 @@
+# Academy
+
+Academy is an article/video list recommended by the committer team.
+
+- [STAM Paper](../papers/stam.md) about the fundamental theory of SkyWalking tracing models.
+
+- [Blog](https://skywalking.apache.org/blog/2022-01-24-scaling-with-apache-skywalking/) about Scaling SkyWalking server automatically in kubernetes.
+
+- [Blog](https://skywalking.apache.org/blog/2020-04-13-apache-skywalking-profiling/) about Use Profiling to Fix the Blind Spot of Distributed Tracing.
+
+- [Blog](https://skywalking.apache.org/blog/2020-12-03-obs-service-mesh-with-sw-and-als/) about observing Istio + Envoy service mesh with ALS solution.
+
+- [Blog](https://skywalking.apache.org/blog/obs-service-mesh-vm-with-sw-and-als/) about observing Istio + Envoy service mesh with ALS Metadata-Exchange mechanism (in VMs and / or Kubernetes).
\ No newline at end of file
diff --git a/docs/en/papers/stam-cn.md b/docs/en/papers/stam-cn.md
new file mode 100644
index 0000000..f53de70
--- /dev/null
+++ b/docs/en/papers/stam-cn.md
@@ -0,0 +1,160 @@
+STAM：针对大型分布式应用系统的拓扑自动检测方法
+
+[](stam.md)
+
+- Sheng Wu 吴 晟
+- wusheng@apache.org
+- 翻译：BZFYS(327568824@qq.com), Yanlong He 何延龙 (heyanlong@apache.org)
+
+### 编者注
+这篇论文由项目创始人吴晟于2017年撰写，用于描述所有探针的核心基础理论。
+读者可以通过阅读此论文，了解为何SkyWalking的探针，和其他tracing系统以及Dapper论文[1]的描述有显著不同。
+
+# 摘要
+对大型分布式系统进行监视，可视化和故障排除是一项重大挑战。当今使用的一种常见工具是分布式跟踪系统（例如Google Dapper）[1]，它基于跟踪数据检测拓扑和度量。当今拓扑检测的一大局限性在于，只能根据给定的时间窗口的跟踪数据来推断服务之间的依赖关系。这会导致更多的延迟和内存使用，因为在高度分布式的系统中，每个客户端和服务端追踪信息都必须在数百万个随机RPC请求中进行匹配。更重要的是，如果客户端和服务器之间的RPC持续时间长于先前的设置时间窗口或跨越两个窗口，则它可能无法匹配。
+
+在本论文中，我们提出了STAM(流拓扑分析方法)。在STAM中，我们可以使用自动检测或手动检测机制在客户端和服务器端截取和操纵RPC。对于自动检测，STAM在runtime处理应用程序代码，例如Java代理。因此，此监视系统不需要应用程序开发团队或RPC框架开发团队修改任何源代码。STAM将客户端使用的RPC网络地址，服务名称和服务实例名称注入RPC上下文，并将服务器端服务名称和服务实例名称绑定为客户端使用的该网络地址的别名 。将依赖性分析从导致阻塞和延迟的机制中解放出来，
+
+STAM已在Apache Software Foundation的一个开源APM（应用程序性能监视系统）项目Apache SkyWalking [2]中实施，该项目已在许多大型企业中广泛使用[3]，其中包括阿里巴巴，华为，腾讯，滴滴，小米，中国移动和其他企业（航空公司，金融机构等）在生产环境中支持其大型分布式系统。它具有更好的水平扩展能力，从而显着降低了负载和内存成本。
+
+# 介绍
+监控高度分布式的系统（尤其是使用微服务体系结构）非常复杂。许多RPC，包括HTTP，gRPC，MQ，缓存和数据库访问，都在单个客户端请求之后。让IT团队了解数千个服务之间的依赖关系是整个分布式系统可观察性的关键特征和第一步。分布式跟踪系统能够收集跟踪，包括所有分布式请求路径。逻辑上已将依赖关系包括在跟踪数据中。分布式跟踪系统，例如Zipkin [4]或Jaeger Tracing [10]，提供了内置的依赖关系分析功能，而且有许多分析功能都基于此。这种分析至少存在两个局限性：实时性和一致的准确性。
+
+服务级别和服务实例级别的依赖分析过程中，由于分布式应用程序系统依赖关系的可变性，需要很强大的实时性保障。
+
+服务是具有相同功能或代码的实例的逻辑组。
+
+服务实例通常是操作系统级别的进程，例如JVM进程。服务和实例之间的关系是可变的，具体取决于配置，代码和网络状态。依赖关系可能会随着时间而改变。
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/dapper-span.png"/>
+<br/>
+图1，在传统的基于Dapper的跟踪系统中生成的span。
+</p>
+
+
+Dapper论文中的span模型和现有的跟踪系统（例如Zipkin仪器模式[9]）只是将span id传播到服务器端。由于这种模型，依赖性分析需要一定的时间窗口。关系分析同时依赖从客户端和服务端收集到的追踪数据。因此，分析过程必须等待客户端和服务器span在同一时间窗口中匹配，才能输出结果Service A依赖于Service B。因此，RPC请求持续时间必须在时间窗口内；否则，将无法分析出服务关系数据。在生产中，有时必须将窗口持续时间设置为3-5分钟，使得拓扑分析无法在秒级做出反应。另外，由于基于时间窗口的设计，如果一侧涉及到长时间任务，它不能轻易达到一致的精度。因为，为了使分析尽可能快，所以分析时间少于5分钟。但是，如果分析不完整或跨越两个时间窗口，则某些span将无法与其父级或子级匹配。即使我们添加了一种机制来处理前一阶段剩余�
�span，仍然必须放弃一些机制以保持数据集大小和内存使用合理。
+
+在STAM中，我们使用新的分析方法介绍了新的span和上下文传播模型。这种新模型将客户端使用的对端网络地址（IP或主机名），同时，客户端将自己的服务实例名称和客户端服务名称添加到上下文传播模型中。然后，依托RPC调用从客户端传递到服务器，就像现有跟踪系统中的传递原始Trace ID和Span ID一样，并将其收集在服务器端span中。新的分析方法可以轻松地直接生成客户端-服务器关系，而无需等待客户端span。它还将客户端使用的对端网络地址设置为服务端服务的一个别名。在跨集群节点数据同步后，客户端span分析也可以使用此别名元数据直接生成客户端-服务器关系。通过在Apache SkyWalking中使用这些新模型和方法，我们不再依赖基于时间窗口的分析方法，在低于5秒延迟的条件下，准备地进行拓扑图分覅。
+
+
+# Span Model(新的跨度模型)和Context Mode(上下文模型)
+
+跟踪系统的传统范围包括以下字段[1] [6] [10]。
+* Trace ID，代表整个跟踪。
+* Span ID,代表当前span。
+* 一个operation name，描述此span执行的操作。
+* start timestamp(开始时间戳)。
+* finish timestamp(完成时间戳)。
+* 当前Span的Service和Service Instance名称。
+* 一组零个或多个键值对组成的的span tag。
+* 一组零个或多个span日志，每个span日志本身就是与时间戳配对的key：value映射。
+* 引用零个或多个因果相关的span。参考包括parent span id和trace id。
+
+在STAM的新span模型中，我们在span中添加以下字段。
+
+**Span type**(跨度类型): 枚举类型,Exit，Local和Entry。Entry和Local适用于网络相关的库中。输入范围代表服务器端网络库，例如Apache Tomcat [7]。Exit spans代表客户端网络库，例如Apache HttpComponents [8]。
+
+**Peer Network Address**:(对端网络地址): 远程“Address”，适用于exit和entry的span。在“Exit spans”中，对端网络地址是客户端库访问服务器的地址。通常，这个字段通常在许多跟踪系统中是可选的。但是在STAM中，我们在所有RPC情况下都需要它们。
+
+**Context Model**(上下文模型):用于将客户端信息传播到原始RPC调用所携带的服务器端，通常在header（例如HTTP header或MQ header）中传播。在旧的设计中，它带有客户端span的Trace ID和Span ID。在STAM中，我们增强了此模型，添加了父服务名称，parent service instance name(父服务实例名称)和peer of exit span.(出口范围的对等点)。名称可以是文字字符串。所有这些额外的字段将有助于消除流分析的障碍。与现有的上下文模型相比，它使用更多的带宽，但是可以对其进行优化。在Apache SkyWalking中，我们设计了一种注册机制来交换代表这些名称的唯一ID。结果，在RPC上下文中仅添加了3个整数，因此在生产环境中带宽的增加至少小于1％。
+
+两种模型的变化可以消除分析过程中的时间窗口。Server-side span分析增强了上下文感知能力。
+
+# 新的拓扑分析方法
+
+STAM核心的新拓扑分析方法是以流模式处理span。server-side span（也称为entry span）的分析针对包括parent service name(父服务名称)，parent service instance name(父服务实例名称)和exit span的peer信息。因此，分析过程可以得出以下结果。
+
+1. 使用exit span的peer做为当前服务和实例的别名。创建`Peer network address <-> service name`和`peer network address <-> Service instance name`别名。这两个将与所有分析节点同步并保存在存储中，从而允许更多分析处理者拥有此别名信息。
+
+2. 生成`parent service name -> current service name`和`parent service instance name -> current service instance name`两种关系数据，除非发现当前已经存在还有另外一个不同的`Peer network address <-> Service Instance Name`映射关系。在这种情况下，仅生成`peer network address <-> service name`的关系和`peer network address <-> Service instance name`的关系。
+
+为了分析client-side span（exit span），可能存在三种可能性。
+
+1. exit span中的对等方已经具有从步骤（1）进行的服务器端范围分析所建立的别名。然后使用别名来代替peer信息，并产生的流量`current service name -> alias service name`和`current service instance name -> alias service instance name`。
+
+2. 如果找不到别名，那么只需为`current service name -> peer`和`current service instance name -> peer`生成流量。
+
+3. 如果`peer network address <-> Service Instance Name`可以找到的多个别名，则继续为`current service name -> peer network address`和`current service instance name -> peer network address`生成流量。
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-topo-in-apache-skywalking.png"/>
+<br/>
+图2，Apache SkyWalking使用STAM来检测和可视化分布式系统的拓扑。
+</p>
+
+# 评价
+
+在本节中，我们将在几种典型情况下评估新模型和分析方法，在这些情况下，旧方法会失去及时性和一致的准确性。
+
+
+- 1. **在线新服务或自动扩展**
+
+新的服务可以由开发团队随机地添加到整个拓扑中，也可以通过某种扩展策略自动将容器操作平台添加到整个拓扑中，例如Kubernetes [5]。在任何情况下都无法手动通知监视系统。通过使用STAM，我们可以自动检测新节点，并保持分析过程畅通无阻，并与检测到的节点保持一致。在这种情况下，将使用新的服务和网络地址（可以是IP，端口或两者）。`peer network address <-> service`映射不存在，将首先生成`client service -> peer network address`的流量并将其持久化在存储中。生成映射后，可以在分析平台中识别，生成和聚合客户端服务到服务器服务的其他流量。为了在生成映射之前填补一些流量的空白，我们要求在查询阶段再次进行`peer network address <-> service`映射转换，以将`client service->peer network address`和client-service合并到server-service。在生产中，整个SkyWalking分析平�
��部署的VM数量少于100，在它们之间的同步将完 [...]
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-span-analysis.png"/>
+<br/>
+图3，使用新的拓扑分析方法进行span分析
+</p>
+
+
+- 2. **现有未配置节点**
+
+在这种情况下，每种拓扑检测方法都必须起作用。在许多情况下，生产环境中存在无法被监控的节点。其原因可能包括：（1）技术限制。在某些使用golang或C ++编写的应用程序中，Java或.Net中没有简单的方法来由代理进行自动检测。因此，可能不会自动检测代码。（2）MQ，数据库服务器等中间件未采用跟踪系统。分布式追踪这些中间件是非常耗时或者时间困难的。（3）第三方服务或云服务不支持当前跟踪系统的工作。（4）缺乏资源：例如，开发人员或操作团队缺乏时间完成探针安装或者修改代码。
+
+即使客户端或服务器端没有探针，STAM也可以正常工作。它仍然保持拓扑尽可能准确。
+
+如果未安装客户端探针，则server-side span将不会通过RPC上下文获得任何引用，因此，它将仅使用peer来生成流量，如图4所示。
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-no-client-instrumentation.png"/>
+<br/>
+图4，没有客户端探针时的STAM流量生成
+</p>
+
+
+如图5所示，在另一种情况下，由于没有server-side span，因此client span分析不需要处理这种情况。STAM分析核心只是简单地不断生成`client service->peer network address`。由于没有生成的peer network address的映射，因此没有合并。
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-no-server-instrumentation.png"/>
+<br/>
+图5，没有服务器端探针时的STAM流量生成
+</p>
+
+- 3. **具有报头转发能力的未配置节点**
+
+除了我们在（2）未配置节点中评估的情况外，还有一种复杂而特殊的情况：被检测的节点具有将header从下游传播到上游的能力，通常在所有代理中，例如Envoy [11]，Nginx [12] ]，Spring Cloud Gateway [13]。作为代理，它具有将所有header从下游转发到上游的功能，以将某些信息保留在header中，包括tracing上下文，身份验证信息，浏览器信息和路由信息，以使它们可被位于proxy后面的业务服务访问，例如Envoy路由配置[14]。当无论什么原因，某些代理无法安装探针时，它都不应该会影响拓扑检测。
+
+在这种情况下， proxy address在客户端使用，并通过RPC上下文作为peer network address，并且代理将其转发到其他上游服务。然后，STAM可以检测到这种情况并生成代理作为推测节点。在STAM中，应为此网络地址生成多个别名。在检测到这两个并同步到分析节点之后，分析核心知道客户端和服务器之间至少有一个未配置的服务。因此，它将生成`client service->peer network address`，`peer->server service B`和`peer network address->server service C`的关系，如图6所示。。
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-uninstrumentation-proxy.png"/>
+<br/>
+图6，代理无法被监控时，STAM流量的生成
+</p>
+
+# 结论
+这个论文介绍了STAM，据我们所知，STAM是分布式跟踪系统的最佳拓扑检测方法。它取代了基于时间窗口的拓扑分析方法，用于基于跟踪的监视系统。它永久和完全地消除了，使用基于时间窗口分析方法中的磁盘和内存资源成本，并消除了水平扩展的障碍。Apache SkyWalking是一个STAM实现，被广泛用于监视生产中的数百个应用程序。其中一些每天生成超过100 TB的跟踪数据，并为200多种服务实时生成拓扑。
+
+# 致谢
+我们感谢Apache SkyWalking项目的所有贡献者，感谢他们对此分析模型提出的建议，实现STAM的代码贡献以及在生产环境中使用STAM和SkyWalking，并提供反馈。
+
+# 许可证
+这篇论文和STAM使用Apache 2.0许可协议
+
+# 参考文献
+1. Dapper, a Large-Scale Distributed Systems Tracing Infrastructure, https://research.google.com/pubs/pub36356.html?spm=5176.100239.blogcont60165.11.OXME9Z
+1. Apache SkyWalking, http://skywalking.apache.org/
+1. Apache Open Users, https://github.com/apache/skywalking/blob/master/docs/powered-by.md
+1. Zipkin, https://zipkin.io/
+1. Kubernetes, Production-Grade Container Orchestration. Automated container deployment, scaling, and management. https://kubernetes.io/
+1. OpenTracing Specification https://github.com/opentracing/specification/blob/master/specification.md
+1. Apache Tomcat, http://tomcat.apache.org/
+1. Apache HttpComponents, https://hc.apache.org/
+1. Zipkin doc, ‘Instrumenting a library’ section, ‘Communicating trace information’ paragraph. https://zipkin.io/pages/instrumenting
+1. Jaeger Tracing, https://jaegertracing.io/
+1. Envoy Proxy, http://envoyproxy.io/
+1. Nginx, http://nginx.org/
+1. Spring Cloud Gateway, https://spring.io/projects/spring-cloud-gateway
+1. Envoy Route Configuration, https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/rds.proto.html?highlight=request_headers_to_
diff --git a/docs/en/papers/stam.md b/docs/en/papers/stam.md
new file mode 100644
index 0000000..087fdff
--- /dev/null
+++ b/docs/en/papers/stam.md
@@ -0,0 +1,156 @@
+# STAM: Enhancing Topology Auto Detection For A Highly Distributed and Large-Scale Application System
+
+- Sheng Wu 吴 晟
+- wusheng@apache.org
+
+[](stam-cn.md)
+
+### Editor's note
+This paper was written by Sheng Wu, project founder, in 2017, to describe the fundamental theory of all current
+agent core concepts.
+Readers could learn why SkyWalking agents are significantly different from other tracing system and
+Dapper[1] Paper's description.
+
+# Abstract
+Monitoring, visualizing and troubleshooting a large-scale distributed system is a major challenge. One common tool used today is the distributed tracing system (e.g., Google Dapper)[1], and detecting topology and metrics based on the tracing data. One big limitation of today’s topology detection is that the analysis depends on aggregating the client-side and server-side tracing spans in a given time window to generate the dependency of services. This causes more latency and memory use, b [...]
+
+In this paper, we present the STAM, Streaming Topology Analysis Method. In STAM, we could use auto instrumentation or a manual instrumentation mechanism to intercept and manipulate RPC at both client-side and server-side. In the case of auto instrumentation, STAM manipulates application codes at runtime, such as Java agent. As such, this monitoring system doesn’t require any source code changes from the application development team or RPC framework development team. The STAM injects an R [...]
+
+The STAM has been implemented in the Apache SkyWalking[2], an open source APM (application performance monitoring system) project of the Apache Software Foundation, which is widely used in many big enterprises[3] including Alibaba, Huawei, Tencent, Didi, Xiaomi, China Mobile and other enterprises (airlines, financial institutions and others) to support their large-scale distributed systems in the production environment. It reduces the load and memory cost significantly, with better horiz [...]
+
+# Introduction
+Monitoring the highly distributed system, especially with a micro-service architecture, is very complex. Many RPCs, including HTTP, gRPC, MQ, Cache, and Database accesses, are behind a single client-side request. Allowing the IT team to understand the dependency relationships among thousands of services is the key feature and first step for observability of a whole distributed system. A distributed tracing system is capable of collecting traces, including all distributed request paths. [...]
+
+Strong timeliness is required to match the mutability of distributed application system dependency relationship, including service level and service instance level dependency.
+
+A Service is a logic group of instances which have the same functions or codes.
+
+A Service Instance is usually an OS level process, such as a JVM process. The relationships between services and instances are mutable, depending on the configuration, codes and network status. The dependency could change over time.
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/dapper-span.png"/>
+<br/>
+Figure 1, Generated spans in traditional Dapper based tracing system.
+</p>
+
+The span model in the Dapper paper and existing tracing systems，such as Zipkin instrumenting mode[9], just propagates the span id to the server side. Due to this model,
+dependency analysis requires a certain time window. The tracing spans are collected at both client- and server-sides, because the relationship is recorded. Due to that, the analysis process has to wait for the client and server spans to match in the same time window, in order to output the result, Service A depending on Service B. So, this time window must be over the duration of this RPC request; otherwise, the conclusion will be lost. This condition makes the analysis would not react [...]
+Also, because of the Windows-based design, if one side involves a long duration task, it can’t easily achieve consistent accuracy. Because in order to make the analysis as fast as possible, the analysis period is less than 5 minutes. But some spans can’t match its parent or children if the analysis is incomplete or crosses two time windows. Even if we added a mechanism to process the spans left in the previous stages, still some would have to be abandoned to keep the dataset size and me [...]
+
+In the STAM, we introduce a new span and context propagation models, with the new analysis method. These new models add the peer network address (IP or hostname) used at client side, client service instance name and client service name, into the context propagation model. Then it passes the RPC call from client to server, just as the original trace id and span id in the existing tracing system, and collects it in the server-side span. The new analysis method can easily generate the clien [...]
+
+# New Span Model and Context Model
+The traditional span of a tracing system includes the following fields [1][6][10].
+- A trace id to represent the whole trace.
+- A span id to represent the current span.
+- An operation name to describe what operation this span did.
+- A start timestamp.
+- A finish timestamp
+- Service and Service Instance names of current span.
+- A set of zero or more key:value Span Tags.
+- A set of zero or more Span Logs, each of which is itself a key:value map paired with a timestamp.
+- References to zero or more causally related Spans. Reference includes the parent span id and trace id.
+
+In the new span model of STAM we add the following fields in the span.
+
+**Span type**. Enumeration, including exit, local and entry. Entry and Exit spans are used in a networking related library. Entry spans represent a server-side networking library, such as Apache Tomcat[7]. Exit spans represent the client-side networking library, such as Apache HttpComponents [8].
+
+**Peer Network Address**. Remote "address," suitable for use in exit and entry spans. In Exit spans, the peer network address is the address by the client library to access the server.
+
+These fields usually are optionally included in many tracing system,. But in STAM, we require them in all RPC cases.
+
+**Context Model** is used to propagate the client-side information to server-side carried by the original RPC call, usually in the header, such as HTTP header or MQ header. In the old design, it carries the trace id and span id of client-side span. In the STAM, we enhance this model, adding the parent service name, parent service instance name and peer of exit span. The names could be literal strings. All these extra fields will help to remove the block of streaming analysis. Compared to [...]
+
+The changes of two models could eliminate the time windows in the analysis process. Server-side span analysis enhances the context aware capability.
+
+# New Topology Analysis Method
+The new topology analysis method at the core of STAM is processing the span in stream mode.
+The analysis of the server-side span, also named entry span, includes the parent service name, parent service instance name and peer of exit span. So the analysis process could establish the following results.
+1. Set the peer of exit span as client using alias name of current service and instance. `Peer network address <-> service name` and `peer network address <-> Service instance name` aliases created. These two will sync with all analysis nodes and persistent in the storage, allowing more analysis processers to have this alias information.
+2. Generate relationships of `parent service name -> current service name` and `parent service instance name -> current service instance name`, unless there is another different `Peer network address <-> Service Instance Name` mapping found. In that case, only generate relationships of `peer network address <-> service name` and `peer network address <-> Service instance name`.
+
+For analysis of the client-side span (exit span), there could three possibilities.
+1. The peer in the exit span already has the alias names established by server-side span analysis from step (1). Then use alias names to replace the peer, and generate traffic of `current service name -> alias service name` and `current service instance name -> alias service instance name`.
+2. If the alias could not be found, then just simply generate traffic for `current service name -> peer` and `current service instance name -> peer`.
+3. If multiple alias names of `peer network address <-> Service Instance Name` could be found, then keep generating traffic for `current service name -> peer network address` and `current service instance name -> peer network address`.
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-topo-in-apache-skywalking.png"/>
+<br/>
+Figure 2, Apache SkyWalking uses STAM to detect and visualize the topology of distributed systems.
+</p>
+
+# Evaluation
+In this section, we evaluate the new models and analysis method in the context of several typical cases in which the old method loses timeliness and consistent accuracy.
+
+- 1.**New Service Online or Auto Scale Out**
+
+New services could be added into the whole topology by the developer team randomly, or container operation platform automatically by some scale out policy, like Kubernetes [5]. The monitoring system could not be notified in any case manually. By using STAM, we could detect the new node automatically and also keep the analysis process unblocked and consistent with detected nodes.
+In this case, a new service and network address (could be IP, port or both) are used. The peer network address <-> service mapping does not exist, the traffic of client service -> peer network address will be generated and persistent in the storage first. After mapping is generated, further traffic of client-service to server-service could be identified, generated and aggregated in the analysis platform. For filling the gap of a few traffic before the mapping generated, we require doing [...]
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-span-analysis.png"/>
+<br/>
+Figure 3, Span analysis by using the new topology analysis method
+</p>
+
+- 2.**Existing Uninstrumented Nodes**
+
+Every topology detection method has to work in this case. In many cases, there are nodes in the production environment that can’t be instrumented. Causes for this might include:(1) Restriction of the technology. In some golang or C++ written applications, there is no easy way in Java or .Net to do auto instrumentation by the agent. So, the codes may not be instrumented automatically. (2) The middleware, such as MQ, database server, has not adopted the tracing system. This would make it d [...]
+
+The STAM works well even if the client or server side has no instrumentation. It still keeps the topology as accurate as possible.
+
+If the client side hasn’t instrumented, the server-side span wouldn’t get any reference through RPC context, so, it would simply use peer to generate traffic, as shown in Figure 4.
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-no-client-instrumentation.png"/>
+<br/>
+Figure 4, STAM traffic generation when no client-side instrumentation
+</p>
+
+As shown in Figure 5, in the other case, with no server-side instrumentation, the client span analysis doesn’t need to process this case. The STAM analysis core just simply keeps generating client service->peer network address traffic. As there is no mapping for peer network address generated, there is no merging.
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-no-server-instrumentation.png"/>
+<br/>
+Figure 5, STAM traffic generation when no server-side instrumentation
+</p>
+
+- 3.**Uninstrumented Node Having Header Forward Capability**
+
+Besides the cases we evaluated in (2) Uninstrumented Nodes, there is one complex and special case: the instrumented node has the capability to propagate the header from downstream to upstream, typically in all proxy, such as Envoy[11], Nginx[12], Spring Cloud Gateway[13]. As proxy, it has the capability to forward all headers from downstream to upstream to keep some of information in the header, including the tracing context, authentication, browser information, and routing information, [...]
+
+In this case, the proxy address would be used at the client side and propagate through RPC context as peer network address, and the proxy forwards this to different upstream services. Then STAM could detect this case and generate the proxy as a conjectural node. In the STAM, more than one alias names for this network address should be generated. After those two are detected and synchronized to the analysis node, the analysis core knows there is at least one uninstrumented service standin [...]
+
+<p align="center">
+<img src="https://skywalking.apache.org/papers/STAM/STAM-uninstrumentation-proxy.png"/>
+<br/>
+Figure 6, STAM traffic generation when the proxy uninstrumentatio
+</p>
+
+# Conclusion
+
+This paper described the STAM, which is to the best of our knowledge the best topology detection method for distributed tracing systems. It replaces the time-window based topology analysis method for tracing-based monitoring systems. It removes the resource cost of disk and memory for time-window baseds analysis permanently and totally, and the barriers of horizontal scale. One STAM implementation, Apache SkyWalking, is widely used for monitoring hundreds of applications in production. S [...]
+
+# Acknowledgments
+We thank all contributors of Apache SkyWalking project for suggestions, code contributions to implement the STAM, and feedback from using the STAM and SkyWalking in their production environment.
+
+# License
+This paper and the STAM are licensed in the [Apache 2.0](LICENSE)
+
+# References
+
+1. Dapper, a Large-Scale Distributed Systems Tracing Infrastructure, https://research.google.com/pubs/pub36356.html?spm=5176.100239.blogcont60165.11.OXME9Z
+1. Apache SkyWalking, http://skywalking.apache.org/
+1. Apache Open Users, https://github.com/apache/skywalking/blob/master/docs/powered-by.md
+1. Zipkin, https://zipkin.io/
+1. Kubernetes, Production-Grade Container Orchestration. Automated container deployment, scaling, and management. https://kubernetes.io/
+1. OpenTracing Specification https://github.com/opentracing/specification/blob/master/specification.md
+1. Apache Tomcat, http://tomcat.apache.org/
+1. Apache HttpComponents, https://hc.apache.org/
+1. Zipkin doc, ‘Instrumenting a library’ section, ‘Communicating trace information’ paragraph. https://zipkin.io/pages/instrumenting
+1. Jaeger Tracing, https://jaegertracing.io/
+1. Envoy Proxy, http://envoyproxy.io/
+1. Nginx, http://nginx.org/
+1. Spring Cloud Gateway, https://spring.io/projects/spring-cloud-gateway
+1. Envoy Route Configuration, https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/rds.proto.html?highlight=request_headers_to_
diff --git a/docs/menu.yml b/docs/menu.yml
index 7873289..7cd6116 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -36,6 +36,8 @@ catalog:
path: "/en/concepts-and-designs/manual-sdk"
- name: "Service Mesh probe"
path: "/en/concepts-and-designs/service-mesh-probe"
+ - name: "STAM Paper, Streaming Topology Analysis Method"
+ path: "/en/papers/stam"
- name: "Backend"
catalog:
- name: "Overview"
@@ -187,6 +189,8 @@ catalog:
path: "/en/protocols/readme"
- name: "Query Protocol (GraphQL)"
path: "/en/protocols/query-protocol"
+ - name: "Academy"
+ path: "en/academy/list"
- name: "FAQs"
path: "/en/FAQ/readme"
- name: "Changelog"