docs(notes): add spring traceid documentation for 2025-03-24

Author: lzwjava

notes/2025-03-24-spring-traceid-en.md

@@ -0,0 +1,109 @@
+---
+title: Spring Boot Log4j Request Tracing
+lang: en
+layout: post
+audio: false
+translated: false
+generated: true
+---
+
+In a Java Spring Boot application using Log4j without a built-in trace ID design, tracking a specific log entry back to a frontend-initiated request can indeed be challenging. You're correct that `%t` (thread name) in Log4j can help identify logs tied to a specific thread, but as you noted, this becomes less reliable when requests span multiple threads (e.g., due to async processing, thread pools, or downstream calls). Using a time range to search logs is a workaround, but it’s imprecise and cumbersome, especially in high-traffic systems. Let’s explore some practical advice to improve this situation without overhauling your entire setup.
+
+### Quick and Practical Suggestions
+1. **Leverage MDC (Mapped Diagnostic Context) with Log4j**
+   - Log4j supports MDC, which allows you to attach contextual key-value pairs to logs within a thread (and even propagate them across thread boundaries with some care).
+   - Generate a unique request ID when the frontend request hits your Spring Boot application (e.g., a UUID), and store it in the MDC. Then, include this ID in your log pattern.
+   - **How to implement:**
+     - In a Spring Boot filter or interceptor (e.g., `OncePerRequestFilter`), generate the ID:
+       ```java
+       import org.slf4j.MDC;
+       import javax.servlet.FilterChain;
+       import javax.servlet.http.HttpServletRequest;
+       import javax.servlet.http.HttpServletResponse;
+       import java.util.UUID;
+
+       public class RequestTracingFilter extends OncePerRequestFilter {
+           @Override
+           protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) {
+               try {
+                   String traceId = UUID.randomUUID().toString();
+                   MDC.put("traceId", traceId);
+                   filterChain.doFilter(request, response);
+               } finally {
+                   MDC.clear(); // Clean up after request
+               }
+           }
+       }
+       ```
+     - Register the filter in your Spring Boot config:
+       ```java
+       @Bean
+       public FilterRegistrationBean<RequestTracingFilter> tracingFilter() {
+           FilterRegistrationBean<RequestTracingFilter> registrationBean = new FilterRegistrationBean<>();
+           registrationBean.setFilter(new RequestTracingFilter());
+           registrationBean.addUrlPatterns("/*");
+           return registrationBean;
+       }
+       ```
+     - Update your Log4j pattern in `log4j.properties` or `log4j.xml` to include the `traceId`:
+       ```properties
+       log4j.appender.console.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} [%t] %-5p %c{1} - %m [traceId=%X{traceId}]%n
+       ```
+     - Now, every log line tied to that request will include the `traceId`, making it easy to trace back to the frontend button click.
+
+2. **Propagate the Trace ID Across Threads**
+   - If your app uses thread pools or async calls (e.g., `@Async`), the MDC context may not propagate automatically. To handle this:
+     - Wrap async tasks with a custom executor that copies the MDC context:
+       ```java
+       import java.util.concurrent.Executor;
+       import org.springframework.context.annotation.Bean;
+       import org.springframework.context.annotation.Configuration;
+       import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
+
+       @Configuration
+       public class AsyncConfig {
+           @Bean(name = "taskExecutor")
+           public Executor taskExecutor() {
+               ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+               executor.setCorePoolSize(10);
+               executor.setMaxPoolSize(20);
+               executor.setQueueCapacity(100);
+               executor.setTaskDecorator(task -> {
+                   Map<String, String> context = MDC.getCopyOfContextMap();
+                   return () -> {
+                       try {
+                           if (context != null) MDC.setContextMap(context);
+                           task.run();
+                       } finally {
+                           MDC.clear();
+                       }
+                   };
+               });
+               executor.initialize();
+               return executor;
+           }
+       }
+       ```
+     - This ensures the `traceId` sticks with the request even across thread boundaries.
+
+3. **Add Frontend Correlation**
+   - If possible, have the frontend send a custom header (e.g., `X-Request-ID`) with a unique ID when the button is clicked. Your backend can pick this up instead of generating its own UUID. This ties the log directly to the frontend action without extra guesswork.
+
+4. **Fallback: Enhance Logging with Contextual Data**
+   - If MDC feels like too much overhead right now, enrich your logs with more context at key points (e.g., user ID, session ID, or endpoint name). For example:
+     ```java
+     logger.info("Button clicked, endpoint=/api/example, user={}", userId);
+     ```
+   - Combine this with `%t` (thread name) and a tight time range to narrow down logs manually. It’s not ideal but works in a pinch.
+
+### Why Not Just Time Range?
+Relying solely on timestamps is fragile because:
+- Logs from concurrent requests overlap, especially in a busy system.
+- Time precision (e.g., milliseconds) might not be enough to isolate a single request.
+- It’s tedious to correlate logs across services or deep call stacks.
+
+### Long-Term Recommendation
+If this tracing need grows, consider adopting Spring Boot’s built-in support for distributed tracing (e.g., via Sleuth or Micrometer with Zipkin). Sleuth auto-generates trace and span IDs and integrates seamlessly with Log4j, but it’s more involved to set up. For now, MDC is a lightweight, effective middle ground.
+
+### Final Advice
+Start with the MDC approach—it’s simple, leverages Log4j’s native capabilities, and gives you a clear way to tie logs to a frontend-initiated request. You’ll see something like `[traceId=123e4567-e89b-12d3-a456-426614174000]` in every log line for that request, making it trivial to search and trace. Let me know if you need help tweaking this further!