Rationale

Spring Cloud Sleuth currently is an autoconfiguration over Brave. It also consists of various instrumentation mechanisms for libraries that are not supported by Brave (e.g. Spring Cloud Circuitbreaker).

We would like to abstract Brave so that Spring Cloud Sleuth becomes an autoconfiguration for any tracer implementation that is compatible with Spring Cloud Sleuth. That way Spring Cloud Sleuth in its core module would consist of an API and various tracer implementations would implement that API which would also allow automatic instrumentation of libraries that are supported by Spring Cloud Sleuth.

OpenTelemetry Support

Thanks to doing this abstraction we are able to support new tracer implementations, not only Brave. We've decided to add support for the OpenTelemetry SDK as the second one. If in the future if we decide to add new tracers then it will be just a matter of adding a new module that bridges to the Spring Cloud Sleuth one. Thanks to abstraction of tests as well we will be easily able to plug that tracer mechanism into our current suite of tests.

Design

In spring-cloud-sleuth-core we have created the new API in the org.springframework.cloud.sleuth.api package. That API was heavily inspired and sometimes literally taken from Brave (we wanted the potential transition to be as easy as possible). In some of the API interfaces we took inspiration from the OpenTelemetry Java API.

The work is still in progress because we want to create an abstraction over the messaging parts.

Changed Modules

spring-cloud-sleuth-core now consists of the API, instrumentation (async, circuitbreaker, messaging (via spring integration), quartz, reactor, rxjava, scheduling and web) and its autoconfiguration. It also consists some common properties and annotation configuration setup (as it used to).

New Modules

New modules were created - spring-cloud-sleuth-brave and spring-cloud-sleuth-otel and spring-cloud-starter-sleuth-otel

In spring-cloud-sleuth-brave we have autoconfigurations for the bridge between Sleuth and Brave and Brave autoconfiguration as such.

In spring-cloud-sleuth-otel we have autoconfigurations for the bridge between Sleuth and OpenTelemetry and OpenTelemetry autoconfiguration as such.

Reorganization of Tests

The tests/common module consists of numerous abstract tests that then would be reused by various tracer implementations to assert whether they are complaint against Spring Cloud Sleuth instrumentation requirements. That way we write test once and we apply configuration for the tracers.

Additional Changes

Multiple Propagation Options

We've added a feature to allow multiple propagation context mechanisms. The spring.sleuth.propagation.type property is a list where you can provide various options such as B3 (the default), but also AWS or W3C. OpenTelemetry also supports JAEGER and OT_TRACER. Of course, you can also provide your own, custom mechanism.

Documentation Rewrite

We've decided to rewrite the documentation to be more consistent with Spring Boot standards (cc @Buzzardo ).

How to Use It / How Does It Affect Me?

If you're a current Spring Cloud Sleuth user you will not see any changes since you will still be using Brave's API directly. If you were using spring-cloud-starter-sleuth dependency you automatically get the Brave tracer implementation. If you used spring-cloud-starter-zipkin only, you need to change it into two dependencies: spring-cloud-sleuth-zipkin and spring-cloud-starter-sleuth.

If you are a new user you should do the following

• Pick which tracer implementation you want to work with (Brave or OpenTelemetry)
• Decide if you want to use Spring Cloud Sleuth's API or the direct tracer's API

If you want to migrate to the Spring Cloud Sleuth API then the migration path should be relatively simple since the API resembles Brave's one a lot.

Breaking Changes

This section might be expanded in time and will end up on a wiki page.

We did our best to make the changes least demanding for our users since backward compatibility is critical to us. However since this is a major release change we've decided to perform some backward incompatible changes.

• spring-cloud-starter-zipkin module was removed - to maintain backward compatibility you need to change it into two dependencies: spring-cloud-sleuth-zipkin and spring-cloud-starter-sleuth
• If for some reason you depended on Sleuth's autoconfiguration classes, they might have moved to a different package (some of the autoconfigs that were in core module now ended up in brave under a different package name