This is an automated email from the ASF dual-hosted git repository.
albumenj pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new 203407286f docs: update tracing doc (#2584)
203407286f is described below
commit 203407286f10df404ec96d12f4ba327cf17cba87
Author: conghuhu <[email protected]>
AuthorDate: Mon May 8 07:47:07 2023 +0800
docs: update tracing doc (#2584)
* docs: modify tracing docs
* docs: update tracing doc
---
.../overview/tasks/observability/tracing/_index.md | 94 ++++++++++++
.../overview/tasks/observability/tracing/zipkin.md | 157 ++++++++++-----------
2 files changed, 166 insertions(+), 85 deletions(-)
diff --git a/content/zh-cn/overview/tasks/observability/tracing/_index.md
b/content/zh-cn/overview/tasks/observability/tracing/_index.md
index 6b41cd9744..28ce747df8 100755
--- a/content/zh-cn/overview/tasks/observability/tracing/_index.md
+++ b/content/zh-cn/overview/tasks/observability/tracing/_index.md
@@ -41,3 +41,97 @@ weight: 2
<hr>
</div>
{{< /blocks/section >}}
+
+## 说明
+
+目前 Dubbo 内置了 [Micrometer](https://micrometer.io/)（Micrometer
为最流行的可观察性系统在检测客户端上提供了一个统一的门面，相当于日志领域的SLF4J，SpringBoot3 内置的可观测门面组件）。
+
+## Tracing相关概念
+
+- Span：基本工作单元。例如，发送 RPC 是一个新的 span，发送对 RPC
的响应也是如此。Span还有其他数据，例如description、带时间戳的事件、键值注释（标签）、导致它们的跨度的 ID 和进程 ID（通常是 IP
地址）。跨度可以启动和停止，并且它们会跟踪它们的时间信息。创建跨度后，您必须在将来的某个时间点停止它。
+
+- Trace：一组形成树状结构的跨度。例如，如果您运行分布式大数据存储，则可能会通过请求形成跟踪PUT。
+
+- Annotation/Event : 用于及时记录一个事件的存在。
+
+- Tracing context：为了使分布式跟踪工作，跟踪上下文（跟踪标识符、跨度标识符等）必须通过进程（例如通过线程）和网络传播。
+
+- Log
correlation：部分跟踪上下文（例如跟踪标识符、跨度标识符）可以填充到给定应用程序的日志中。然后可以将所有日志收集到一个存储中，并通过跟踪 ID
对它们进行分组。这样就可以从所有按时间顺序排列的服务中获取单个业务操作（跟踪）的所有日志。
+
+- Latency analysis tools：一种收集导出跨度并可视化整个跟踪的工具。允许轻松进行延迟分析。
+
+- Tracer: 处理span生命周期的库（Dubbo 目前支持 Opentelemetry 和 Brave）。它可以通过 Exporter
创建、启动、停止和报告 Spans 到外部系统（如 Zipkin、Jagger 等）。
+
+- Exporter: 将产生的 Trace 信息通过 http 等接口上报到外部系统，比如上报到 Zipkin。
+
+## SpringBoot Starters
+
+对于 SpringBoot 用户，Dubbo 提供了 Tracing 相关的 starters，自动装配 Micrometer
相关的配置代码，且用户可自由选择 Tracer 和Exporter。
+
+### Opentelemetry 作为 Tracer，将 Trace 信息 export 到 Zipkin
+
+```yml
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-spring-boot-tracing-otel-zipkin-starter</artifactId>
+ <version>${version}</version>
+ </dependency>
+```
+
+### Brave 作为 Tracer，将 Trace 信息 export 到 Zipkin
+
+```yml
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-spring-boot-tracing-brave-zipkin-starter</artifactId>
+ <version>${version}</version>
+ </dependency>
+```
+
+### 自由组装 Tracer 和 Exporter
+
+如果用户基于 Micrometer 有自定义的需求，想将 Trace 信息上报至其他外部系统观测，可参照如下自由组装 Tracer 和 Exporter：
+
+```yml
+ <!-- 自动装配 -->
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-spring-boot-observability-starter</artifactId>
+ <version>${version}</version>
+ </dependency>
+ <!-- otel作为tracer -->
+ <dependency>
+ <groupId>io.micrometer</groupId>
+ <artifactId>micrometer-tracing-bridge-otel</artifactId>
+ <version>${version}</version>
+ </dependency>
+ <!-- export到zipkin -->
+ <dependency>
+ <groupId>io.opentelemetry</groupId>
+ <artifactId>opentelemetry-exporter-zipkin</artifactId>
+ <version>${version}</version>
+ </dependency>
+```
+
+```yml
+ <!-- 自动装配 -->
+ <dependency>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-spring-boot-observability-starter</artifactId>
+ <version>${version}</version>
+ </dependency>
+ <!-- brave作为tracer -->
+ <dependency>
+ <groupId>io.micrometer</groupId>
+ <artifactId>micrometer-tracing-bridge-brave</artifactId>
+ <version>${version}</version>
+ </dependency>
+ <!-- export到zipkin -->
+ <dependency>
+ <groupId>io.zipkin.reporter2</groupId>
+ <artifactId>zipkin-reporter-brave</artifactId>
+ <version>${version}</version>
+ </dependency>
+```
+
+后续还会补齐更多的 starters，如 Jagger、SkyWalking等。
diff --git a/content/zh-cn/overview/tasks/observability/tracing/zipkin.md
b/content/zh-cn/overview/tasks/observability/tracing/zipkin.md
index 95752c5920..4ef8731ce8 100644
--- a/content/zh-cn/overview/tasks/observability/tracing/zipkin.md
+++ b/content/zh-cn/overview/tasks/observability/tracing/zipkin.md
@@ -9,11 +9,13 @@ type: docs
weight: 1
---
-这个示例演示了 Dubbo 集成 Zipkin 全链路追踪的基础示例，此示例共包含三部分内容：
+这个示例演示了 SpringBoot 项目中 Dubbo 集成 Zipkin 全链路追踪的基础示例，此示例共包含三部分内容：
+
* dubbo-samples-spring-boot3-tracing-provider
* dubbo-samples-spring-boot3-tracing-consumer
* dubbo-samples-spring-boot3-tracing-interface
+[案例代码地址](https://github.com/apache/dubbo-samples/tree/master/4-governance/dubbo-samples-spring-boot3-tracing)
## 快速开始
@@ -49,121 +51,106 @@ docker run -d -p 9411:9411 --name zipkin openzipkin/zipkin
-## 如何在项目中使用 Dubbo Tracing
+## 如何在SpringBoot项目中使用 Dubbo Tracing
-### 1. 添加 Micrometer Observation 依赖
+### 1. 添加 Dubbo Tracing 相关的 Starter 依赖
-首先需要添加 `dubbo-metrics-api` 依赖将 Micrometer 和 Dubbo Metrics 引入项目中：
+从下面两个 starter 中选择一个加入到你的项目中，区别在于 Tracer 的选型不一样，一个是 Opentelemetry，一个是 Brave：
```xml
+<!-- Opentelemetry as Tracer, Zipkin as exporter -->
<dependency>
<groupId>org.apache.dubbo</groupId>
- <artifactId>dubbo-metrics-api</artifactId>
+ <artifactId>dubbo-spring-boot-tracing-otel-zipkin-starter</artifactId>
</dependency>
```
-通过集成 [Micrometer Observations](https://micrometer.io/) Dubbo
可以在只被拦截一次的情况下，导出多种不同类型的监控指标如 Metrics、Tracer、其他一些信号等，这具体取决于你对
`ObservationHandlers` 的配置。 可以参考以下链接 [documentation under
docs/observation](https://micrometer.io) 了解更多内容。
-
-### 2. 配置 Micrometer Tracing Bridge
-
-为了启用 Dubbo 全链路追踪统计，需要为 Micrometer Tracing 和实际的 Tracer（本示例中的 Zipkin）间配置
`bridge`。
-
-> 注意：Tracer 是一个管控 span 生命周期的二进制包，比如 span 的 创建、终止、采样、上报等。
-
-Micrometer Tracing 支持
[OpenTelemetry](https://github.com/open-telemetry/opentelemetry-java) and
[Brave](https://github.com/openzipkin/brave) 格式的 Tracer。Dubbo 推荐使 OpenTelemetry
作为标准的 tracing 协议，`bridge` 的具体配置如下:
-
-```xml
-<!-- OpenTelemetry Tracer -->
-<dependency>
- <groupId>io.micrometer</groupId>
- <artifactId>micrometer-tracing-bridge-otel</artifactId>
-</dependency>
-```
-
-### 3. 添加 Micrometer Tracing Exporter
-
-添加 Tracer 后，需要继续配置 exporter（也称为 reporter）。exporter 负责导出完成 span 并将其发送到后端
reporter 系统。Micrometer Tracer 原生支持 Tanzu Observability by Wavefront 和 Zipkin。以
Zipkin 为例：
-
```xml
+<!-- Brave as Tracer, Zipkin as exporter -->
<dependency>
- <groupId>io.opentelemetry</groupId>
- <artifactId>opentelemetry-exporter-zipkin</artifactId>
+ <groupId>org.apache.dubbo</groupId>
+ <artifactId>dubbo-spring-boot-tracing-brave-zipkin-starter</artifactId>
</dependency>
```
-你可以在此阅读更多关于 Tracing 的配置信息 [this documentation, under
docs/tracing](https://micrometer.io/).
-
-### 4. 配置 ObservationRegistry
-
-```java
-@Configuration
-public class ObservationConfiguration {
-
- // reuse the applicationModel in your system
- @Bean
- ApplicationModel applicationModel(ObservationRegistry observationRegistry)
{
- ApplicationModel applicationModel = ApplicationModel.defaultModel();
- applicationModel.getBeanFactory().registerBean(observationRegistry);
- return applicationModel;
- }
-
- // zipkin endpoint url
- @Bean
- SpanExporter spanExporter() {
- return new
ZipkinSpanExporterBuilder().setEndpoint("http://localhost:9411/api/v2/spans";).build();
- }
-}
+### 2. 配置
+
+在application.yml中添加如下配置：
+
+```yaml
+dubbo:
+ tracing:
+ enabled: true # 默认为false
+ sampling:
+ probability: 0.5 # 采样率, 默认是 0.1
+ propagation:
+ type: W3C # 传播器类型：W3C/B3 默认是W3C
+ tracing-exporter:
+ zipkin-config:
+ endpoint: http://localhost:9411/api/v2/spans
+ connect-timeout: 1s # 建立连接超时时间, 默认为1s
+ read-timeout: 10s # 传递数据超时时间, 默认为10s
+
+# tracing信息输出到logging
+logging:
+ pattern:
+ level: '%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]'
```
-### 5. 定制 Observation Filters
+## 扩展
-To customize the tags present in metrics (low cardinality tags) and in spans
(low and high cardinality tags) you should
-create your own versions of `DubboServerObservationConvention` (server side)
and `DubboClientObservationConvention` (
-client side) and register them in the `ApplicationModel`'s `BeanFactory`. To
reuse the existing ones
-check `DefaultDubboServerObservationConvention` (server side) and
`DefaultDubboClientObservationConvention` (client
-side).
+### 选择合适的Sender
+Zipkin 的 Sender，是 Exporter
将埋点后的数据进行上报的客户端实现，全部实现可[参考](https://github.com/openzipkin/zipkin-reporter-java)
+Sender 有很多种实现：
-## Extension
+* URLConnectionSender 通过 Java 自带的 HTTP 客户端上报
+* OkHttpSender 通过 OKHttp3 上报
+* KafkaSender 通过 Kafka 消息队列上报
+* ActiveMQSender 通过 ActiveMQ 消息队列上报
+* RabbitMQSender 通过 RabbitMQ 消息队列上报
-### 其他 Micrometer Tracing Bridge
+Dubbo Tracing 相关的 starter 目前默认是使用 OKHttpSender，也支持 URLConnectionSender，如果想通过
URLConnectionSender 向 Zipkin 发送 Spans，可直接在 pom 中添加如下依赖：
```xml
-<!-- Brave Tracer -->
<dependency>
- <groupId>io.micrometer</groupId>
- <artifactId>micrometer-tracing-bridge-brave</artifactId>
+ <groupId>io.zipkin.reporter2</groupId>
+ <artifactId>zipkin-sender-urlconnection</artifactId>
</dependency>
```
+配置 Zipkin 的 endpoint、connectTimeout、readTimeout
+
+```yaml
+dubbo:
+ tracing:
+ enabled: true # 默认为false
+ tracing-exporter:
+ zipkin-config:
+ endpoint: http://localhost:9411/api/v2/spans
+ connect-timeout: 1s # 建立连接超时时间, 默认为1s
+ read-timeout: 10s # 传递数据超时时间, 默认为10s
+```
+如果想使用其他类型的 Sender ，需要用户在项目中手动注入对应的 Bean，并配置对应的属性，如 KafkaSender：
-### 其他 Micrometer Tracing Exporter
-
-Tanzu Observability by Wavefront
-
-```xml
-<dependency>
- <groupId>io.micrometer</groupId>
- <artifactId>micrometer-tracing-reporter-wavefront</artifactId>
-</dependency>
-```
+```java
+@Configuration
+public class KafkaSenderConfiguration {
-OpenZipkin Zipkin with Brave
+ @Bean
+ KafkaSender kafkaSender(){
+ KafkaSender.Builder builder = KafkaSender.newBuilder();
+ builder.bootstrapServers("127.0.0.0.1:9092");
+ builder.topic("zipkin");
+ builder.encoding(Encoding.JSON);
+ return builder.build();
+ }
-```xml
-<dependency>
- <groupId>io.zipkin.reporter2</groupId>
- <artifactId>zipkin-reporter-brave</artifactId>
-</dependency>
+}
```
-An OpenZipkin URL sender dependency to send out spans to Zipkin via a
URLConnectionSender
+### SpringBoot2案例
-```xml
-<dependency>
- <groupId>io.zipkin.reporter2</groupId>
- <artifactId>zipkin-sender-urlconnection</artifactId>
-</dependency>
-```
+dubbo-tracing相关的使用在SpringBoot2与3中区别不大，SpringBoot2的案例可参考[代码地址](https://github.com/apache/dubbo-samples/tree/master/4-governance/dubbo-samples-spring-boot-tracing)。
