open-telemetry / open-telemetry/opentelemetry-java

Do we have plan to support ScopedValue rather than ThreadLocal?

Open
#8,282 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Feature Request
Dominant language
Java
Stars
2.5k
Forks
1k
Avg merge
3d 17h
Merged PRs (30d)
58

Description

I saw the impl heavily relies on ThreadLocal like io.opentelemetry.context.ThreadLocalContextStorage.
While in our LnP test against JDK virtual thread, we found threadlocal could be the bottleneck.
Is there any plan to switch to ScopedValue?

Here's also some comments from AI:

The Performance Overhead Sources

  1. Thread.currentThread() lookup: Each get()/set() needs to get the current thread. With virtual threads, this involves:
    - Finding the carrier thread
    - Looking up which virtual thread is currently mounted
    - This has more indirection than with platform threads
  2. Mounting/unmounting cost: When a virtual thread blocks (IO), it's unmounted. On resumption, there's overhead. ThreadLocal access
    during this transition adds to the cost.
  3. Potential JVM internal contention: While ThreadLocalMap itself is largely lock-free, some JVM implementations have shown
    contention-like bottlenecks at scale due to:
    - Internal hash map operations
    - Memory barrier costs with millions of concurrent threads

The Reality Check

┌────────────────────────────────┬────────────────────────────────────────┐
│ Aspect │ Reality │
├────────────────────────────────┼────────────────────────────────────────┤
│ Traditional lock contention? │ No │
├────────────────────────────────┼────────────────────────────────────────┤
│ Per-operation overhead higher? │ Yes, marginally │
├────────────────────────────────┼────────────────────────────────────────┤
│ Scales to millions of threads? │ Debatable - depends on access patterns │
├────────────────────────────────┼────────────────────────────────────────┤
│ ScopedValue better? │ Yes, designed for virtual threads │
└────────────────────────────────┴────────────────────────────────────────┘

Recommendation

For new code with virtual threads, prefer ScopedValue (Java 21+) over ThreadLocal. It's semantics-matched to virtual thread model and
avoids some of the historical design choices in ThreadLocal that weren't made with millions of threads in mind.

If stuck with ThreadLocal, keep access patterns minimal and benchmark your specific use case.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing io.opentelemetry.context.ThreadLocalContextStorage and the JDK virtual-thread behavior described in the issue. Establish whether ScopedValue is compatible with the context-storage requirements and identify the benchmarks or tests needed to compare the approaches. Done would require a documented design decision or an agreed implementation plan, not just a code change.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.