Skip to content

Spring Cloud Sleuth 3.1 Migration Guide

Jump to bottom
Marcin Grzejszczak edited this page Jan 9, 2023 · 25 revisions

High-Level Overview

We've moved the API code from Sleuth to Micrometer Tracing. The Brave and OpenTelemetry bridges have their respective modules in Micrometer Tracing.

The Autoconfiguration of Brave and OpenTelemetry Tracer got moved to Spring Boot. So did autoconfiguration for Zipkin and Wavefront reporters for both tracers.

The default Tracer now is OpenTelemetry tracer, the default Trace Id format is 128 bit and default Context Propagation format is W3C. By default we don't support joined spans (this means that when you have e.g. an HTTP span, you will no longer see the same span being there on the client and sender side, you will see two separate spans now).

The instrumentation code and its autoconfiguration got moved to respective projects (e.g. Web instrumentation is now in Spring Web and Spring Boot autconfigures that).

Context Propagation

Since the default propagation format is w3c you should set in your Sleuth & Boot 2.x application spring.sleuth.propagation.type=w3c,b3 so that you publish the headers in 2 formats. One for the current Boot 2.x applications (b3) and one for the new Boot 3.x applications (w3c).

Spring Cloud Sleuth API migration

The whole Spring Cloud Sleuth API module got pretty much moved to Micrometer Tracing. That means that in the vast majority of places you should just change the package from org.springframework.cloud.sleuth to io.micrometer.tracing.

Autoconfiguration

Parts of the Spring Cloud Sleuth Autoconfigure and Spring Cloud Sleuth OTel Autoconfigure modules got moved to:

Log pattern

Spring Cloud Sleuth had a TraceEnvironmentPostProcessor that would set the logging pattern that would contain trace and span ids. With Micrometer Tracing and Boot 3.0 you need to set it yourself e.g. like this

logging.pattern.level: "%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]"

Instrumentations

You have to check each project for their Micrometer Observation configuration.

Async Instrumentation

Spring Cloud Sleuth came with a bunch of executor / executor service instrumentations (e.g. LazyTraceExecutor) that would propagate the tracing context together with a creation of a span . With the new releases of Micrometer we come to the conclusion that we have to separate those two approaches.

This is why we have the Context Propagation library that will propagate objects (thread locals) through various means of communication (you can read more about it in the Context Propagation Docs. You don't have to add Context Propagation JAR manually if you're adding Micrometer Tracing library - that will come in as a transitive dependency.

To wrap executors just use the ContextExecutorService.wrap() or ContextScheduledExecutorService.wrap() methods. You can also use ContextSnapshot.wrap() methods to wrap Runnables or Callables.

Example of setup for enabling Async Servlets and Async processing with Spring.

@Configuration(proxyBeanMethods = false)
class CommonConfiguration {

    // Example of Async Servlets setup
    @Configuration(proxyBeanMethods = false)
    @EnableAsync
    static class AsyncConfig implements AsyncConfigurer, WebMvcConfigurer {
        @Override
        public Executor getAsyncExecutor() {
            return ContextExecutorService.wrap(Executors.newCachedThreadPool(), ContextSnapshot::captureAll);
        }

        @Override
        public void configureAsyncSupport(AsyncSupportConfigurer configurer) {
            configurer.setTaskExecutor(new SimpleAsyncTaskExecutor(r -> new Thread(ContextSnapshot.captureAll().wrap(r))));
        }
    }


    /**
     * NAME OF THE BEAN IS IMPORTANT!
     * <p>
     * We need to wrap this for @Async related things to propagate the context.
     *
     * @see EnableAsync
     */
    // [Observability] instrumenting executors
    @Bean(name = "taskExecutor", destroyMethod = "shutdown")
    ThreadPoolTaskScheduler threadPoolTaskScheduler() {
        ThreadPoolTaskScheduler threadPoolTaskScheduler = new ThreadPoolTaskScheduler() {
            @Override
            protected ExecutorService initializeExecutor(ThreadFactory threadFactory, RejectedExecutionHandler rejectedExecutionHandler) {
                ExecutorService executorService = super.initializeExecutor(threadFactory, rejectedExecutionHandler);
                return ContextExecutorService.wrap(executorService, ContextSnapshot::captureAll);
            }
        };
        threadPoolTaskScheduler.initialize();
        return threadPoolTaskScheduler;
    }
}

Reactor

We no longer auto-instrument Project Reactor, you have to do that manually. Please read this section of the Micrometer docs for more information.

Samples

Spring Cloud Sleuth Samples got migrated to Micrometer Samples.

Clone this wiki locally