A request handler stores a correlation identifier in thread-local storage so log lines can be tagged with it. When the handler hands work to a background worker pool, that identifier disappears from the logs. Explain why, and describe the general fix.

## Why the value vanishes Thread-local storage keys a value to the thread that reads it. Conceptually, a lookup is `currentThread().localMap[key]`. The request handler thread has an entry for the correlation key; the pool worker is an entirely different thread whose map has no such entry. Nothing copies it. The pool takes a callable off a queue and invokes it — it has no idea your key exists. So the log line emitted from the worker has no identifier. And there is a worse variant: if some earlier task on that worker set the key and never removed it, the read returns a *stale* identifier, and now your logs and traces confidently attribute this work to an unrelated request. Missing context is a nuisance; wrong context actively misleads the person debugging an incident. ## The general shape of context propagation Every working solution is the same three-step pattern, and it is worth naming the steps explicitly because failures usually come from skipping one. **1. Capture — on the submitting thread, at submission time.** This timing is load-bearing. If you defer capture until the task begins executing, you read the *worker's* context, which is exactly the empty-or-stale slot you were trying to escape. Even a lazy "read the submitter's context later" design is wrong, because by then the submitter has moved on to another request. Capture happens synchronously, at the moment of hand-off, while the submitter still has the right value. **2. Carry — with the task.** Store the captured snapshot inside the task wrapper object. Now the context is attached to the *work*, not to any thread, which is the property you actually wanted all along. **3. Install and remove — around execution.** On the worker, set the values before invoking the body and remove them in a finally. Removal is mandatory: without it you have simply moved the leak from the handler thread to the worker thread, and the next task on that worker inherits your identifier. ``` wrap(task): captured = CTX.get() // step 1: on the submitter, now return () -> // step 2: travels with the task previous = CTX.get() CTX.set(captured) // step 3: install try: task() finally: restore(previous) // and always remove/restore ``` ## Where to apply it At the boundary — once — not at call sites. A decorating executor that wraps every submitted task, an instrumented HTTP/messaging client, or a framework-level hook guarantees the invariant for all work that flows through it. Per-call-site wrapping is a convention, and the failure mode of a violated convention here is silent: one forgotten wrap produces log lines missing an identifier, which nobody notices until an incident. Be systematic about enumerating the boundaries, because they are more numerous than people expect: - Task submission to any pool or executor - Async continuations and callback chains (each stage may run on a different thread) - Scheduled and delayed execution — a timer thread is a hand-off too - Retries and circuit-breaker fallbacks, which frequently run on a separate scheduler - Parallel iteration/streams, which fan work onto shared worker threads - Message producers and consumers - Any library that internally offloads work to its own pool The last one is the usual culprit in a service that "mostly" propagates context: a third-party client hands your callback to *its* executor, which you never wrapped. ## Nested and mixed context When a task submits further tasks, the same wrapping applies recursively; each hop captures whatever is current. Two subtleties: - **Restore, do not blindly remove.** On a worker that may already have context (nested wrapping, or a worker running inside another scope), the finally must restore the *previous* value rather than unconditionally removing, or the outer scope loses its context mid-flight. - **Decide capture semantics per key.** A correlation id should be captured once and stay fixed for the whole logical operation. A trace span usually should *not* be copied verbatim — the child work needs a new child span linked to the parent, or your traces show one span with impossible concurrency. So propagation is per-key policy, not a single blanket copy. ## What does not work **Inheritable thread-local variants.** These copy at *thread creation*. Pool workers are created once, long before your request, by whichever thread happened to trigger pool growth — so workers inherit one arbitrary snapshot and keep it forever. That produces stale, plausible-looking context on every task, which is worse than none. **Passing the id into the task body only.** It works for code you wrote, but every logger, metric, and library call in the transitive call graph reads the ambient slot, so they all still see nothing. Propagation must restore the ambient mechanism, not merely hand you a variable. **Hoping the framework does it.** Some do, for some paths. The reliable move is to verify with a test that asserts the identifier survives each hop your service actually uses. ## Crossing process boundaries No in-process mechanism spans machines. Between services the context must be serialized into the transport — headers on an HTTP request, attributes on a message — and rehydrated by the receiver at its entry point, where it re-enters the in-process propagation described above. This is exactly what distributed-tracing propagation formats standardize. Treat the wire format as part of your API contract: both sides must agree on the key names, and the receiving side must validate and bound what it accepts, since inbound context arrives from a caller you may not fully trust. ## Verifying it works Write a test per hand-off type: set an identifier, cross the boundary, assert the identifier observed on the other side equals the one set. Then assert the slot is *empty* after the task completes. Those two assertions together catch both the propagation break and the leak, and they are the only reliable defence against a library quietly introducing a new unwrapped executor.