whatisgithub

What is transmittable-thread-local?

alibaba/transmittable-thread-local — explained in plain English

Analysis updated 2026-06-24

8,294JavaAudience · developerComplexity · 2/5Setup · easy

In one sentence

A tiny Java library from Alibaba that fixes a common problem: per-request data like trace IDs stored in ThreadLocal gets lost when tasks run on a reused thread pool thread, this library makes sure it carries through correctly.

Mindmap

mindmap
  root((TTL))
    Problem solved
      ThreadLocal in pools
      Context not inherited
      Reused pool threads
    Usage modes
      Wrap tasks
      Wrap thread pool
      Java Agent
    Use cases
      Distributed tracing
      Log context
      Request-scoped cache
    Compatibility
      Java 6 to 21
      Zero dependencies
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Pass a distributed trace ID through all async tasks in a thread pool so your logs stay correlated across threads.

USE CASE 2

Propagate a user ID or request context from the main thread into pooled worker threads without adding extra method parameters.

USE CASE 3

Wrap your existing ExecutorService with TTL so all submitted tasks automatically inherit the current thread's context in one line.

USE CASE 4

Use the Java Agent mode to patch JDK thread pools at startup so TTL works across the whole application without touching existing code.

What is it built with?

JavaMavenGradle

How does it compare?

alibaba/transmittable-thread-localkrahets/leetcode-bookbytedeco/javacv
Stars8,2948,2898,308
LanguageJavaJavaJava
Setup difficultyeasyeasyeasy
Complexity2/51/52/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 30min

Zero external dependencies, add one Maven or Gradle dependency and wrap your executor in a single method call.

So what is it?

This is a small Java library from Alibaba that solves a specific problem with thread-local storage in Java applications. In Java, developers often store per-request information (like a user ID or trace ID) in a structure called a ThreadLocal, which keeps that data tied to the current thread. Java also has a built-in InheritableThreadLocal that passes that data to child threads, but it breaks down when thread pools are involved, because pooled threads are created once and reused many times rather than spawned fresh for each task. This library provides a class called TransmittableThreadLocal (TTL) that fills that gap. When a task is submitted to a thread pool, TTL captures the current ThreadLocal values from the submitting thread and makes them available inside the task when it runs on a pooled thread. The library has zero external dependencies and is around 1000 lines of code, making it very lightweight to add to a project. There are three ways to use it: wrap individual tasks (Runnable or Callable) with a TTL-aware wrapper before submitting them to a pool, wrap the thread pool itself so all tasks go through TTL automatically, or use a Java Agent that patches the standard JDK thread pool classes at startup without any code changes in the application. Typical use cases mentioned in the documentation include distributed tracing systems (where a trace ID must follow a request through all async work), log context collection, request-scoped caches, and passing configuration from a framework layer down to an SDK. The library supports Java 6 through 21 depending on the version used. The full README is longer than what was shown.

Copy-paste prompts

Prompt 1
Show me how to use TransmittableThreadLocal to pass a request trace ID through tasks submitted to a Java ExecutorService thread pool.
Prompt 2
How do I wrap an existing Java ExecutorService with TTL so that all submitted Runnable tasks automatically carry the parent thread's context?
Prompt 3
I want to use the TTL Java Agent so I don't need to change existing code. How do I add it as a JVM argument and what does it patch?
Prompt 4
Using TransmittableThreadLocal, show me how to propagate a log4j MDC context with userId and requestId into async tasks in a Spring Boot app.

Frequently asked questions

What is transmittable-thread-local?

A tiny Java library from Alibaba that fixes a common problem: per-request data like trace IDs stored in ThreadLocal gets lost when tasks run on a reused thread pool thread, this library makes sure it carries through correctly.

What language is transmittable-thread-local written in?

Mainly Java. The stack also includes Java, Maven, Gradle.

How hard is transmittable-thread-local to set up?

Setup difficulty is rated easy, with roughly 30min to a first successful run.

Who is transmittable-thread-local for?

Mainly developer.

Open on GitHub → Ask about another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.