DataDog
diff --git a/‎build-logic/conventions/src/main/kotlin/com/datadoghq/profiler/ProfilerTestPlugin.kt‎
Lines changed: 67 additions & 1 deletion b/‎build-logic/conventions/src/main/kotlin/com/datadoghq/profiler/ProfilerTestPlugin.kt‎
Lines changed: 67 additions & 1 deletion
diff --git a/‎ddprof-lib/src/main/java/com/datadoghq/profiler/ContextStorageMode.java‎
Lines changed: 28 additions & 0 deletions b/‎ddprof-lib/src/main/java/com/datadoghq/profiler/ContextStorageMode.java‎
Lines changed: 28 additions & 0 deletions
diff --git a/‎ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java‎
Lines changed: 58 additions & 13 deletions b/‎ddprof-lib/src/main/java/com/datadoghq/profiler/JavaProfiler.java‎
Lines changed: 58 additions & 13 deletions
@@ -15,6 +15,7 @@ import org.gradle.api.provider.Property
 import org.gradle.api.tasks.Exec
 import org.gradle.api.tasks.SourceSetContainer
 import org.gradle.api.tasks.testing.Test
+import java.io.File
 import java.time.Duration
 import javax.inject.Inject
 
@@ -76,6 +77,61 @@ import javax.inject.Inject
  * ```
  */
 class ProfilerTestPlugin : Plugin<Project> {
+
+    /**
+     * Major version of the *test* JVM, read from its `release` file (`JAVA_VERSION="..."`) rather
+     * than by executing the launcher.
+     *
+     * Executing `$JAVA_TEST_HOME/bin/java -version` (PlatformUtils.testJvmMajorVersion()) is
+     * unreliable here: in the musl split-JDK matrix it has been observed to report the build JDK
+     * (21) even when the test JVM is JDK 8, which put a JDK-21-only `--add-exports` onto a JDK-8
+     * launcher and aborted it. Reading the `release` file is a pure file read of the same
+     * JAVA_TEST_HOME the executable is resolved from — deterministic, no subprocess, no exec-format
+     * or PATH hazards. Returns 0 when it cannot be determined (missing/old `release`), so callers
+     * fail safe: they omit the flag, the profiler degrades to thread-scoped storage, and the
+     * carrier-scoping tests skip — never an abort.
+     */
+    private fun testJvmMajorVersionFromRelease(): Int = try {
+        val release = File(PlatformUtils.testJavaHome(), "release")
+        val version = release.takeIf { it.isFile }
+            ?.readLines()
+            ?.firstOrNull { it.startsWith("JAVA_VERSION=") }
+            ?.substringAfter('=')?.trim()?.trim('"')
+        // "1.8.0_452" -> 8 ; "21.0.5" -> 21
+        val parts = version?.split('.').orEmpty()
+        val majorToken = when {
+            parts.isEmpty() -> ""
+            parts[0] == "1" && parts.size > 1 -> parts[1]
+            else -> parts[0]
+        }
+        majorToken.takeWhile { it.isDigit() }.toIntOrNull() ?: 0
+    } catch (e: Exception) {
+        0
+    }
+
+    /**
+     * JVM args required to enable carrier-scoped OTEL context storage
+     * (`OtelContextStorage.Mode.CARRIER`), or an empty list when the test JVM does not support it.
+     *
+     * Carrier scoping resolves `jdk.internal.misc.CarrierThreadLocal`, which lives in a
+     * non-exported package, so it needs `--add-exports java.base/jdk.internal.misc=ALL-UNNAMED`.
+     * That type only exists on JDK 21+, and the flag *aborts* a Java 8 JVM ("Unrecognized option"),
+     * so it is gated on the version of the actual test JVM.
+     *
+     * MUST be evaluated at task execution time (inside doFirst), not configuration time: the test
+     * JVM is selected via JAVA_TEST_HOME, which the CI only makes resolvable at execution time (see
+     * the `executable` assignments below).
+     */
+    private fun carrierExportJvmArgs(project: Project): List<String> {
+        val major = testJvmMajorVersionFromRelease()
+        val enabled = major >= 21
+        project.logger.info(
+            "ddprof: carrier --add-exports gate — testJavaHome={}, detected major={}, flag {}",
+            PlatformUtils.testJavaHome(), major, if (enabled) "ADDED" else "omitted"
+        )
+        return if (enabled) listOf("--add-exports=java.base/jdk.internal.misc=ALL-UNNAMED") else emptyList()
+    }
+
     override fun apply(project: Project) {
         val extension = project.extensions.create(
             "profilerTest",
@@ -238,6 +294,8 @@ class ProfilerTestPlugin : Plugin<Project> {
             testTask.doFirst {
                 val allArgs = mutableListOf<String>()
                 allArgs.addAll(testConfig.standardJvmArgs)
+                // Version-gated at execution time, when the real test JVM is resolvable.
+                allArgs.addAll(carrierExportJvmArgs(project))
 
                 if (extension.nativeLibDir.isPresent) {
                     allArgs.add("-Djava.library.path=${extension.nativeLibDir.get().asFile.absolutePath}")
@@ -302,6 +360,8 @@ class ProfilerTestPlugin : Plugin<Project> {
 
                 // JVM args
                 allArgs.addAll(testConfig.standardJvmArgs)
+                // Version-gated at execution time, when the real test JVM (JAVA_TEST_HOME) is resolvable.
+                allArgs.addAll(carrierExportJvmArgs(project))
                 if (extension.nativeLibDir.isPresent) {
                     allArgs.add("-Djava.library.path=${extension.nativeLibDir.get().asFile.absolutePath}")
                 }
@@ -661,7 +721,13 @@ abstract class ProfilerTestExtension @Inject constructor(
     abstract val applicationMainClass: Property<String>
 
     init {
-        // Standard JVM arguments for profiler testing
+        // Standard JVM arguments for profiler testing.
+        // NOTE: JDK-version-gated flags (e.g. the carrier-scoping --add-exports) must NOT be
+        // added here. This convention is computed at configuration time, where JAVA_TEST_HOME
+        // is not yet resolvable and PlatformUtils.testJavaHome() falls back to the *build* JDK
+        // (JAVA_HOME) — which misdetects in the musl split-JDK CI (build JDK 21, test JDK 8) and
+        // would emit a JDK-21 flag onto a JDK-8 test JVM. Version-gated flags are added at
+        // execution time in the task doFirst blocks instead (see ProfilerTestPlugin).
         standardJvmArgs.convention(listOf(
             "-Djdk.attach.allowAttachSelf",      // Allow profiler to attach to self
             "-Djol.tryWithSudo=true",            // JOL memory layout analysis
 
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2026, Datadog, Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datadoghq.profiler;
+
+/**
+ * Scope of the OTEL context {@link ThreadContext} storage actually in effect, as reported by
+ * {@link JavaProfiler#contextStorageMode()}. See {@link OtelContextStorage} for how it is
+ * selected.
+ */
+public enum ContextStorageMode {
+  /** Carrier-scoped via {@code jdk.internal.misc.CarrierThreadLocal} (JDK 21+). */
+  CARRIER,
+  /** Legacy virtual-thread-scoped plain {@link ThreadLocal}. */
+  THREAD
+}
@@ -39,8 +39,31 @@ static final class TSCFrequencyHolder {
     }
     private static JavaProfiler instance;
 
-    // Thread-local storage for profiling context
-    private final ThreadLocal<ThreadContext> tlsContextStorage = ThreadLocal.withInitial(JavaProfiler::initializeThreadContext);
+    // Storage for profiling context. Scoped to the carrier thread when available so a
+    // mounted virtual thread resolves to its current carrier's OTEP record (the record the
+    // sampler reads); falls back to plain thread-local storage otherwise. See
+    // OtelContextStorage for the mode selection and the rationale.
+    private final ThreadLocal<ThreadContext> tlsContextStorage = OtelContextStorage.create();
+
+    /**
+     * Returns the calling thread's (or, in carrier mode, its current carrier's)
+     * {@link ThreadContext}, creating and caching it on first use. Replaces the previous
+     * {@code ThreadLocal.withInitial(...)} supplier: a carrier-scoped storage instance is
+     * built reflectively and cannot carry a supplier, so lazy initialization is done here.
+     *
+     * <p>Race-free without synchronization: a carrier runs at most one mounted virtual
+     * thread at a time and this method has no blocking point, so no unmount can occur
+     * mid-call. A redundant re-init could at worst produce a second {@link ThreadContext}
+     * over the same carrier record, which is harmless.
+     */
+    private ThreadContext currentContext() {
+        ThreadContext ctx = tlsContextStorage.get();
+        if (ctx == null) {
+            ctx = initializeThreadContext();
+            tlsContextStorage.set(ctx);
+        }
+        return ctx;
+    }
 
     private JavaProfiler() {
     }
@@ -191,7 +214,7 @@ public void removeThread() {
      */
     @Deprecated
     public void setContext(long spanId, long rootSpanId) {
-        tlsContextStorage.get().put(spanId, rootSpanId);
+        currentContext().put(spanId, rootSpanId);
     }
 
     /**
@@ -203,15 +226,15 @@ public void setContext(long spanId, long rootSpanId) {
      * @param traceIdLow Lower 64 bits of the 128-bit trace ID
      */
     public void setContext(long localRootSpanId, long spanId, long traceIdHigh, long traceIdLow) {
-        tlsContextStorage.get().put(localRootSpanId, spanId, traceIdHigh, traceIdLow);
+        currentContext().put(localRootSpanId, spanId, traceIdHigh, traceIdLow);
     }
 
     /**
      * Resets the current thread's context to zero (traceId=0, spanId=0, localRootSpanId=0).
      * Custom context attributes are also cleared.
      */
     public void clearContext() {
-        tlsContextStorage.get().put(0, 0, 0, 0);
+        currentContext().put(0, 0, 0, 0);
     }
 
     /**
@@ -226,7 +249,7 @@ public void clearContext() {
      *         for this slot
      */
     public boolean setContextAttribute(int offset, String value) {
-        return tlsContextStorage.get().setContextAttribute(offset, value);
+        return currentContext().setContextAttribute(offset, value);
     }
 
     /**
@@ -236,7 +259,7 @@ public boolean setContextAttribute(int offset, String value) {
      * @param offset slot index (0-based, in [0, 9]); out-of-range values are silently ignored
      */
     public void clearContextAttribute(int offset) {
-        tlsContextStorage.get().clearContextAttribute(offset);
+        currentContext().clearContextAttribute(offset);
     }
 
     /**
@@ -263,11 +286,11 @@ public void clearContextAttribute(int offset) {
      *                                  or any active {@code utf8[i]} exceeds 255 bytes
      */
     public boolean setContextAttributesByIdAndBytes(int[] constantIds, byte[][] utf8) {
-        return tlsContextStorage.get().setContextAttributesByIdAndBytes(constantIds, utf8);
+        return currentContext().setContextAttributesByIdAndBytes(constantIds, utf8);
     }
 
     void copyTags(int[] snapshot) {
-        tlsContextStorage.get().copyCustoms(snapshot);
+        currentContext().copyCustoms(snapshot);
     }
 
     /**
@@ -444,8 +467,29 @@ private static ThreadContext initializeThreadContext() {
      */
     private static native ByteBuffer initializeContextTLS0(long[] metadata);
 
+    /**
+     * Returns the {@link ThreadContext} for the current storage slot (the calling thread, or in
+     * {@link ContextStorageMode#CARRIER} its current carrier).
+     *
+     * <p><b>Do not cache the returned instance across a point where the calling thread may be
+     * unmounted and remounted on a different carrier</b> (any blocking operation on a virtual
+     * thread). In carrier mode the returned context's buffer targets the carrier that was mounted
+     * at call time; after migration it no longer corresponds to the current carrier's record — the
+     * sampler reads the new carrier, and once the old carrier's OS thread exits the buffer dangles.
+     * Callers that write context (span/attributes) should re-fetch per use — the {@code setContext*}
+     * methods already do this internally via {@code currentContext()}.
+     */
     public ThreadContext getThreadContext() {
-        return tlsContextStorage.get();
+        return currentContext();
+    }
+
+    /**
+     * Diagnostics/tests: the resolved OTEL context storage mode, as selected by
+     * {@code -D}{@value OtelContextStorage#MODE_PROPERTY} and the availability of
+     * {@code jdk.internal.misc.CarrierThreadLocal}.
+     */
+    public ContextStorageMode contextStorageMode() {
+        return OtelContextStorage.modeOf(tlsContextStorage);
     }
 
 // --- test and debug utility methods
@@ -459,9 +503,10 @@ public ThreadContext getThreadContext() {
     public static native void dumpContext();
 
     /**
-     * Resets the cached ThreadContext for the current thread.
-     * The next call to {@link #getThreadContext()} or any {@code setContext} overload
-     * will re-create it with fresh OTEL TLS buffers.
+     * Resets the cached ThreadContext for the current storage slot — the calling thread in
+     * {@link ContextStorageMode#THREAD}, or its current carrier in
+     * {@link ContextStorageMode#CARRIER}. The next call to {@link #getThreadContext()}
+     * or any {@code setContext} overload will re-create it with fresh OTEL TLS buffers.
      */
     public void resetThreadContext() {
         tlsContextStorage.remove();