MDC (Mapped Diagnostic Context): Passing Context Information

In distributed microservice architectures or high-concurrency application scenarios, traditional logging often struggles to trace the full journey of a single business request. When a user initiates a call across multiple services, if each service only records local information, the resulting logs will be a collection of isolated fragments lacking correlation and contextual coherence. To address this pain point, the Java ecosystem introduced Mapped Diagnostic Context (MDC).

MDC is essentially a thread-safe Map structure used to store and pass additional diagnostic information within the same thread. It allows developers to inject key business identifiers such as User ID, Request ID, Session Token, etc., into the log context. Regardless of how the log output stream switches, as long as there is no context switch in the thread, these key-value pairs remain synchronized, ensuring that logs generated by different service nodes for the same request can be uniformly correlated and analyzed. This mechanism greatly simplifies the fault troubleshooting and performance monitoring processes in distributed systems.
To use MDC correctly, one must first understand its lifecycle management rules. MDC is initialized as an empty Map at application startup and automatically cleans up all entries upon program exit. Developers can dynamically modify the context content using static methods provided by the Context class, primarily put, remove, and clear.

In practical development, the most common operation is injecting critical information before the request enters business logic and removing sensitive data or completing tracking after processing. Below is an example of a standard initialization and cleanup flow:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

public class RequestHandler {
    private static final Logger logger = LoggerFactory.getLogger(RequestHandler.class);

    public void handleRequest(String userId) {
        // 1. Inject context: Store user ID as key "user_id" in MDC
        MDC.put("user_id", userId);

        try {
            // 2. Execute core business logic; all logs will automatically include the user_id prefix
            logger.info("Starting order processing, Order ID: 10086");
            int result = processOrder();
            
            logger.info("Order processing successful, Result: {}", result);
        } finally {
            // 3. Clean up context: Remove unnecessary keys to prevent memory leaks or cross-request pollution
            MDC.remove("user_id");
        }
    }

    private int processOrder() {
        return 200;
    }
}

In the code above, the put operation binds userId to log output, while the remove operation ensures that each request's context is isolated. If the cleanup operation is forgotten, in a multi-threaded environment, subsequent requests might inadvertently use data from previous requests, causing serious logical errors.

MDC Transfer Mechanism and Precautions in Asynchronous Threads

A key characteristic of MDC is its thread-based context transfer mechanism. When a thread initiates a new thread (e.g., via the Thread class or ExecutorService), by default, the new thread inherits the MDC content from the parent thread. This behavior is crucial for distributed tracing, as it ensures that asynchronous tasks (such as message queue consumers or background scheduled jobs) can carry critical identifier information from the main flow.

However, this also brings potential risks: if developers do not explicitly clean up MDC, long-running asynchronous threads may accumulate a large amount of context data, or unexpected data pollution may occur between multiple asynchronous tasks. For example, in an environment with a shared thread pool, if asynchronous tasks for different requests share the same thread for execution and the context is not cleared in time, it leads to log chaos.

To safely handle asynchronous scenarios, the best practice is to check the MDC status before creating a new thread or submitting an asynchronous task, and force cleanup in callbacks after the task completes:

import java.util.concurrent.*;

public class AsyncExample {
    private static final ExecutorService executor = Executors.newFixedThreadPool(5);

    public void submitTask() {
        String taskId = "task-" + System.currentTimeMillis();
        
        // Inject task ID
        MDC.put("task_id", taskId);

        executor.submit(() -> {
            try {
                logger.info("Asynchronous task is executing");
            } finally {
                // Explicit cleanup to prevent context pollution when the thread pool is reused
                MDC.clear();
            }
        });
    }
}

Through this explicit clear operation, it can be ensured that even if threads are reused to handle other requests, old diagnostic information will not be left behind.

Integration Configuration with Spring Boot

In modern Java Web development, the Spring Boot framework provides highly integrated support for MDC, significantly reducing the cost of manual management. By configuring parameters such as spring.jackson.serialization.write-dates-as-timestamps=true, Spring Boot can automatically parse and inject specific fields from request headers (such as X-Request-ID) into MDC.

Developers can enable Spring Boot's MDC support in the application.yml or application.properties file:

logging:
  level:
    root: INFO
spring:
  mdc:
    enabled: true
    request-headers: X-Request-ID, User-Agent

Once the configuration takes effect, Spring MVC interceptors will automatically read the specified headers and place them into MDC at the beginning of each HTTP request, and automatically clear them after the response ends. This not only reduces code volume but also ensures that logs always contain complete request context information, eliminating the need for developers to manually write MDC.put and MDC.clear logic in the Controller layer.

Best Practices and Performance Optimization Suggestions

Although MDC is powerful, it should be used cautiously in high-concurrency scenarios. First, avoid storing large objects or sensitive data (such as passwords or credit card numbers) directly in MDC to prevent log leakage risks. Second, for tasks that take an extremely long time to complete, evaluate whether the MDC context needs to be maintained throughout the entire lifecycle; it is generally recommended to inject and clean up only during critical phases of the business logic.

Furthermore, since MDC is implemented based on HashMap, there may be performance bottlenecks in extreme high-concurrency write scenarios. If severe context contention issues are encountered, consider using ConcurrentHashMap as an alternative for the underlying storage, but this requires a custom MDC implementation or reliance on support from specific libraries. Overall, the rational use of MDC can significantly improve log readability and system observability, making it an indispensable part of building robust distributed systems.