Context propagation library
Propagate a snapshot of one or more ThreadLocal values into another thread.
This library enables automatic propagation of several well-known ThreadLocal contexts by capturing a snapshot, reactivating it in another thread and ensuring proper cleanup after execution finishes:
ContextAwareExecutorServicewrapping any existingExecutorService.ContextAwareCompletableFuturepropagating context snapshots into each successiveCompletionStage.
Terminology
Context
Abstraction containing a value in the context of a thread.
The most common implementation in Java is a ThreadLocal value.
The library provies an AbstractThreadLocalContext base class
that features nesting values and predictable behaviour for out-of-order closing.
For each context type, there can only be one active context per thread at any time.
ContextManager
Manages a context. The ContextManager API can activate a new context value and provides access to the active context value.
ContextSnapshot
A snapshot contains the current value from all known context managers.
These values can be reactivated in another thread.
Reactivated snapshots must be closed to avoid leaking context.
All context aware utility classes in this library are tested to make sure they reactivate and close snapshots in a safe way.
How to use this library
Capturing a snapshot of ThreadLocal context values
Just before creating a new thread, capture a snapshot of all ThreadLocal context values:
ContextSnapshot snapshot = ContextManagers.createContextSnapshot();In the code of your background thread, activate the snapshot to have all ThreadLocal context values set as they were captured:
try (Context<Void> reactivation = snapshot.reactivate()) {
// All ThreadLocal values from the snapshot are available within this block
}Threadpools and ExecutorService
If your background threads are managed by an ExecutorService, you can use our context aware ExecutorService instead of your usual threadpool.
When submitting new work, this automatically takes a context snapshot
to reactivate in the background thread.
After the background thread finishes the snapshot is closed,
ensuring no ThreadLocal values leak into the thread pool.
The ContextAwareExecutorService can wrap any ExecutorService for the actual thread execution:
private static final ExecutorService THREADPOOL =
new ContextAwareExecutorService(Executors.newCachedThreadpool());Supported contexts
The following ThreadLocal-based contexts are currently supported
out of the box by this context-propagation library:
- SLF4J MDC (Mapped Diagnostic Context)
- Log4j 2 Thread Context
- OpenTracing Span contexts
- Spring Security Context
- Locale context
- ServletRequest contexts
- Yours? Feel free to create an issue or pull-request if you believe there's a general context that was forgotten.
Custom contexts
Adding your own Context type is possible
by creating your own context manager.
Caching
By default the ContextManagers class caches the context manager instances it finds
per classloader.
Since the cache is per classloader, this should work satisfactory
for applications with simple classloader hierarchies (e.g. dropwizard)
and also for complex hierarchies (spring boot, JEE and the like).
Disable caching
If however, you wish to disable caching of the context manager instances, you can set either:
- the java system property
talsmasoftware.context.caching, or - the environment variable
TALSMASOFTWARE_CONTEXT_CACHING
The values false or 0 will disable caching.
Building jars with dependencies
When using a build tool or plugin to create an 'uber-jar', i.e. a jar file with all
the classes of its dependencies included, you have to make sure that the service
provider configuration files under META-INF/services are either preserved or
merged. Otherwise Java's ServiceLoader will not be able to find the context
implementations of this library.
In case your are using the Maven Shade Plugin, you can use the
ServicesResourceTransformer
for this task.
Performance metrics
No library is 'free' with regards to performance.
Capturing a context snapshot and reactivating it in another thread is no different.
For insight, the library tracks the overall time used creating and reactivating
context snapshots along with time spent in each individual ContextManager.
Logging performance
On a development machine, you can get timing for each snapshot by turning on logging
for nl.talsmasoftware.context.Timing at FINEST or TRACE level
(depending on your logger of choice).
Please do not turn this on in production as the logging overhead will most likely
have a noticable impact on your application.
Metrics reporting
The context propagation metrics module uses the excellent dropwizard metrics library to instrument Timers for context propagation.
Similarly, the context propagation Micrometer module adds Micrometer instrumentation Timers for the context propagation.
Adding either of these modules to your classpath will automatically configure various timers in the global default metric registry of your application.