README.md

Basic example showing distributed tracing across Java applications

This is an example app where two Java services collaborate on a request.

Notably, these services send data to Zipkin, a distributed tracing system. Zipkin allows you to see how long the operation took, as well how much time was spent in each service.

Here's an example of what it looks like:

Implementation Overview

This example has two services: frontend and backend. Both are instrumented to send tracing data to a third service Zipkin. Brave performs this function.

Running the example

To set up the demo, you need to start Frontend, Backend and Zipkin. You can do this using Java commands or Docker.

Once the services start, open http://localhost:8081/

• This calls the backend (http://127.0.0.1:9000/api) and shows its result: a formatted date.

Afterward, you can view traces that went through the backend via http://127.0.0.1:9411/zipkin?serviceName=backend

• This is a locally run zipkin service which keeps traces in memory

Tips

There are some interesting details that apply to all examples:

• If you pass the header user_name Brave will automatically propagate it to the backend!
  • curl -s localhost:8081 -H'user_name: JC'
• The below Logback pattern adds trace and span identifiers into log output
  • %d{HH:mm:ss.SSS} [%thread] [%X{userName}] [%X{traceId}/%X{spanId}] %-5level %logger{36} - %msg%n

Example projects

Here are the example projects you can try:

• armeria BRAVE_EXAMPLE=armeria docker compose up

  • Runtime: Armeria, SLF4J 1.7, JRE 21
  • Trace Instrumentation: Armeria, SLF4J
  • Trace Configuration: Brave API Java
  • You can also use Eureka discovery like this:
    • BRAVE_EXAMPLE=armeria docker compose -f docker-compose.yml -f docker-compose-eureka.yml up

• armeria-kafka BRAVE_EXAMPLE=armeria-kafka docker compose -f docker-compose.yml -f docker-compose-kafka.yml up

  • Runtime: Armeria, Kafka Clients and Streams 2.7, SLF4J 1.7, JRE 21
  • Trace Instrumentation: Armeria, Kafka Clients, Kafka Streams, SLF4J
  • Trace Configuration: Brave API Java

• jersey2-cassandra3 BRAVE_EXAMPLE=jersey2-cassandra3 docker compose up

  • Runtime: JaxRS 2, Jersey 2, DataStax Java Driver 3, Apache Cassandra 4, SLF4J 1, JRE 8
  • Trace Instrumentation: Jersey Server, DataStax Java Driver, Apache Cassandra, SLF4J
  • Trace Configuration: Brave API XML

• netty4-grpc BRAVE_EXAMPLE=netty4-grpc docker compose up

  • Runtime: Netty 4.1, Google gRPC 1.63, SLF4J 1.7, JRE 21
  • Trace Instrumentation: Netty Codec HTTP, Google gRPC, SLF4J
  • Trace Configuration: Brave API Java

• webflux5-sleuth BRAVE_EXAMPLE=webflux5-sleuth docker compose up

  • Runtime: Spring 5, Reactor Netty 0.9, Spring Boot 2.3, Spring Cloud Sleuth 2.2, Log4J 2.13, JRE 21
  • Trace Instrumentation: WebFlux Server, WebFlux Client, Reactor Context, SLF4J
  • Trace Configuration: Spring Cloud Sleuth Properties
  • You can also use Eureka discovery like this:
    • BRAVE_EXAMPLE=webflux5-sleuth docker compose -f docker-compose.yml -f docker-compose-eureka.yml up

• webflux6-micrometer BRAVE_EXAMPLE=webflux6-micrometer docker compose up

  • Runtime: Spring 6, Reactor Netty, Spring Boot 3, Micrometer, Log4J 2, JRE 21
  • Trace Configuration: Spring Boot Actuator

• webmvc25-jetty BRAVE_EXAMPLE=webmvc25-jetty docker compose up

  • Runtime: Spring 2.5, Apache HttpClient 4.3, Servlet 2.5, Jetty 7.6, Log4J 1.2, JRE 6
  • Trace Instrumentation: Servlet, Spring MVC, Apache HttpClient, Log4J 1.2
  • Trace Configuration: Brave Spring Beans XML

• webmvc3-jetty BRAVE_EXAMPLE=webmvc3-jetty docker compose up

  • Runtime: Spring 3.2, Apache HttpClient 4.3, Servlet 3.0, Jetty 8.1, Log4J 1.2, JRE 7
  • Trace Instrumentation: Servlet, Spring MVC, Spring Web, Apache HttpClient, Log4J 1.2
  • Trace Configuration: Brave Spring Beans XML

• webmvc4-jetty BRAVE_EXAMPLE=webmvc4-jetty docker compose up

  • Runtime: Spring 4.3, OkHttp 3.12, Jetty 9.2, Servlet 3.1, SLF4J 1.7, JRE 8
  • Trace Instrumentation: Servlet, Spring MVC, Spring Web, OkHttp, SLF4J
  • Trace Configuration: Brave API Spring Java Config

• webmvc4-boot BRAVE_EXAMPLE=webmvc4-boot docker compose up

  • Runtime: Spring 4.3, OkHttp 3.14, Spring Boot 1.5, Servlet 3.1, Jetty 9.4, SLF4J 1.7, JRE 8
  • Trace Instrumentation: Servlet, Spring MVC, Spring Web, OkHttp, SLF4J
  • Trace Configuration: Brave API Spring Boot AutoConfiguration

Starting the services with Docker

Docker Compose is the easiest way to start.

Just run docker compose up.

Armeria starts by default. To use a different version of the project, set the VERSION variable.

Ex. VERSION=webmvc25-jetty docker compose up

Starting the services from source

When not using Docker, you'll need to start services according to the frameworks used.

First, start Zipkin. This stores and queries traces reported by the example services.

Starting Zipkin with Java:

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

Java

In a separate tab or window, start each of brave.example.Frontend and brave.example.Backend.

Ex.

$ cd armeria
$ mvn compile exec:java -Dexec.mainClass=brave.example.Backend
$ mvn compile exec:java -Dexec.mainClass=brave.example.Frontend

Servlet

In a separate tab or window, start a Jetty container for "backend" and "frontend".

Ex.

$ cd webmvc4-jetty
$ mvn jetty:run -Pfrontend
$ mvn jetty:run -Pbackend