feat: add DD-Session-ID and DD-Root-Session-ID telemetry headers

khanayan123 · claude · khanayan123 · commit dc79c61edfa0 · 2026-03-25T11:19:56.000-04:00
Implements the Stable Service Instance Identifier RFC for .NET telemetry.

- DD-Session-ID (= runtime_id) added to every telemetry request
- DD-Root-Session-ID added only when the process inherited _DD_ROOT_DOTNET_SESSION_ID from a parent (child process scenario)
- Root session ID auto-propagates to child processes via Environment.SetEnvironmentVariable()
- _DD_ROOT_DOTNET_SESSION_ID registered in supported-configurations.yaml as ConfigurationKeys.Telemetry.RootSessionId

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/tracer/src/Datadog.Trace/Configuration/supported-configurations.yaml b/tracer/src/Datadog.Trace/Configuration/supported-configurations.yaml
@@ -1571,6 +1571,15 @@ supportedConfigurations:
     documentation: |-
       Configuration key for whether telemetry metrics should be sent.
       <see cref="Datadog.Trace.Telemetry.TelemetrySettings.MetricsEnabled"/>
+  _DD_ROOT_DOTNET_SESSION_ID:
+  - implementation: A
+    type: string
+    default: null
+    product: Telemetry
+    const_name: RootSessionId
+    documentation: |-
+      Internal env var for propagating the root session ID to child processes.
+      Set automatically by the tracer at init time; not user-configurable.
   DD_TEST_MANAGEMENT_ATTEMPT_TO_FIX_RETRIES:
   - implementation: A
     type: int
diff --git a/tracer/src/Datadog.Trace/Generated/net461/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/ConfigurationKeys.Telemetry.g.cs b/tracer/src/Datadog.Trace/Generated/net461/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/ConfigurationKeys.Telemetry.g.cs
@@ -17,6 +17,12 @@ internal static partial class ConfigurationKeys
 {
     internal static class Telemetry
     {
+        /// <summary>
+        /// Internal env var for propagating the root session ID to child processes.
+        /// Set automatically by the tracer at init time; not user-configurable.
+        /// </summary>
+        public const string RootSessionId = "_DD_ROOT_DOTNET_SESSION_ID";
+
         /// <summary>
         /// SSI variable that provides a unique identifier for the instrumentation installation.
         /// Used for tracking and correlation purposes in telemetry.
diff --git a/tracer/src/Datadog.Trace/Generated/net6.0/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/ConfigurationKeys.Telemetry.g.cs b/tracer/src/Datadog.Trace/Generated/net6.0/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/ConfigurationKeys.Telemetry.g.cs
@@ -17,6 +17,12 @@ internal static partial class ConfigurationKeys
 {
     internal static class Telemetry
     {
+        /// <summary>
+        /// Internal env var for propagating the root session ID to child processes.
+        /// Set automatically by the tracer at init time; not user-configurable.
+        /// </summary>
+        public const string RootSessionId = "_DD_ROOT_DOTNET_SESSION_ID";
+
         /// <summary>
         /// SSI variable that provides a unique identifier for the instrumentation installation.
         /// Used for tracking and correlation purposes in telemetry.
diff --git a/tracer/src/Datadog.Trace/Generated/netcoreapp3.1/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/ConfigurationKeys.Telemetry.g.cs b/tracer/src/Datadog.Trace/Generated/netcoreapp3.1/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/ConfigurationKeys.Telemetry.g.cs
@@ -17,6 +17,12 @@ internal static partial class ConfigurationKeys
 {
     internal static class Telemetry
     {
+        /// <summary>
+        /// Internal env var for propagating the root session ID to child processes.
+        /// Set automatically by the tracer at init time; not user-configurable.
+        /// </summary>
+        public const string RootSessionId = "_DD_ROOT_DOTNET_SESSION_ID";
+
         /// <summary>
         /// SSI variable that provides a unique identifier for the instrumentation installation.
         /// Used for tracking and correlation purposes in telemetry.
diff --git a/tracer/src/Datadog.Trace/Generated/netstandard2.0/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/ConfigurationKeys.Telemetry.g.cs b/tracer/src/Datadog.Trace/Generated/netstandard2.0/Datadog.Trace.SourceGenerators/ConfigurationKeysGenerator/ConfigurationKeys.Telemetry.g.cs
@@ -17,6 +17,12 @@ internal static partial class ConfigurationKeys
 {
     internal static class Telemetry
     {
+        /// <summary>
+        /// Internal env var for propagating the root session ID to child processes.
+        /// Set automatically by the tracer at init time; not user-configurable.
+        /// </summary>
+        public const string RootSessionId = "_DD_ROOT_DOTNET_SESSION_ID";
+
         /// <summary>
         /// SSI variable that provides a unique identifier for the instrumentation installation.
         /// Used for tracking and correlation purposes in telemetry.
diff --git a/tracer/src/Datadog.Trace/Telemetry/TelemetryConstants.cs b/tracer/src/Datadog.Trace/Telemetry/TelemetryConstants.cs
@@ -21,6 +21,9 @@ internal static class TelemetryConstants
         public const string ClientLibraryLanguageHeader = "DD-Client-Library-Language";
         public const string ClientLibraryVersionHeader = "DD-Client-Library-Version";
 
+        public const string SessionIdHeader = "DD-Session-ID";
+        public const string RootSessionIdHeader = "DD-Root-Session-ID";
+
         public const string CloudProviderHeader = "DD-Cloud-Provider";
         public const string CloudResourceTypeHeader = "DD-Cloud-Resource-Type";
         public const string CloudResourceIdentifierHeader = "DD-Cloud-Resource-Identifier";
diff --git a/tracer/src/Datadog.Trace/Telemetry/Transports/JsonTelemetryTransport.cs b/tracer/src/Datadog.Trace/Telemetry/Transports/JsonTelemetryTransport.cs
@@ -13,6 +13,7 @@
 using Datadog.Trace.Logging;
 using Datadog.Trace.PlatformHelpers;
 using Datadog.Trace.Telemetry.Metrics;
+using Datadog.Trace.Util;
 using Datadog.Trace.Util.Http;
 using Datadog.Trace.Vendors.Newtonsoft.Json;
 using Datadog.Trace.Vendors.Newtonsoft.Json.Serialization;
@@ -56,6 +57,14 @@ public async Task<TelemetryPushResult> PushTelemetry(TelemetryData data)
                     request.AddHeader(TelemetryConstants.DebugHeader, "true");
                 }
 
+                var sessionId = RuntimeId.Get();
+                request.AddHeader(TelemetryConstants.SessionIdHeader, sessionId);
+                var rootSessionId = RuntimeId.GetRootSessionId();
+                if (rootSessionId != sessionId)
+                {
+                    request.AddHeader(TelemetryConstants.RootSessionIdHeader, rootSessionId);
+                }
+
                 request.AddContainerMetadataHeaders(_containerMetadata);
 
                 TelemetryFactory.Metrics.RecordCountTelemetryApiRequests(endpointMetricTag);
diff --git a/tracer/src/Datadog.Trace/Util/RuntimeId.cs b/tracer/src/Datadog.Trace/Util/RuntimeId.cs
@@ -5,6 +5,7 @@
 
 using System;
 using System.Threading;
+using Datadog.Trace.Configuration;
 using Datadog.Trace.Logging;
 
 namespace Datadog.Trace.Util
@@ -13,10 +14,13 @@ internal static class RuntimeId
     {
         private static readonly IDatadogLogger Log = DatadogLogging.GetLoggerFor(typeof(RuntimeId));
         private static string _runtimeId;
+        private static string _rootSessionId;
 
-        public static string Get() => LazyInitializer.EnsureInitialized(ref _runtimeId, () => GetImpl());
+        public static string Get() => LazyInitializer.EnsureInitialized(ref _runtimeId, () => GetRuntimeIdImpl());
 
-        private static string GetImpl()
+        public static string GetRootSessionId() => LazyInitializer.EnsureInitialized(ref _rootSessionId, () => GetRootSessionIdImpl());
+
+        private static string GetRuntimeIdImpl()
         {
             if (NativeLoader.TryGetRuntimeIdFromNative(out var runtimeId))
             {
@@ -29,5 +33,19 @@ private static string GetImpl()
 
             return guid;
         }
+
+        private static string GetRootSessionIdImpl()
+        {
+            var inherited = EnvironmentHelpers.GetEnvironmentVariable(ConfigurationKeys.Telemetry.RootSessionId);
+            if (!string.IsNullOrEmpty(inherited))
+            {
+                Log.Debug("Inherited root session ID from parent: {RootSessionId}", inherited);
+                return inherited;
+            }
+
+            var rootId = Get();
+            EnvironmentHelpers.SetEnvironmentVariable(ConfigurationKeys.Telemetry.RootSessionId, rootId);
+            return rootId;
+        }
     }
 }
diff --git a/tracer/test/Datadog.Trace.IntegrationTests/TelemetryTransportTests.cs b/tracer/test/Datadog.Trace.IntegrationTests/TelemetryTransportTests.cs
@@ -14,6 +14,7 @@
 using Datadog.Trace.Telemetry;
 using Datadog.Trace.Telemetry.Transports;
 using Datadog.Trace.TestHelpers;
+using Datadog.Trace.Util;
 using FluentAssertions;
 using FluentAssertions.Execution;
 using Xunit;
@@ -116,6 +117,12 @@ public async Task SetsRequiredHeaders(bool agentless, bool useCloudAgentless)
                 { "DD-Client-Library-Version", TracerConstants.AssemblyVersion },
             };
 
+            // DD-Session-ID is always present and equals the runtime ID
+            allExpected.Add(TelemetryConstants.SessionIdHeader, RuntimeId.Get());
+
+            // DD-Root-Session-ID is absent when rootSessionId == runtimeId (normal process)
+            // We can't assert absence in the loop below, so we check it separately after
+
             if (ContainerMetadata.Instance.ContainerId is { } containerId)
             {
                 allExpected.Add(AgentHttpHeaderNames.ContainerId, containerId);
@@ -149,6 +156,12 @@ public async Task SetsRequiredHeaders(bool agentless, bool useCloudAgentless)
                     }
                 }
 
+                // DD-Root-Session-ID should be absent in a normal (non-child) process
+                if (RuntimeId.GetRootSessionId() == RuntimeId.Get())
+                {
+                    headers.AllKeys.Should().NotContain(TelemetryConstants.RootSessionIdHeader);
+                }
+
                 // should have either content-length or chunked encoding
                 headers.AllKeys.Should()
                        .Contain(s => s.Equals("Content-Type", StringComparison.OrdinalIgnoreCase)
diff --git a/tracer/test/Datadog.Trace.Tests/Telemetry/ConfigurationTests.cs b/tracer/test/Datadog.Trace.Tests/Telemetry/ConfigurationTests.cs
@@ -52,6 +52,7 @@ public class ConfigurationTests
                 "DD_CIVISIBILITY_CODE_COVERAGE_MODE",
                 "DD_CIVISIBILITY_AUTO_INSTRUMENTATION_PROVIDER",
                 // Internal env vars that we only ever read from environment
+                "_DD_ROOT_DOTNET_SESSION_ID",
                 "DD_INTERNAL_TRACE_NATIVE_ENGINE_PATH",
                 "DD_INTERNAL_PROFILING_NATIVE_ENGINE_PATH",
                 "DD_DOTNET_TRACER_HOME",
diff --git a/tracer/test/Datadog.Trace.Tests/Telemetry/Transports/JsonTelemetryTransportTests.cs b/tracer/test/Datadog.Trace.Tests/Telemetry/Transports/JsonTelemetryTransportTests.cs
@@ -11,6 +11,7 @@
 using Datadog.Trace.Agent.Transports;
 using Datadog.Trace.PlatformHelpers;
 using Datadog.Trace.Telemetry;
+using Datadog.Trace.Util;
 using Datadog.Trace.Telemetry.Transports;
 using Datadog.Trace.TestHelpers.FluentAssertionsExtensions.Json;
 using Datadog.Trace.TestHelpers.TransportHelpers;
@@ -74,7 +75,8 @@ public async Task ShouldContainRequiredHeaders(bool debugEnabled, [Combinatorial
                 { "DD-Telemetry-API-Version", TelemetryConstants.ApiVersionV2 },
                 { "DD-Telemetry-Request-Type", "my-request-type" },
                 { "Datadog-Container-ID", "my-container-id" },
-                { "Datadog-Entity-ID", "my-entity-id" }
+                { "Datadog-Entity-ID", "my-entity-id" },
+                { TelemetryConstants.SessionIdHeader, RuntimeId.Get() },
             };
             if (debugEnabled)
             {
diff --git a/tracer/test/Datadog.Trace.Tests/TracerTests.cs b/tracer/test/Datadog.Trace.Tests/TracerTests.cs
@@ -561,6 +561,21 @@ public void RuntimeId()
             Guid.TryParse(runtimeId, out _).Should().BeTrue();
         }
 
+        [Fact]
+        public void RootSessionId_DefaultsToRuntimeId()
+        {
+            var rootSessionId = Datadog.Trace.Util.RuntimeId.GetRootSessionId();
+            rootSessionId.Should().Be(Datadog.Trace.Util.RuntimeId.Get());
+        }
+
+        [Fact]
+        public void RootSessionId_SetsEnvVar()
+        {
+            var rootSessionId = Datadog.Trace.Util.RuntimeId.GetRootSessionId();
+            Environment.GetEnvironmentVariable(ConfigurationKeys.Telemetry.RootSessionId)
+                       .Should().Be(rootSessionId);
+        }
+
         [Fact]
         public async Task ForceFlush()
         {

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,12 @@ internal static partial class ConfigurationKeys`
`17`	`17`	`{`
`18`	`18`	`internal static class Telemetry`
`19`	`19`	`{`
	`20`	`+ /// <summary>`
	`21`	`+ /// Internal env var for propagating the root session ID to child processes.`
	`22`	`+ /// Set automatically by the tracer at init time; not user-configurable.`
	`23`	`+ /// </summary>`
	`24`	`+ public const string RootSessionId = "_DD_ROOT_DOTNET_SESSION_ID";`
	`25`	`+`
`20`	`26`	`/// <summary>`
`21`	`27`	`/// SSI variable that provides a unique identifier for the instrumentation installation.`
`22`	`28`	`/// Used for tracking and correlation purposes in telemetry.`