docs: update microservices distributed tracing

Author: iluwatar

Diff for: microservices-distributed-tracing/README.md

@@ -2,26 +2,31 @@
 title: "Microservices Distributed Tracing Pattern: Enhancing Visibility in Service Communication"
 shortTitle: Distributed Tracing in Microservices
 description: "Learn how the Distributed Tracing pattern enhances visibility into service communication across microservices. Discover its benefits, implementation examples, and best practices."
-category: Structural
+category: Architectural
 language: en
 tag:
-  - Scalability
+    - Cloud distributed
+    - Microservices
+    - Resilience
+    - Scalability
+    - Observability
+    - System health
 ---
 
 ## Intent of Microservices Distributed Tracing Design Pattern
 
-Distributed tracing aims to monitor and track requests as they flow through different services in a microservices architecture, providing insights into performance, dependencies, and failures.
+Provide a mechanism to trace and correlate requests as they traverse multiple microservices in a distributed system, enabling end-to-end visibility and easier troubleshooting.
 
 ## Also known as
 
 * Distributed Request Tracing
-* End-to-End Tracing
+* End-to-End Microservice Tracing
 
 ## Detailed Explanation of Microservices Distributed Tracing Pattern with Real-World Examples
 
 Real-world example
 
-> In an e-commerce platform, distributed tracing is used to track a customer's request from the moment they add an item to the cart until the order is processed and shipped. This helps in identifying bottlenecks, errors, and latency issues across different services.
+> Imagine an online food delivery platform where one microservice handles user orders, another manages restaurant menus, and yet another coordinates courier assignments. When a user places an order, the request travels through all three services in sequence. By implementing distributed tracing, each service attaches a trace identifier to its logs. This allows the operations team to follow the journey of a single order across the entire pipeline, identify any delays along the way, and quickly pinpoint which service is causing the bottleneck or experiencing an error.
 
 In plain words
 
@@ -31,10 +36,13 @@ Wikipedia says
 
 > Tracing in software engineering refers to the process of capturing and recording information about the execution of a software program. This information is typically used by programmers for debugging purposes, and additionally, depending on the type and detail of information contained in a trace log, by experienced system administrators or technical-support personnel and by software monitoring tools to diagnose common problems with software.
 
-## Programmatic Example of Microservices Distributed Tracing in Java
+Sequence diagram
+
+![Microservices Distributed Tracing Sequence Diagram](./etc/microservices-distributed-tracing-sequence-diagram.png)
 
+## Programmatic Example of Microservices Distributed Tracing in Java
 
-This implementation shows how an e-commerce platform's `OrderService` interacts with both `PaymentService` and `ProductService`. When a customer places an order, the `OrderService` calls the `PaymentService` to process the payment and the `ProductService` to check the product inventory. Distributed tracing logs are generated for each of these interactions and can be viewed in the Zipkin interface to monitor the flow and performance of requests across these services.
+This implementation shows how an e-commerce platform's `OrderService` interacts with both `PaymentService` and `ProductService`. When a customer places an order, the `OrderService` calls the `PaymentService` to process the payment and the `ProductService` to check the product inventory. By adding distributed trace instrumentation (usually via libraries like Spring Cloud Sleuth or OpenTelemetry), each service attaches trace context to outgoing requests and logs. These logs can then be viewed in the Zipkin interface (or other tracing tools, such as Jaeger) to observe the entire flow of the request and quickly identify any performance bottlenecks or failures across multiple services.
 
 Here's the `Order microservice` implementation.
 
@@ -150,25 +158,32 @@ public class ProductController {
 }
 ```
 
-## When to Use the Microservices Distributed Tracing Pattern in Java
+In this example, each microservice would typically be configured with tracing libraries (like Sleuth or OpenTelemetry). The trace context is propagated via HTTP headers, enabling the logs and metrics for each service call to be grouped together and visualized in Zipkin or another compatible tool. This ensures complete end-to-end visibility into each request’s journey.
 
-* When you have a microservices architecture and need to monitor the flow of requests across multiple services.
-* When troubleshooting performance issues or errors in a distributed system.
-* When you need to gain insights into system bottlenecks and optimize overall performance.
+## When to Use the Microservices Distributed Tracing Pattern in Java
 
+* When multiple services form a single user request path and debugging failures requires visibility across service boundaries.
+* When monitoring or diagnosing performance bottlenecks is critical in a multi-service environment.
+* When correlation of logs and metrics from independent services is needed to understand overall system health.
 
 ## Microservices Distributed Tracing Pattern Java Tutorials
 
 * [Spring Boot - Tracing (Spring)](https://docs.spring.io/spring-boot/reference/actuator/tracing.html)
 * [Reactive Observability (Spring Academy)](https://spring.academy/guides/microservices-observability-reactive-spring-boot-3)
 * [Spring Cloud – Tracing Services with Zipkin (Baeldung)](https://dzone.com/articles/getting-started-with-spring-cloud-gateway)
 
+## Real-World Applications of Microservices Distributed Tracing Pattern in Java
+
+* OpenTelemetry for tracing instrumentation in Java services.
+* Spring Cloud Sleuth for automatic tracing in Spring Boot microservices.
+* Jaeger and Zipkin for collecting and visualizing distributed traces in Java-based systems.
+
 ## Benefits and Trade-offs of Microservices Distributed Tracing Pattern
 
 Benefits:
 
-* Provides end-to-end visibility into requests.
-* Helps in identifying performance bottlenecks.
+* Centralized insight into request paths across services, reducing time to diagnose issues.
+* Improved observability enables proactive identification of system bottlenecks.
 * Aids in debugging and troubleshooting complex systems.
 
 Trade-offs:
@@ -177,20 +192,17 @@ Trade-offs:
 * Requires additional infrastructure (e.g., Zipkin, Jaeger) for collecting and visualizing traces.
 * Can become complex to manage in large-scale systems.
 
-## Real-World Applications of Microservices Distributed Tracing Pattern in Java
-
-* Monitoring and troubleshooting e-commerce platforms.
-*  Performance monitoring in financial transaction systems.
-*  Observability in large-scale SaaS applications.
-
 ## Related Java Design Patterns
 
-* [Log Aggregation Microservice](https://java-design-patterns.com/patterns/microservices-log-aggregation/) - Distributed tracing works well in conjunction with log aggregation to provide comprehensive observability and troubleshooting capabilities.
-* [Circuit Breaker](https://java-design-patterns.com/patterns/circuit-breaker/) - Distributed tracing can be used alongside the Circuit Breaker pattern to monitor and handle failures gracefully, preventing cascading failures in microservices.
-* [API Gateway Microservice](https://java-design-patterns.com/patterns/microservices-api-gateway/) - The API Gateway pattern can be integrated with distributed tracing to provide a single entry point for tracing requests across multiple microservices.
+* [API Gateway Microservice](https://java-design-patterns.com/patterns/microservices-api-gateway/): Acts as an entry point to microservices and can propagate trace information to downstream services.
+* [Circuit Breaker](https://java-design-patterns.com/patterns/circuit-breaker/): Distributed tracing can be used alongside the Circuit Breaker pattern to monitor and handle failures gracefully, preventing cascading failures in microservices.
+* [Log Aggregation Microservice](https://java-design-patterns.com/patterns/microservices-log-aggregation/): Distributed tracing works well in conjunction with log aggregation to provide comprehensive observability and troubleshooting capabilities.
+* [Saga](https://java-design-patterns.com/patterns/saga/): Orchestrates distributed transactions, which benefit from trace identifiers to correlate steps across services.
 
 ## References and Credits
 
 * [Building Microservices](https://amzn.to/3UACtrU)
-* [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
 * [Distributed tracing (microservices.io)](https://microservices.io/patterns/observability/distributed-tracing.html)
+* [Microservices Patterns: With examples in Java](https://amzn.to/3UyWD5O)
+* [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
+* [Release It! Design and Deploy Production-Ready Software](https://amzn.to/3Uul4kF)

Diff for: microservices-distributed-tracing/etc/microservices-distributed-tracing-sequence-diagram.png

@@ -36,7 +36,7 @@ class ProductControllerTest {
   private ProductController productController;
 
   @BeforeEach
-  public void setUp() {
+  void setUp() {
     productController = new ProductController();
   }