Open-Source Observability · alibaba

transmittable-thread-local

TransmittableThreadLocal (TTL) is a Java library that solves the problem of passing ThreadLocal values across thread boundaries in thread pools. It extends InheritableThreadLocal to enable context propagation in asynchronous and pooled execution scenarios, commonly used in distributed tracing, request-scoped caching, and logging systems.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/alibaba/transmittable-thread-local

8.3k

GitHub stars

1.7k

Forks

Java

Primary language

Apache-2.0

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	alibaba/transmittable-thread-local
Owner	alibaba
Primary language	Java
License	Apache-2.0 — OSI-approved
Stars	8.3k
Forks	1.7k
Open issues	55
Latest release	v2.14.5 (2023-12-25)
Last updated	2026-06-18
Source	https://github.com/alibaba/transmittable-thread-local

What transmittable-thread-local is

TTL provides an enhanced InheritableThreadLocal implementation with ~1000 SLOC that enables ThreadLocal value transmission from task submission time to task execution time in pooled executors, ForkJoinPool, and TimerTask. It includes wrapper utilities (TtlRunnable, TtlCallable) and optional Java Agent instrumentation for transparent thread pool wrapping.

Quickstart

Get the transmittable-thread-local source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/alibaba/transmittable-thread-local.git2cd transmittable-thread-local3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Distributed Tracing & APM

Propagate trace IDs, span context, and request metadata across thread pool boundaries for end-to-end request tracing in microservices architectures.

Request-Scoped Context Propagation

Maintain request metadata (user ID, tenant ID, correlation IDs) across async task execution without explicit parameter passing through method chains.

Structured Logging & MDC

Carry logging context (request ID, user context, business context) through async operations so logs from spawned tasks include the originating request's metadata.

Implementation considerations

Decide between manual wrapping (TtlRunnable/TtlCallable) or Java Agent instrumentation—Agent approach is transparent but requires JVM flag configuration.
If transmitting mutable reference objects, implement transmitteeValue() with proper deep copying to prevent unintended shared state across threads.
Monitor memory overhead of captured ThreadLocal contexts in long-lived or high-concurrency scenarios; contexts are retained until task completes.
Verify compatibility with your thread pool implementation; TTL wraps standard ExecutorService, ForkJoinPool, and TimerTask but may need custom adapters for proprietary pools.
Plan cleanup strategy for ThreadLocal values (using remove() in try-finally) to prevent memory leaks in pooled environments.

When to avoid it — and what to weigh

No Async Operations — If your application uses only synchronous execution and standard ThreadLocal without thread pools, standard InheritableThreadLocal is sufficient.
High Frequency Context Mutations — If ThreadLocal values are frequently modified across multiple threads without proper synchronization, shared state challenges may outweigh benefits; consider immutable context objects.
Virtual Thread Environments — For Java 21+ with virtual threads, inheritance model may differ; requires evaluation against virtual thread semantics and future Java ThreadLocal changes.
Non-JDK Thread Pools — Custom or third-party thread pool implementations may require manual instrumentation or Java Agent configuration; transparent wrapping is not guaranteed.

License & commercial use

Licensed under Apache License 2.0 (Apache-2.0), a permissive OSI-approved license allowing commercial use, modification, and distribution with attribution and liability disclaimer.

Commercial use is permitted under Apache-2.0. No licensing fees or restrictions on proprietary applications. Requires preservation of copyright/license notices. Liability is disclaimed. Suitable for production commercial software without legal concerns regarding the license itself.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

No inherent security vulnerabilities disclosed in provided data. Java Agent mechanism requires careful JVM configuration to prevent agent tampering. Context values transmitted through TTL retain data sensitivity properties—if ThreadLocal holds sensitive data (passwords, tokens), ensure they are handled securely and cleaned up promptly. Shared context across threads (when using reference objects) requires synchronization if needed.

Alternatives to consider

Micrometer Tracing / Spring Cloud Sleuth

Integrated tracing solutions that handle ThreadLocal context propagation automatically. Heavier weight but bundle APM features, observability, and vendor integrations.

MDC (Mapped Diagnostic Context) with custom wrapping

SLF4J/Logback MDC for logging context only. Lighter than TTL but solves narrower problem (logging) and requires manual async handling.

Context API (Jakarta EE / Project Loom for virtual threads)

Emerging standard for context propagation in async environments. Future-proof for Java 21+ virtual threads but less mature and not yet universal.

Software development agency

Build on transmittable-thread-local with DEV.co software developers

Evaluate TransmittableThreadLocal if you're building microservices, APM integrations, or middleware requiring ThreadLocal context across thread pool boundaries. Check compatibility with existing tracing solutions first.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

opentelemetry-dotnet otel-cli opentelemetry-rust

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Observability APM & Distributed Tracing Middleware & Framework Integration Enterprise Application Development Talk to DEV.co

transmittable-thread-local FAQ

Do I need TTL if I use Spring Cloud Sleuth or similar?

Likely not. Modern tracing frameworks handle async context propagation. Check if your framework already solves this problem before adding TTL as a dependency.

Can TTL work with virtual threads (Java 21+)?

Unknown without testing. Virtual threads change inheritance semantics. Review compatibility against your Java version and thread model; the project may provide guidance in v3 or issue discussions.

What is the performance overhead of TTL?

Not clearly stated in provided documentation. Context capture and transmission involve map operations. For latency-sensitive systems, benchmark against your use case; code size (~1000 SLOC) suggests minimal footprint but not zero cost.

Is Java Agent deployment mandatory?

No. Manual wrapping (TtlRunnable/TtlCallable) is transparent and requires no JVM flags. Java Agent is optional for automatic instrumentation and reduces code changes.

Custom software development services

From first prototype to production, DEV.co delivers software development services around tools like transmittable-thread-local. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source observability and beyond.

Need Reliable Context Propagation in Async Java Systems?

Talk to DEV.co Schedule a Consultation