Add stable session ID headers to telemetry requests

Implements the Stable Service Instance Identifier RFC for Java.

- Add DD-Session-ID header (= runtime_id) to all telemetry requests
- Add DD-Root-Session-ID header when process is a child (inherited from parent)
- Read _DD_ROOT_JAVA_SESSION_ID from environment at init time
- Auto-propagate _DD_ROOT_JAVA_SESSION_ID to child processes via
  ProcessBuilder instrumentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: khanayan123

dd-java-agent/instrumentation/java/java-lang/java-lang-1.8/src/main/java/datadog/trace/instrumentation/java/lang/ProcessBuilderSessionIdAdvice.java

@@ -0,0 +1,15 @@
+package datadog.trace.instrumentation.java.lang;
+
+import datadog.trace.api.Config;
+import net.bytebuddy.asm.Advice;
+
+class ProcessBuilderSessionIdAdvice {
+  @Advice.OnMethodEnter(suppress = Throwable.class)
+  public static void beforeStart(@Advice.This final ProcessBuilder self) {
+    Config config = Config.get();
+    String rootSessionId = config.getRootSessionId();
+    if (rootSessionId != null) {
+      self.environment().put("_DD_ROOT_JAVA_SESSION_ID", rootSessionId);
+    }
+  }
+}

dd-java-agent/instrumentation/java/java-lang/java-lang-1.8/src/main/java/datadog/trace/instrumentation/java/lang/ProcessBuilderSessionIdInstrumentation.java

@@ -0,0 +1,35 @@
+package datadog.trace.instrumentation.java.lang;
+
+import static datadog.trace.agent.tooling.bytebuddy.matcher.NameMatchers.named;
+import static net.bytebuddy.matcher.ElementMatchers.takesNoArguments;
+
+import com.google.auto.service.AutoService;
+import datadog.trace.agent.tooling.Instrumenter;
+import datadog.trace.agent.tooling.InstrumenterModule;
+import datadog.trace.api.Platform;
+
+@AutoService(InstrumenterModule.class)
+public class ProcessBuilderSessionIdInstrumentation extends InstrumenterModule.Tracing
+    implements Instrumenter.ForSingleType, Instrumenter.HasMethodAdvice {
+
+  public ProcessBuilderSessionIdInstrumentation() {
+    super("process-session-id");
+  }
+
+  @Override
+  protected boolean defaultEnabled() {
+    return super.defaultEnabled() && !Platform.isNativeImageBuilder();
+  }
+
+  @Override
+  public String instrumentedType() {
+    return "java.lang.ProcessBuilder";
+  }
+
+  @Override
+  public void methodAdvice(MethodTransformer transformer) {
+    transformer.applyAdvice(
+        named("start").and(takesNoArguments()),
+        packageName + ".ProcessBuilderSessionIdAdvice");
+  }
+}

dd-java-agent/instrumentation/java/java-lang/java-lang-1.8/src/test/groovy/datadog/trace/instrumentation/java/lang/ProcessBuilderSessionIdSpecification.groovy

@@ -0,0 +1,36 @@
+package datadog.trace.instrumentation.java.lang
+
+import datadog.trace.agent.test.AgentTestRunner
+import datadog.trace.api.Config
+
+class ProcessBuilderSessionIdSpecification extends AgentTestRunner {
+
+  def "ProcessBuilder injects root session ID into child environment"() {
+    setup:
+    def command = ['sh', '-c', 'echo $_DD_ROOT_JAVA_SESSION_ID']
+    def pb = new ProcessBuilder(command)
+
+    when:
+    def process = pb.start()
+    def output = process.inputStream.text.trim()
+    process.waitFor()
+
+    then:
+    output == Config.get().getRootSessionId()
+  }
+
+  def "child process inherits root session ID not runtime ID"() {
+    setup:
+    def command = ['sh', '-c', 'echo $_DD_ROOT_JAVA_SESSION_ID']
+    def pb = new ProcessBuilder(command)
+
+    when:
+    def process = pb.start()
+    def output = process.inputStream.text.trim()
+    process.waitFor()
+
+    then:
+    output == Config.get().getRootSessionId()
+    Config.get().getRootSessionId() == Config.get().getRuntimeId()
+  }
+}

internal-api/src/main/java/datadog/trace/api/Config.java

@@ -687,6 +687,7 @@
 import static datadog.trace.util.ConfigStrings.propertyNameToEnvironmentVariableName;
 import static datadog.trace.util.json.JsonPathParser.parseJsonPaths;
 
+import datadog.environment.EnvironmentVariables;
 import datadog.environment.JavaVirtualMachine;
 import datadog.environment.OperatingSystem;
 import datadog.environment.SystemProperties;
@@ -792,6 +793,12 @@ public class Config {
    */
   static class RuntimeIdHolder {
     static final String runtimeId = RandomUtils.randomUUID().toString();
+    static final String rootSessionId = initRootSessionId();
+
+    private static String initRootSessionId() {
+      String inherited = EnvironmentVariables.get("_DD_ROOT_JAVA_SESSION_ID");
+      return inherited != null ? inherited : runtimeId;
+    }
   }
 
   static class HostNameHolder {
@@ -3123,6 +3130,10 @@ public String getRuntimeId() {
     return runtimeIdEnabled ? RuntimeIdHolder.runtimeId : "";
   }
 
+  public String getRootSessionId() {
+    return RuntimeIdHolder.rootSessionId;
+  }
+
   public Long getProcessId() {
     return PidHelper.getPidAsLong();
   }

telemetry/src/main/java/datadog/telemetry/TelemetryRequest.java

@@ -80,6 +80,16 @@ public Request.Builder httpRequest() {
       builder.addHeader("DD-Telemetry-Debug-Enabled", "true");
     }
 
+    Config config = Config.get();
+    String sessionId = config.getRuntimeId();
+    if (sessionId != null && !sessionId.isEmpty()) {
+      builder.addHeader("DD-Session-ID", sessionId);
+    }
+    String rootSessionId = config.getRootSessionId();
+    if (rootSessionId != null && !rootSessionId.equals(sessionId)) {
+      builder.addHeader("DD-Root-Session-ID", rootSessionId);
+    }
+
     return builder;
   }
 

telemetry/src/test/groovy/datadog/telemetry/TestTelemetryRouter.groovy

@@ -84,7 +84,8 @@ class TestTelemetryRouter extends TelemetryRouter {
         'DD-Client-Library-Language',
         'DD-Client-Library-Version',
         'DD-Telemetry-API-Version',
-        'DD-Telemetry-Request-Type'
+        'DD-Telemetry-Request-Type',
+        'DD-Session-ID'
       ])
       assert this.request.header('Content-Type') == 'application/json; charset=utf-8'
       assert this.request.header('Content-Length').toInteger() > 0
@@ -94,6 +95,8 @@ class TestTelemetryRouter extends TelemetryRouter {
       assert this.request.header('DD-Telemetry-Request-Type') == requestType.toString()
       def entityId = this.request.header('Datadog-Entity-ID')
       assert entityId == null || entityId.startsWith("in-") || entityId.startsWith("cin-")
+      def sessionId = this.request.header('DD-Session-ID')
+      assert sessionId =~ /[\da-f]{8}-([\da-f]{4}-){3}[\da-f]{12}/
       return this
     }