openzipkin/example-sleuth-webmvc

跨Spring Boot应用分布式追踪基础示例

镜像概述和主要用途

本示例是两个Spring Boot（Java）服务协作处理HTTP请求的应用，重点在于这些请求的时间会记录到分布式追踪系统Zipkin中。通过此示例，您可以查看整个操作的耗时以及每个服务所花费的时间。

!Zipkin截图

本示例最初是为2016年6月30日的分布式追踪网络研讨会制作的，适合对分布式追踪基础感兴趣的用户。

核心功能和特性

• 自动分布式追踪：使用Spring Cloud Sleuth自动对服务间请求进行追踪
• Zipkin集成：将追踪数据发送至Zipkin，可视化展示请求链路和耗时
• 基础架构：基于Spring MVC控制器处理Web请求，避免异步和负载均衡等高级主题，适合入门学习
• 可扩展性：支持扩展集成多种常用技术（如WebFlux、Apache HttpClient、MySQL、消息队列等）的追踪能力

使用场景和适用范围

• 分布式系统初学者学习分布式追踪基础原理
• Spring Boot微服务架构中追踪请求链路的示例参考
• 理解服务间调用耗时分布的实践演示
• 集成不同技术组件（数据库、消息队列等）追踪能力的参考案例

详细使用方法和配置说明

运行示例

本示例包含两个服务：frontend（前端）和backend（后端），两者均向Zipkin报告追踪数据。启动演示需按以下步骤操作：

1. 启动服务和Zipkin

需在不同终端或窗口分别启动前端服务、后端服务和Zipkin：

启动后端服务：

bash
./mvnw compile exec:java -Dexec.mainClass=sleuth.webmvc.Backend

启动前端服务：

bash
./mvnw compile exec:java -Dexec.mainClass=sleuth.webmvc.Frontend

启动Zipkin：

bash
curl -sSL https://zipkin.io/quickstart.sh | bash -s
java -jar zipkin.jar

2. 访问服务

• 服务启动后，访问前端服务：http://localhost:8081（前端会调用后端服务http://localhost:9000/api，返回格式化日期结果）
• 查看追踪数据：访问Zipkin UI：http://localhost:9411/?serviceName=backend（本地运行的Zipkin服务，内存存储追踪数据）

配置提示

• 服务名配置：Zipkin UI中的服务名默认使用应用名，通过以下配置设置：

  properties
  spring.application.name=frontend  # 前端服务名
  

• 采样率配置：所有入站请求均会被采样，且该决策会向下游传递，配置采样率（1.0表示100%采样）：

  properties
  spring.sleuth.sampler.probability=1.0
  

• 日志格式配置：以下日志格式可在输出中添加追踪ID和跨度ID：

  properties
  logging.pattern.level=%d{ABSOLUTE} [%X{traceId}/%X{spanId}] %-5p [%t] %C{2} - %m%n
  

• 用户头传播：若传递user_name请求头，Brave会自动将其传播至后端：

  bash
  curl -s localhost:8081 -H'user_name: JC'
  

进一步探索

分布式追踪仅包含已配置（ instrumentation ）的连接。若使用未自动配置的库，可参考以下示例集成常用功能：

Spring WebFlux追踪

bash
git checkout add-webflux-tracing

https://github.com/openzipkin/sleuth-webmvc-example/compare/add-webflux-tracing%E5%B0%86%E7%A4%BA%E4%BE%8B%E4%BF%AE%E6%94%B9%E4%B8%BA%E4%BD%BF%E7%94%A8%E5%93%8D%E5%BA%94%E5%BC%8F%60Mono%60%E6%8E%A7%E5%88%B6%E5%99%A8%EF%BC%8C%E5%B9%B6%E9%80%9A%E8%BF%87%60WebClient%60%EF%BC%88%E6%9B%BF%E4%BB%A3%60RestTemplate%60%EF%BC%89%E5%AE%9E%E7%8E%B0%E5%89%8D%E7%AB%AF%E5%88%B0%E5%90%8E%E7%AB%AF%E7%9A%84%E8%B0%83%E7%94%A8%E3%80%82

Apache HttpClient追踪

bash
git checkout add-apachehc-tracing

https://github.com/openzipkin/sleuth-webmvc-example/compare/add-apachehc-tracing%E5%B0%86%E7%A4%BA%E4%BE%8B%E4%BF%AE%E6%94%B9%E4%B8%BA%E4%BD%BF%E7%94%A8Apache HttpClient（替代RestTemplate）实现前端到后端的调用。

MySQL追踪

bash
git checkout add-mysql-tracing

https://github.com/openzipkin/sleuth-webmvc-example/compare/add-mysql-tracing%E5%B0%86%E7%A4%BA%E4%BE%8B%E4%BF%AE%E6%94%B9%E4%B8%BA%E4%BB%8EMySQL%E8%AF%BB%E5%8F%96%E6%97%B6%E9%97%B4%E6%88%B3%EF%BC%88%E6%9B%BF%E4%BB%A3Spring Boot进程内时间），并添加Brave追踪拦截器以丰富现有追踪详情。

RabbitMQ追踪

bash
git checkout add-rabbit-tracing

https://github.com/openzipkin/sleuth-webmvc-example/compare/add-rabbit-tracing%E5%B0%86%E7%A4%BA%E4%BE%8B%E4%BF%AE%E6%94%B9%E4%B8%BA%E4%BD%BF%E7%94%A8RabbitMQ%EF%BC%88%E6%9B%BF%E4%BB%A3WebMVC%EF%BC%89%E8%B0%83%E7%94%A8%E5%90%8E%E7%AB%AF%EF%BC%8CSleuth%E4%BC%9A%E8%87%AA%E5%8A%A8%E9%85%8D%E7%BD%AEBrave%E7%9A%84%60spring-rabbit%60%E4%BB%A5%E6%B7%BB%E5%8A%A0%E8%BF%BD%E8%B8%AA%E8%AF%A6%E6%83%85%E3%80%82

Kafka追踪

bash
git checkout add-kafka-tracing

https://github.com/openzipkin/sleuth-webmvc-example/compare/add-kafka-tracing%E5%B0%86%E7%A4%BA%E4%BE%8B%E4%BF%AE%E6%94%B9%E4%B8%BA%E4%BD%BF%E7%94%A8Kafka%EF%BC%88%E6%9B%BF%E4%BB%A3WebMVC%EF%BC%89%E8%B0%83%E7%94%A8%E5%90%8E%E7%AB%AF%EF%BC%8C%E5%BD%93%60spring-kafka%60%E5%AD%98%E5%9C%A8%E6%97%B6%EF%BC%8CSleuth%E4%BC%9A%E8%87%AA%E5%8A%A8%E9%85%8D%E7%BD%AEBrave%E7%9A%84%60kafka-clients%60 instrumentation。

其他技术追踪

还支持JMS、Dubbo、Java Flight Recorder、OpenTracing等技术的追踪集成，具体可通过对应git checkout命令查看示例（详见英文原文链接）。

Docker部署

构建Docker镜像

使用以下命令构建包含示例的Docker镜像：

bash
docker build -t openzipkin/example-sleuth-webmvc -f docker/Dockerfile .

运行Docker容器

• 启动后端服务容器：

  bash
  docker run -it --rm -p 9000:9000 openzipkin/example-sleuth-webmvc backend
  

• 启动前端服务容器：

  bash
  docker run -it --rm -p 8081:8081 openzipkin/example-sleuth-webmvc frontend
  

其他资源

Sleuth基于https://github.com/openzipkin/brave%E9%A1%B9%E7%9B%AE%EF%BC%8C%E5%8F%AF%E9%87%8D%E7%94%A8%E4%BB%BB%E4%BD%95%E4%B8%8EBrave%E5%85%BC%E5%AE%B9%E7%9A%84%E4%BB%A3%E7%A0%81%EF%BC%8C%E4%B9%9F%E5%8F%AF%E4%BD%BF%E7%94%A8HTTP%E4%B9%8B%E5%A4%96%E7%9A%84%E4%BC%A0%E8%BE%93%E6%96%B9%E5%BC%8F%E5%90%91Zipkin%E5%85%BC%E5%AE%B9%E6%9C%8D%E5%8A%A1%E5%8F%91%E9%80%81%E6%95%B0%E6%8D%AE%E3%80%82

如需更多帮助，可通过gitter联系我们！<|FCResponseEnd|>===SHORT_DESC=== 展示跨Spring Boot应用分布式追踪的基础示例，通过两个Spring Boot服务协作处理HTTP请求，并使用Zipkin记录追踪数据，便于查看整个操作耗时及各服务耗时情况。 ===FULL_DESC===# 跨Spring Boot应用分布式追踪基础示例

镜像概述和主要用途

本示例是两个Spring Boot（Java）服务协作处理HTTP请求的应用，重点是这些请求的时间会记录到分布式追踪系统Zipkin中。通过此示例，您可以查看整个操作的耗时以及每个服务所花费的时间，是学习分布式追踪基础原理的实用案例。

!Zipkin截图

该示例最初为2016年6月30日的"分布式追踪网络研讨会"制作，适合对微服务延迟分析和分布式追踪感兴趣的开发者入门学习。

核心功能和特性

• 自动追踪集成：Web请求由Spring MVC控制器处理，通过Spring Cloud Sleuth实现自动分布式追踪
• Zipkin数据记录：请求时间数据自动发送至Zipkin，支持可视化查看追踪链路和各服务耗时
• 简化设计：刻意避免异步处理、负载均衡等高级主题，专注基础追踪功能，降低学习门槛
• 可扩展性：支持扩展集成多种常用技术（如WebFlux、Apache HttpClient、MySQL、消息队列等）的追踪能力

使用场景和适用范围

• 分布式系统初学者学习分布式追踪基础原理的实践示例
• Spring Boot微服务架构中实现请求链路追踪的参考模板
• 分析微服务间调用延迟、定位性能瓶颈的基础演示环境
• 验证不同技术组件（数据库、消息中间件等）追踪配置的测试案例

详细使用方法和配置说明

运行示例

本示例包含两个服务：frontend（前端）和backend（后端），两者均向Zipkin报告追踪数据。启动演示需完成以下步骤：

1. 启动服务和Zipkin

需在不同终端或窗口分别启动前端服务、后端服务和Zipkin：

启动后端服务：

bash
./mvnw compile exec:java -Dexec.mainClass=sleuth.webmvc.Backend

启动前端服务：

bash
./mvnw compile exec:java -Dexec.mainClass=sleuth.webmvc.Frontend

启动Zipkin：

bash
curl -sSL https://zipkin.io/quickstart.sh | bash -s
java -jar zipkin.jar

2. 访问和验证

• 访问前端服务：http://localhost:8081（前端会调用后端服务http://localhost:9000/api，返回格式化日期结果）
• 查看追踪数据：访问Zipkin UI：http://localhost:9411/?serviceName=backend（可查看后端服务的追踪记录）

配置提示

• 服务名配置：Zipkin UI中显示的服务名默认对应应用名，配置方式：

  properties
  spring.application.name=frontend  # 前端服务名配置
  

• 采样率配置：控制请求采样比例（1.0表示100%采样），配置后会在服务间传递采样决策：

  properties
  spring.sleuth.sampler.probability=1.0
  

• 日志格式配置：在日志中添加追踪ID和跨度ID，便于关联日志与追踪数据：

  properties
  logging.pattern.level=%d{ABSOLUTE} [%X{traceId}/%X{spanId}] %-5p [%t] %C{2} - %m%n
  

• 用户头传播：通过user_name请求头可自动向后端传递用户信息：

  bash
  curl -s localhost:8081 -H'user_name: JC'  # 传递用户头示例
  

进一步探索

分布式追踪仅覆盖已配置的连接，以下示例展示如何集成常用技术的追踪能力：

Spring WebFlux追踪

bash
git checkout add-webflux-tracing

https://github.com/openzipkin/sleuth-webmvc-example/compare/add-webflux-tracing%EF%BC%9A%E4%BD%BF%E7%94%A8%E5%93%8D%E5%BA%94%E5%BC%8F%60Mono%60%E6%8E%A7%E5%88%B6%E5%99%A8%EF%BC%8C%E9%80%9A%E8%BF%87%60WebClient%60%E6%9B%BF%E4%BB%A3%60RestTemplate%60%E5%AE%9E%E7%8E%B0%E6%9C%8D%E5%8A%A1%E8%B0%83%E7%94%A8%E3%80%82

Apache HttpClient追踪

bash
git checkout add-apachehc-tracing

https://github.com/openzipkin/sleuth-webmvc-example/compare/add-apachehc-tracing%EF%BC%9A%E4%BD%BF%E7%94%A8Apache HttpClient替代RestTemplate实现服务调用。

其他技术追踪

还支持MySQL、RabbitMQ、Kafka、JMS、Dubbo等技术的追踪集成，可通过对应git checkout命令查看示例（详见项目仓库链接）。

Docker部署

构建镜像

bash
docker build -t openzipkin/example-sleuth-webmvc -f docker/Dockerfile .

运行容器

启动后端服务：

bash
docker run -it --rm -p 9000:9000 openzipkin/example-sleuth-webmvc backend

启动前端服务：

bash
docker run -it --rm -p 8081:8081 openzipkin/example-sleuth-webmvc frontend

扩展资源

Sleuth基于https://github.com/openzipkin/brave%E9%A1%B9%E7%9B%AE%EF%BC%8C%E5%8F%AF%E9%87%8D%E7%94%A8%E4%BB%BB%E4%BD%95Brave%E5%85%BC%E5%AE%B9%E4%BB%A3%E7%A0%81%EF%BC%8C%E4%B9%9F%E6%94%AF%E6%8C%81%E9%80%9A%E8%BF%87%E9%9D%9EHTTP%E4%BC%A0%E8%BE%93%E6%96%B9%E5%BC%8F%E5%8F%91%E9%80%81%E6%95%B0%E6%8D%AE%E8%87%B3Zipkin%E5%85%BC%E5%AE%B9%E6%9C%8D%E5%8A%A1%E3%80%82

如需更多帮助，可通过gitter联系社区！