Lightweight Distributed Tracing in Spring Cloud Without Third‑Party Tools

Problem

Spring Boot’s default logging framework Logback stores MDC data in a ThreadLocal, which means the trace ID is lost when execution moves to child threads or downstream services. The core challenge is to reliably pass the trace ID through API gateways, remote service calls, and asynchronous thread pools.

How to forward the MDC trace ID in an API Gateway.

How to forward the trace ID between microservices during remote calls.

How to propagate the trace ID to child threads in thread pools.

…

Environment Preparation

Technical stack:

Java 21

Spring Boot 3.2.4

Spring Cloud 2023.0.1

Spring Cloud Gateway 4.1.2

Spring Cloud OpenFeign 4.1.1

Alibaba Transmittable Thread Local 2.14.5

01 API Gateway

Create a GlobalTraceFilter to intercept both web and routing requests and inject a trace ID into the MDC.

Configure Logback (logback‑spring.xml) to include the trace ID in the log pattern:

<springProperty scope="context" name="appName" source="spring.application.name"/>
<property name="CONSOLE_LOG_PATTERN" value="%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(%level){blue} %clr(${PID}){magenta} %clr([%X{traceId:-}]){yellow} %clr([${appName}]){blue} %clr([%thread]){orange} %clr(%-40.40logger{39}){cyan} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}"/>

02 Downstream Service – Intercept HTTP Header

Extract the trace ID from the incoming HTTP header (set by the gateway) and place it into the MDC for the downstream service.

03 Downstream Service – Remote Calls

Implement an OpenFeign interceptor so that all FeignClient calls automatically forward the trace ID via HTTP headers.

04 Asynchronous Multi‑Thread Transmission

Patch LogbackMDCAdapter

Copy the original LogbackMDCAdapter and replace its internal ThreadLocal with Alibaba’s TransmittableThreadLocal to enable MDC propagation across thread pools.

Note: In Spring Boot 3.0 and later, the default Logback MDC adapter cannot be replaced directly; you must register the custom adapter via the SPI mechanism (META‑INF/services directory).

Replace Spring’s Default Thread Pool

Swap the default executor with a wrapper that uses TtlRunnable to preserve the MDC context.

Conclusion

As the number of microservices grows, observability becomes critical; therefore, log aggregation and distributed tracing should be considered prerequisites before adopting a microservice architecture.

Appendix

Gateway MDC verification:

After the modifications, logs show the trace ID correctly propagated through the gateway and downstream services, and the Elastic Stack can be used for visualizing the trace data.