From 500389219057f9a6a1463ba0ad8d5f2172acba6a Mon Sep 17 00:00:00 2001
From: Brian Marks <brian.marks@datadoghq.com>
Date: Thu, 27 Aug 2026 17:06:42 -0400
Subject: [PATCH 1/3] Support stable OTel deployment environment attribute

---
 .../Configuration/MutableSettings.cs          |  4 ++-
 .../Configuration/MutableSettingsTests.cs     | 32 ++++++++++++++++---
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/tracer/src/Datadog.Trace/Configuration/MutableSettings.cs b/tracer/src/Datadog.Trace/Configuration/MutableSettings.cs
index caf31e49e2d5..c8c3ede81b71 100644
--- a/tracer/src/Datadog.Trace/Configuration/MutableSettings.cs
+++ b/tracer/src/Datadog.Trace/Configuration/MutableSettings.cs
@@ -1107,8 +1107,10 @@ private static ConfigurationBuilder.ClassConfigurationResultWithKey<IDictionary<
         if (original.ConfigurationResult is { IsValid: true, Result: { } values })
         {
             // Update well-known service information resources
-            if (values.TryGetValue("deployment.environment", out var envValue))
+            if (values.TryGetValue("deployment.environment.name", out var envValue) ||
+                values.TryGetValue("deployment.environment", out envValue))
             {
+                values.Remove("deployment.environment.name");
                 values.Remove("deployment.environment");
                 values[Tags.Env] = envValue;
             }
diff --git a/tracer/test/Datadog.Trace.Tests/Configuration/MutableSettingsTests.cs b/tracer/test/Datadog.Trace.Tests/Configuration/MutableSettingsTests.cs
index a594cebf28d0..612815439c4c 100644
--- a/tracer/test/Datadog.Trace.Tests/Configuration/MutableSettingsTests.cs
+++ b/tracer/test/Datadog.Trace.Tests/Configuration/MutableSettingsTests.cs
@@ -652,20 +652,44 @@ public void DDTagsSetsServiceInformation()
             mutable.GitCommitSha.Should().Be("42");
         }
 
-        [Fact]
-        public void OTELTagsSetsServiceInformation()
+        [Theory]
+        [InlineData("deployment.environment.name=stable_env", "stable_env")]
+        [InlineData("deployment.environment=legacy_env", "legacy_env")]
+        [InlineData("deployment.environment.name=stable_env,deployment.environment=legacy_env", "stable_env")]
+        [InlineData("deployment.environment=legacy_env,deployment.environment.name=stable_env", "stable_env")]
+        public void OTELTagsSetServiceInformation(string environmentAttributes, string expectedEnvironment)
         {
             var source = new NameValueConfigurationSource(new()
             {
-                { "OTEL_RESOURCE_ATTRIBUTES", "deployment.environment=datadog_env,service.name=datadog_service,service.version=datadog_version" },
+                { ConfigurationKeys.OpenTelemetry.ResourceAttributes, $"{environmentAttributes},service.name=datadog_service,service.version=datadog_version,custom.attribute=custom_value" },
             });
 
             var tracerSettings = new TracerSettings(source);
             var mutable = GetMutableSettings(source, tracerSettings);
 
-            mutable.Environment.Should().Be("datadog_env");
+            mutable.Environment.Should().Be(expectedEnvironment);
             mutable.ServiceVersion.Should().Be("datadog_version");
             mutable.ServiceName.Should().Be("datadog_service");
+            mutable.GlobalTags.Should().NotContainKey("deployment.environment.name");
+            mutable.GlobalTags.Should().NotContainKey("deployment.environment");
+            mutable.GlobalTags.Should().Contain("custom.attribute", "custom_value");
+        }
+
+        [Fact]
+        public void DDEnvTakesPrecedenceOverOTELTags()
+        {
+            var source = new NameValueConfigurationSource(new()
+            {
+                { ConfigurationKeys.Environment, "datadog_env" },
+                { ConfigurationKeys.OpenTelemetry.ResourceAttributes, "deployment.environment=legacy_env,deployment.environment.name=stable_env" },
+            });
+
+            var tracerSettings = new TracerSettings(source);
+            var mutable = GetMutableSettings(source, tracerSettings);
+
+            mutable.Environment.Should().Be("datadog_env");
+            mutable.GlobalTags.Should().NotContainKey("deployment.environment.name");
+            mutable.GlobalTags.Should().NotContainKey("deployment.environment");
         }
 
         [Fact]

From c8b10b188400b0dd3bfb7fdd4ac4797a60b7aebf Mon Sep 17 00:00:00 2001
From: Zach Montoya <zach.montoya@datadoghq.com>
Date: Thu, 3 Sep 2026 10:54:03 -0700
Subject: [PATCH 2/3] Update one more location where we parse
 deployment.environment so that we prefer deployment.environment.name

---
 .../src/Datadog.Trace/Activity/OtlpHelpers.cs |  2 +-
 .../Tagging/ActivityTagsTests.cs              | 42 +++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/tracer/src/Datadog.Trace/Activity/OtlpHelpers.cs b/tracer/src/Datadog.Trace/Activity/OtlpHelpers.cs
index 490a1f426e03..9a3a06187446 100644
--- a/tracer/src/Datadog.Trace/Activity/OtlpHelpers.cs
+++ b/tracer/src/Datadog.Trace/Activity/OtlpHelpers.cs
@@ -127,7 +127,7 @@ private static void AgentConvertSpan<TInner>(TInner activity, Span span, bool op
             // Fixup "env" tag
             if (traceContext is not null
              && traceContext.Environment is null
-             && span.GetTag("deployment.environment") is { Length: > 0 } otelServiceEnv)
+             && (span.GetTag("deployment.environment.name") ?? span.GetTag("deployment.environment")) is { Length: > 0 } otelServiceEnv)
             {
                 traceContext.Environment = otelServiceEnv;
             }
diff --git a/tracer/test/Datadog.Trace.Tests/Tagging/ActivityTagsTests.cs b/tracer/test/Datadog.Trace.Tests/Tagging/ActivityTagsTests.cs
index 796710d17b22..aa8a11479ea5 100644
--- a/tracer/test/Datadog.Trace.Tests/Tagging/ActivityTagsTests.cs
+++ b/tracer/test/Datadog.Trace.Tests/Tagging/ActivityTagsTests.cs
@@ -160,4 +160,46 @@ public async Task ActivityLink_PreservesTraceStateWithoutParsingOtelTraceState()
         spanLinkContext.AdditionalW3CTraceState.Should().Be("ot=rv:ef284ace7a91e1;th:e6666666666668");
         spanLinkContext.OtelTraceState.Should().BeNull();
     }
+
+    [Theory]
+    [InlineData("deployment.environment.name", "stable_env")]
+    [InlineData("deployment.environment", "legacy_env")]
+    public async Task Environment_ShouldBe_FixedUpFromActivityTag(string tagKey, string tagValue)
+    {
+        var activityMock = new Mock<IActivity5>();
+        activityMock.Setup(x => x.Kind).Returns(ActivityKind.Producer);
+
+        var tagObjects = new Dictionary<string, object> { { tagKey, tagValue } };
+        activityMock.Setup(x => x.TagObjects).Returns(tagObjects);
+
+        // UpdateSpanFromActivity implicitly accesses Tracer.Instance if there's no associated Tracer in the span
+        await using var tracer = TracerHelper.CreateWithFakeAgent();
+        using var span = tracer.StartSpan("operation", new OpenTelemetryTags());
+
+        OtlpHelpers.UpdateSpanFromActivity(activityMock.Object, span);
+
+        span.Context.TraceContext!.Environment.Should().Be(tagValue);
+    }
+
+    [Fact]
+    public async Task Environment_StableTagName_ShouldTakePrecedenceOverLegacyTagName()
+    {
+        var activityMock = new Mock<IActivity5>();
+        activityMock.Setup(x => x.Kind).Returns(ActivityKind.Producer);
+
+        var tagObjects = new Dictionary<string, object>
+        {
+            { "deployment.environment", "legacy_env" },
+            { "deployment.environment.name", "stable_env" }
+        };
+        activityMock.Setup(x => x.TagObjects).Returns(tagObjects);
+
+        // UpdateSpanFromActivity implicitly accesses Tracer.Instance if there's no associated Tracer in the span
+        await using var tracer = TracerHelper.CreateWithFakeAgent();
+        using var span = tracer.StartSpan("operation", new OpenTelemetryTags());
+
+        OtlpHelpers.UpdateSpanFromActivity(activityMock.Object, span);
+
+        span.Context.TraceContext!.Environment.Should().Be("stable_env");
+    }
 }

From 08968bcb78ca4eaadf574e39a4e0697bb85d76f4 Mon Sep 17 00:00:00 2001
From: Zach Montoya <zach.montoya@datadoghq.com>
Date: Thu, 17 Sep 2026 16:03:13 -0400
Subject: [PATCH 3/3] Update handling of empty deployment.environment.name
 resource attribute so that it falls back to the legacy deployment.environment
 resource attribute

---
 .../Configuration/MutableSettings.cs          |  3 +-
 .../Configuration/MutableSettingsTests.cs     | 31 +++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/tracer/src/Datadog.Trace/Configuration/MutableSettings.cs b/tracer/src/Datadog.Trace/Configuration/MutableSettings.cs
index c8c3ede81b71..171dd9d40f75 100644
--- a/tracer/src/Datadog.Trace/Configuration/MutableSettings.cs
+++ b/tracer/src/Datadog.Trace/Configuration/MutableSettings.cs
@@ -1107,7 +1107,8 @@ private static ConfigurationBuilder.ClassConfigurationResultWithKey<IDictionary<
         if (original.ConfigurationResult is { IsValid: true, Result: { } values })
         {
             // Update well-known service information resources
-            if (values.TryGetValue("deployment.environment.name", out var envValue) ||
+            // an empty "deployment.environment.name" falls back to the legacy "deployment.environment"
+            if ((values.TryGetValue("deployment.environment.name", out var envValue) && !string.IsNullOrEmpty(envValue)) ||
                 values.TryGetValue("deployment.environment", out envValue))
             {
                 values.Remove("deployment.environment.name");
diff --git a/tracer/test/Datadog.Trace.Tests/Configuration/MutableSettingsTests.cs b/tracer/test/Datadog.Trace.Tests/Configuration/MutableSettingsTests.cs
index 612815439c4c..1445d3ed8d9f 100644
--- a/tracer/test/Datadog.Trace.Tests/Configuration/MutableSettingsTests.cs
+++ b/tracer/test/Datadog.Trace.Tests/Configuration/MutableSettingsTests.cs
@@ -675,6 +675,37 @@ public void OTELTagsSetServiceInformation(string environmentAttributes, string e
             mutable.GlobalTags.Should().Contain("custom.attribute", "custom_value");
         }
 
+        [Fact]
+        public void EmptyStableEnvironmentNameFallsBackToLegacyEnvironment()
+        {
+            var source = new NameValueConfigurationSource(new()
+            {
+                { ConfigurationKeys.OpenTelemetry.ResourceAttributes, "deployment.environment.name=,deployment.environment=legacy_env" },
+            });
+
+            var tracerSettings = new TracerSettings(source);
+            var mutable = GetMutableSettings(source, tracerSettings);
+
+            mutable.Environment.Should().Be("legacy_env");
+            mutable.GlobalTags.Should().NotContainKey("deployment.environment.name");
+            mutable.GlobalTags.Should().NotContainKey("deployment.environment");
+        }
+
+        [Fact]
+        public void EmptyStableEnvironmentNameWithNoLegacyEnvironmentIsUnset()
+        {
+            var source = new NameValueConfigurationSource(new()
+            {
+                { ConfigurationKeys.OpenTelemetry.ResourceAttributes, "deployment.environment.name=" },
+            });
+
+            var tracerSettings = new TracerSettings(source);
+            var mutable = GetMutableSettings(source, tracerSettings);
+
+            mutable.Environment.Should().BeNullOrEmpty();
+            mutable.GlobalTags.Should().NotContainKey("deployment.environment.name");
+        }
+
         [Fact]
         public void DDEnvTakesPrecedenceOverOTELTags()
         {