Usage of `sun.misc.Unsafe` will break the SDK in future Java releases

[ThomasVitale]

Is your feature request related to a problem? Please describe.
As of Java 24 (released on March 18th, 2025), when running an application which uses the OpenTelemetry SDK, the following warning is logged at application startup:

WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
WARNING: sun.misc.Unsafe::objectFieldOffset has been called by io.opentelemetry.internal.shaded.jctools.util.UnsafeAccess (file:/Users/thomas/.gradle/caches/modules-2/files-2.1/io.opentelemetry/opentelemetry-sdk-trace/1.48.0/e88429ab27db3fbb6ed579daf0ae5ceb98b70210/opentelemetry-sdk-trace-1.48.0.jar)
WARNING: Please consider reporting this to the maintainers of class io.opentelemetry.internal.shaded.jctools.util.UnsafeAccess
WARNING: sun.misc.Unsafe::objectFieldOffset will be removed in a future release

This is in line with the step-wise plan to completely remove access to sun.misc.Unsafe in future Java versions. In particular, by default, Java 26 (March 2026) will fail the application at startup time if this internal API is used.

See more details and the complete plan here.

Describe the solution you'd like

The solution recommended by the Java team here.

Over the past several years, we have introduced two standard APIs that are safe and performant replacements for the memory-access methods in sun.misc.Unsafe:

java.lang.invoke.VarHandle, introduced in JDK 9 (JEP 193), provides methods to safely and efficiently manipulate on-heap memory, i.e., fields of objects, static fields of classes, and elements of arrays.

java.lang.foreign.MemorySegment, introduced in JDK 22 (JEP 454), provides methods to safely and efficiently access off-heap memory, sometimes in cooperation with VarHandle.

These standard APIs guarantee no undefined behavior, promise long-term stability, and have high-quality integration with the tooling and documentation of the Java Platform. (Examples of their use are given in JEP 471.) Given the availability of these APIs, it is now appropriate to deprecate and eventually remove the memory-access methods in sun.misc.Unsafe.

Describe alternatives you've considered

No other alternatives exist once sun.misc.Unsafe is completely removed from the Java platform.

Additional context

Issue where a different usage of sun.misc.Unsafe was introduced (different from what I get flagged in the warning): #6433. I can see the usage is behind a Java version check (<= 22), so the warning might not get printed out, but it's something to verify in this case. Perhaps an idea would be to produce multiple JARs when releasing the SDK, targeting different versions of Java. So that for Java 22+, the new FFM API can be used instead of sun.misc.Unsafe.

And related issue about the problematic usage of sun.misc.Unsafe: #6913

[jack-berg]

Perhaps an idea would be to produce multiple JARs when releasing the SDK, targeting different versions of Java.

Yes I think this is what we'll have to do. We have precedent for that type of thing here: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/common/src/main/java9/io/opentelemetry/sdk/internal/Java9VersionSpecific.java

[joffrey-bion]

Why is this classified as a feature request? There is no new feature involved here.

It's about preventing this library from crashing apps in the future, so it's closer to a bug IMO.

[ThomasVitale]

With Java 25 released, there are now 6 months to go before Java 26 is out, where the usage of sun.misc.Unsafe will throw an error and the OpenTelemetry Java SDK will not work any longer.

I reported this issue for a specific instance of sun.misc.Unsafe usage, but there might be more. Would it be beneficial to have some kind of comprehensive task to handle the migration across the entire SDK, and come up with a plan to be ready for when Java 26 is released?

[trask]

hi @ThomasVitale! do you know if the Java 26-ea releases will throw an error already? or if there's a way to opt-in to that behavior in Java 25? if so, we could probably add that to our build matrix and work through any failures that way

[trask]

thanks @jhalliday! I'll try this:

--sun-misc-unsafe-memory-access=deny

[jack-berg]

I've been looking into this a bit myself. I believe that all usages of sun.misc.Unsafe are currently performance optimizations with fallbacks in place if unavailable:

• BatchSpanProcessor initializes a queue using JCTool's MpscArrayQueue, which uses Unsafe under the hood. However, during initialization, we catch exceptions thrown from Unsafe being unavailable and fallback to ArrayBlockingQueue
• StatelessMarshalerUtil uses unsafe to speed up computing UTF8 string size during OTLP marshaling. The logic only uses Unsafe if available, else falls back to a less performant variant.

Are there other uses of unsafe? Are the checks for Unsafe availability sufficient?

We should definitely enable the --sun-misc-unsafe-memory-access=deny option and double check. Should also see if we can find alternatives to our performance optimizations which use the Unsafe alternatives.

For reference, here's what a couple other popular projects which use Unsafe say about the topic:

• Warnings about terminally deprecated Unsafe usage protocolbuffers/protobuf#20760 (comment)
• org.jctools.util.UnsafeAccess invokes terminally deprecated method sun.misc.Unsafe::objectFieldOffset JCTools/JCTools#395

[trask]

Usage of sun.misc.Unsafe will break the SDK in future Java releases

#7683 confirms this is not the case, and that the SDK already has fallbacks in place when Unsafe is not available.

That said, however, the warning message from the JVM:

WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
WARNING: sun.misc.Unsafe::objectFieldOffset has been called by io.opentelemetry.internal.shaded.jctools.util.UnsafeAccess (file:/Users/thomas/.gradle/caches/modules-2/files-2.1/io.opentelemetry/opentelemetry-sdk-trace/1.48.0/e88429ab27db3fbb6ed579daf0ae5ceb98b70210/opentelemetry-sdk-trace-1.48.0.jar)
WARNING: Please consider reporting this to the maintainers of class io.opentelemetry.internal.shaded.jctools.util.UnsafeAccess
WARNING: sun.misc.Unsafe::objectFieldOffset will be removed in a future release

is causing people to (rightfully) worry, and so we should avoid triggering it.

I've sent #7691 to address that.

[goafabric]

@goafabric: remindme