skip to content

With SLF4J's MDC, how do you carry a request id into ExecutorService tasks and CompletableFuture stages, and what must the task's finally do?

level: middleimportance: must knowfreq 55%

answer

  1. copy at hand-off, not at run
  2. two threads, two maps
  3. getCopyOfContextMap may be null
  4. restore the worker's previous map
  5. every async stage needs the executor

basics

~10 s

Capture MDC.getCopyOfContextMap() when the task is submitted, apply it with MDC.setContextMap inside the task, and in finally restore the worker's previous map, clearing when it was null, so no request's entries stay behind.

solid answer

~40 s

Wrap the executor so that `execute` runs on the submitting thread and takes `MDC.getCopyOfContextMap()` there, while the request's entries are still present. The wrapped task, now on the worker, saves the worker's own map, installs the captured one with `MDC.setContextMap`, runs the work, and in `finally` puts the saved map back. Both maps can be `null`, since `getCopyOfContextMap()` may return `null` when nothing was put, so the wrapper calls `MDC.clear()` in that case; SLF4J documents a `null` argument to `setContextMap` as allowed only since 2.0.0. Restoring instead of clearing matters when the task runs on the submitting thread itself, as under a caller-runs rejection policy. For `CompletableFuture`, pass the wrapped executor to `supplyAsync` and to every `*Async` stage: a stage given no executor runs on the default pool and never meets the wrapper.

code

java · 29 lines
java
public final class MdcExecutor implements Executor {
    private final Executor delegate;

    public MdcExecutor(Executor delegate) {
        this.delegate = delegate;
    }

    @Override
    public void execute(Runnable task) {
        Map<String, String> captured = MDC.getCopyOfContextMap(); // submitting thread
        delegate.execute(() -> {
            Map<String, String> previous = MDC.getCopyOfContextMap(); // worker thread
            install(captured);
            try {
                task.run();
            } finally {
                install(previous);
            }
        });
    }

    private static void install(Map<String, String> map) {
        if (map == null) {
            MDC.clear();
        } else {
            MDC.setContextMap(map);
        }
    }
}

go deeper

for a junior

Recall the two methods, getCopyOfContextMap and setContextMap, and that a worker thread starts without the request's entries.

for a middle

Walk through capture on the submitter, install on the worker, restore in finally, and the null-map branch, naming the thread each step runs on.

for a senior

Explain why restoring beats clearing under caller-runs rejection, and how one async stage without an executor silently drops the id in production.

for a principal

Decide where the wrapper lives so teams cannot forget it: one shared executor factory or framework hook, plus a test that a one-thread pool never leaks ids.

## The gap the wrapper closes SLF4J's **MDC** (Mapped Diagnostic Context) is a per-thread map that the bound backend can print on every log line. A servlet filter fills it on the request thread. When that thread hands work to an `ExecutorService` or a `CompletableFuture`, the work runs on a **worker thread** with a map of its own, so the request id is missing unless something copies it across. `slf4j-api` ships no executor wrapper for this; the copying is code you write once, using two static methods: - `MDC.getCopyOfContextMap()` returns a **copy** of the current thread's map, and may return `null` when the thread has no map. - `MDC.setContextMap(map)` first clears the current thread's map, then copies the argument into it. Because both methods copy, the submitter and the worker never share a map object, and a key the worker adds does not leak back into the request thread. ## Capture, install, restore The pattern has five steps, split across two threads: 1. **On the submitting thread**, inside `execute` or `submit`, call `MDC.getCopyOfContextMap()`. This is the only moment when both the request's entries and the task exist on the same thread. 2. **On the worker**, before the work, save the worker's current map with `getCopyOfContextMap()`. 3. Install the captured map with `MDC.setContextMap(captured)`, or `MDC.clear()` if it was `null`. 4. Run the task inside `try`. 5. In `finally`, put the saved map back the same way: `setContextMap(previous)`, or `clear()` if `previous` was `null`. Capturing inside the task body instead of in `execute` is the classic mistake: by then the code is on the worker, and it copies the worker's map, which is empty or holds an earlier request's entries. ## The null map `getCopyOfContextMap()` is documented as possibly returning `null`, and SLF4J's own `BasicMDCAdapter` does return `null` on a thread where nothing was ever put. The MDC documentation also says a `null` argument to `setContextMap` is allowed since SLF4J 2.0.0, and the `MDCAdapter` contract says implementations must support it. Writing the check yourself costs one `if` and keeps the wrapper's meaning obvious: a `null` capture means the worker should run with **no** entries, so the wrapper clears instead of keeping whatever the worker already had. ## Restore versus clear in finally | `finally` does | Worker thread from a pool | Task run on the submitting thread | |---|---|---| | nothing | keeps the request's entries for the next task | unchanged, by luck | | `MDC.clear()` | clean | the submitter loses its own entries | | restore the saved map | clean | the submitter's entries come back intact | A task runs on the submitting thread more often than people expect: a `ThreadPoolExecutor` with `CallerRunsPolicy` runs a rejected task on the caller, and a direct executor runs everything inline. In those cases a `clear()` in `finally` wipes the request thread's entries for the rest of the request, which looks exactly like the bug the wrapper was written to fix. Restoring the saved map is correct on both kinds of thread. ## CompletableFuture stages `CompletableFuture` takes an `Executor`, so a wrapping `Executor` covers it as long as every asynchronous step receives it: - pass the wrapper to `supplyAsync(supplier, executor)` and `runAsync(runnable, executor)`; - pass it again to each `thenApplyAsync`, `thenComposeAsync` and similar call, because a `*Async` stage written **without** an executor runs on the future's default asynchronous pool, which never went through the wrapper; - for an `ExecutorService` used directly, wrap the `Runnable` or `Callable` given to `submit` the same way, or decorate the service so every submission is captured. Which thread runs a non-async stage such as `thenAccept` is a question about `CompletableFuture` itself; for MDC the rule is simply that whichever thread runs the code must have had the map installed, either by the wrapper or by the request filter. ## Checking it works - Log one line inside the task and one after `join()`; both should show the same id. - Run two requests through a pool of one thread; the second must never print the first's id. - Force a rejection with a caller-runs policy and confirm the request thread still logs its id afterwards. Framework executors often offer a task-decorating hook, which is the natural place for this wrapper; the logic inside it is the same five steps.

  • Why take the copy in execute() rather than as the first line of the wrapped lambda?
    The lambda runs on the worker, so reading MDC there copies the worker's map, which is empty or holds an earlier request's entries. `execute()` runs on the submitting thread at the moment of hand-off, the only point where the request's entries and the task are on the same thread, so the copy must be taken there and closed over by the lambda.
  • Why does the wrapper copy the map instead of passing the submitter's map object to the worker?
    `getCopyOfContextMap()` returns a copy, and `setContextMap()` copies its argument into the worker's own map, so each thread owns independent entries. A key the worker adds or removes does not change the request thread's map or another worker's, and no synchronization is needed between them.
  • A thenApplyAsync stage written without an executor argument logs no request id although supplyAsync used the wrapper. Why?
    A `*Async` stage with no executor argument is scheduled on the future's default asynchronous pool, not on the executor an earlier stage used. That pool's threads never went through the wrapper, so nothing installed the map. Pass the wrapping executor to every `*Async` stage, or wrap the stage's function so it captures and restores the map itself.

  • Read the MDC inside the task body, on the worker, to capture the request id.
  • Calling MDC.clear() in finally is always safe, even when the caller runs the task.
  • slf4j-api ships an MDC-aware ExecutorService that you only need to wrap around the pool.
  • MDC.getCopyOfContextMap() always returns a map, empty at worst.
  • Wrapping the pool once also covers CompletableFuture stages that are given no executor.

Assumes SLF4J 2.0.20; MDC.setContextMap documents a null argument as allowed only since 2.0.0.