Why Does TraceId Get Mixed Up Under High Concurrency Even Though the Parent Thread Passes It to Child Threads?

Why ITL Fails

In microservice development, a TraceId must travel from the gateway to the database. Java provides InheritableThreadLocal (ITL) to automatically copy parent‑thread locals to a newly created child thread.

ITL Mechanism

When new Thread() is executed, Thread.init() checks the parent’s inheritableThreadLocals field and copies the entire map into the child’s memory. This copy only occurs at thread creation.

Thread‑Pool Reuse Problem

In production code asynchronous tasks are submitted to a ThreadPoolExecutor, not created with new Thread. Consider a high‑load sequence:

Request A is submitted; the pool creates a new worker thread (Thread‑1). ITL copies A’s TraceId, and the task logs correctly.

Thread‑1 finishes and returns to the pool.

Request B arrives; the pool reuses Thread‑1. Because no new thread is created, ITL does not copy B’s TraceId, so Thread‑1 still holds A’s TraceId. All logs for B incorrectly show A’s identifier, causing the “mixed‑up” effect.

During low‑traffic periods idle threads are destroyed (keepAliveTime expires), so a new thread is created for each request and the problem is not observed.

Manual Context Propagation

The straightforward fix is to capture the TraceId before submitting the task and set it inside the worker thread, clearing it afterward:

// 1. Capture in the submitting thread
String traceId = TraceContext.getTraceId();
executorService.submit(() -> {
    try {
        // 2. Install in the worker thread
        TraceContext.setTraceId(traceId);
        // ... business logic ...
    } finally {
        // 3. Clean up to avoid contamination
        TraceContext.remove();
    }
});

This approach works but is highly intrusive; every place that uses a thread pool must repeat the try‑finally block.

Using Alibaba’s TransmittableThreadLocal (TTL)

TTL is designed to solve ITL’s limitation in thread‑pool environments. It automatically captures and restores context for any Runnable or Callable.

// Wrap a task so the TraceId is transmitted automatically
Runnable ttlRunnable = TtlRunnable.get(() -> {
    Map<String, Object> user = UserContextHolder.get();
    // ... business logic ...
});
executorService.execute(ttlRunnable);

For a whole pool, wrap the executor service:

ExecutorService normalPool = Executors.newFixedThreadPool(5);
ExecutorService ttlPool = TtlExecutors.getTtlExecutorService(normalPool);
// Use ttlPool for all submissions; no manual propagation needed

TTL Internal Flow

Submission: When submit() is called, TTL snapshots the current thread’s context and binds it to the task object.

Execution: Before the worker thread runs run(), TTL intercepts and overwrites the worker’s context with the snapshot, regardless of the worker’s previous state.

Cleanup: After the task finishes, TTL clears the worker’s context to prevent leakage.

Conclusion

Whenever a thread pool is used, context propagation cannot be ignored. Understanding ITL’s creation‑time limitation and adopting a solution such as manual propagation or, preferably, TTL ensures that TraceId and other thread‑local data remain correct under high concurrency.