make DD_DOTNET_TRACER_HOME optional in managed loader (#7568)

~_This PR is stacked on #7594. Merge that PR first._~

## Summary of changes

Make `DD_DOTNET_TRACER_HOME` optional. If not set, try to figure out the
path from `COR_PROFILER_PATH`/`CORECLR_PROFILER_PATH` and friends.

## Reason for change

One less env var for users to set manually. Easier onboarding, less
error-prone.

I recently worked on an escalation where `DD_DOTNET_TRACER_HOME` was set
to the wrong path so the tracer was not loading.

## Implementation details

The implementation makes `DD_DOTNET_TRACER_HOME` optional by adding
fallback logic to derive the tracer home path from the profiler path
environment variables:

  1. **New method `GetTracerHomePath`** (`Startup.cs:150-178`):
- First checks for explicit `DD_DOTNET_TRACER_HOME` setting (preserves
backward compatibility)
- Falls back to computing the path from architecture-specific profiler
path env vars (e.g., `CORECLR_PROFILER_PATH_64`, `COR_PROFILER_PATH_64`)
- If not found, tries the generic profiler path env var (e.g.,
`CORECLR_PROFILER_PATH`, `COR_PROFILER_PATH`)

2. **New method `ComputeTracerHomePathFromProfilerPath`**
(`Startup.cs:180-218`):
- Takes a profiler path like
`C:\tracer\win-x64\Datadog.Trace.ClrProfiler.Native.dll`
     - Extracts the parent directory
- If the parent directory name matches a known architecture folder
(e.g., `win-x64`, `linux-arm64`, `osx`), goes up one more level
     - Returns the computed tracer home path

  3. **Platform-specific helper methods**:
- `GetProfilerPathEnvVarNameForArch()`: Returns the
architecture-specific env var name (`CORECLR_PROFILER_PATH_64` on .NET
Core x64, `COR_PROFILER_PATH_32` on .NET Framework x86, etc.)
- `GetProfilerPathEnvVarNameFallback()`: Returns the generic env var
name (`CORECLR_PROFILER_PATH` or `COR_PROFILER_PATH`)

  4. **Architecture directory detection**:
- Maintains a `HashSet<string>` of known architecture directories
(`win-x64`, `win-x86`, `linux-x64`, `linux-arm64`, etc)

## Test coverage

**Unit tests**
(`tracer/test/Datadog.Trace.Tests/ClrProfiler/Managed/Loader/`):
- Environment variable reading and fallback logic
(`StartupNetCoreTests.cs`, `StartupNetFrameworkTests.cs`)
- `GetTracerHomePath()` with explicit `DD_DOTNET_TRACER_HOME`
(with/without whitespace)
- `GetTracerHomePath()` with architecture-specific profiler path
fallback
- `GetTracerHomePath()` with generic profiler path fallback
- `ComputeTracerHomePathFromProfilerPath()` with all architecture
directories
- Edge cases: empty values, whitespace, missing variables, null handling

**Integration tests**:
- Added `WhenOmittingTracerHome_InstrumentsApp()` test in
`InstrumentationTests.cs` that explicitly omits `DD_DOTNET_TRACER_HOME`
and verifies instrumentation works via fallback logic
- Modified all smoke tests (`SmokeTests/SmokeTestBase.cs`) to omit
`DD_DOTNET_TRACER_HOME` by default, providing comprehensive real-world
validation of the fallback behavior across multiple regression scenarios

## Other details
<!-- Fixes #{issue} -->

⚠️ Based on #7567, which was originally [generated by OpenAI
Codex](https://chatgpt.com/codex/tasks/task_b_68d59245fcec832180db94dd256130ba),
but I made substantial changes to clean up and refactor.


<!--  ⚠️ Note:

Where possible, please obtain 2 approvals prior to merging. Unless
CODEOWNERS specifies otherwise, for external teams it is typically best
to have one review from a team member, and one review from apm-dotnet.
Trivial changes do not require 2 reviews.

MergeQueue is NOT enabled in this repository. If you have write access
to the repo, the PR has 1-2 approvals (see above), and all of the
required checks have passed, you can use the Squash and Merge button to
merge the PR. If you don't have write access, or you need help, reach
out in the #apm-dotnet channel in Slack.
-->

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: lucaspimentel

tracer/src/Datadog.Trace.ClrProfiler.Managed.Loader/Startup.NetCore.cs

@@ -11,6 +11,7 @@
 using System.Collections.Generic;
 using System.IO;
 using System.Reflection;
+using System.Runtime.InteropServices;
 
 namespace Datadog.Trace.ClrProfiler.Managed.Loader
 {
@@ -62,6 +63,23 @@ internal static string ComputeTfmDirectory(string tracerHomeDirectory)
             return fullPath;
         }
 
+        internal static string GetProfilerPathEnvVarNameForArch()
+        {
+            return RuntimeInformation.ProcessArchitecture switch
+                   {
+                       Architecture.X64 => "CORECLR_PROFILER_PATH_64",
+                       Architecture.X86 => "CORECLR_PROFILER_PATH_32",
+                       Architecture.Arm64 => "CORECLR_PROFILER_PATH_ARM64",
+                       Architecture.Arm => "CORECLR_PROFILER_PATH_ARM",
+                       _ => throw new ArgumentOutOfRangeException(nameof(RuntimeInformation.ProcessArchitecture), RuntimeInformation.ProcessArchitecture, "Unsupported architecture")
+                   };
+        }
+
+        internal static string GetProfilerPathEnvVarNameFallback()
+        {
+            return "CORECLR_PROFILER_PATH";
+        }
+
         private static Assembly? AssemblyResolve_ManagedProfilerDependencies(object sender, ResolveEventArgs args)
         {
             return ResolveAssembly(args.Name);

tracer/src/Datadog.Trace.ClrProfiler.Managed.Loader/Startup.NetFramework.cs

@@ -23,6 +23,16 @@ internal static string ComputeTfmDirectory(string tracerHomeDirectory)
             return Path.Combine(Path.GetFullPath(tracerHomeDirectory), "net461");
         }
 
+        internal static string GetProfilerPathEnvVarNameForArch()
+        {
+            return Environment.Is64BitProcess ? "COR_PROFILER_PATH_64" : "COR_PROFILER_PATH_32";
+        }
+
+        internal static string GetProfilerPathEnvVarNameFallback()
+        {
+            return "COR_PROFILER_PATH";
+        }
+
         private static Assembly? AssemblyResolve_ManagedProfilerDependencies(object sender, ResolveEventArgs args)
         {
             try

tracer/src/Datadog.Trace.ClrProfiler.Managed.Loader/Startup.cs

@@ -6,6 +6,7 @@
 #nullable enable
 
 using System;
+using System.Collections.Generic;
 using System.IO;
 using System.Reflection;
 using System.Threading;
@@ -21,6 +22,21 @@ public partial class Startup
         private const string AzureAppServicesSiteExtensionKey = "DD_AZURE_APP_SERVICES"; // only set when using the AAS site extension
         private const string TracerHomePathKey = "DD_DOTNET_TRACER_HOME";
 
+        private static readonly HashSet<string> ArchitectureDirectories = new(StringComparer.OrdinalIgnoreCase)
+        {
+            "win-x64",
+            "win-x86",
+#if NETCOREAPP
+            "linux-x64",
+            "linux-arm64",
+            "linux-musl-x64",
+            "linux-musl-arm64",
+            "osx",
+            "osx-arm64",
+            "osx-x64"
+#endif
+        };
+
         private static int _startupCtorInitialized;
 
         /// <summary>
@@ -34,10 +50,9 @@ static Startup()
                 // Startup() was already called before in the same AppDomain, this can happen because the profiler rewrites
                 // methods before the jitting to inject the loader. This is done until the profiler detects that the loader
                 // has been initialized.
-                // The piece of code injected already includes an Interlocked condition but, because the static variable is emitted
-                // in a custom type inside the running assembly, others assemblies will also have a different type with a different static
-                // variable, so, we still can hit an scenario where multiple loaders initialize.
-                // With this we prevent this scenario.
+                // The piece of code injected already includes an Interlocked condition. However, because the static variable is emitted
+                // in a custom type inside the running assembly, other assemblies will also have a different type with a different static
+                // variable, so we still can hit a scenario where multiple loaders initialize. This prevents this scenario.
                 return;
             }
 
@@ -58,23 +73,36 @@ static Startup()
 #endif
 
                 var envVars = new EnvironmentVariableProvider(logErrors: true);
-                var tracerHomeDirectory = envVars.GetEnvironmentVariable(TracerHomePathKey);
+                var tracerHomeDirectory = GetTracerHomePath(envVars);
 
                 if (tracerHomeDirectory is null)
                 {
-                    StartupLogger.Log("{0} not set. Datadog SDK will be disabled.", TracerHomePathKey);
+                    // Provide a specific error message based on what was configured
+                    var explicitTracerHome = envVars.GetEnvironmentVariable(TracerHomePathKey);
+
+                    if (string.IsNullOrWhiteSpace(explicitTracerHome))
+                    {
+                        // DD_DOTNET_TRACER_HOME was not set and automatic detection from profiler path failed
+                        StartupLogger.Log("{0} is not set and the tracer home directory could not be determined automatically. Datadog SDK will be disabled. To resolve this issue, set environment variable {0}.", TracerHomePathKey);
+                    }
+                    else
+                    {
+                        // DD_DOTNET_TRACER_HOME was set but resulted in null (shouldn't happen, but just in case)
+                        StartupLogger.Log("{0} is set to '{1}' but could not be used. Datadog SDK will be disabled.", TracerHomePathKey, explicitTracerHome);
+                    }
+
                     return;
                 }
 
                 ManagedProfilerDirectory = ComputeTfmDirectory(tracerHomeDirectory);
 
                 if (!Directory.Exists(ManagedProfilerDirectory))
                 {
-                    StartupLogger.Log("Datadog.Trace.dll TFM directory not found at '{0}'. Datadog SDK will be disabled.", ManagedProfilerDirectory);
+                    StartupLogger.Log("Datadog.Trace.dll directory not found at '{0}'. Datadog SDK will be disabled.", ManagedProfilerDirectory);
                     return;
                 }
 
-                StartupLogger.Debug("Resolved Datadog.Trace.dll TFM directory to: {0}", ManagedProfilerDirectory);
+                StartupLogger.Debug("Resolved Datadog.Trace.dll directory to: {0}", ManagedProfilerDirectory);
 
                 try
                 {
@@ -125,13 +153,89 @@ static Startup()
                     // Nothing to do here.
                 }
 
-                // If the logger fails, throw the original exception. The profiler emits code to log it.
+                // If the logger fails, throw the original exception. The native library emits code to log it.
                 throw;
             }
         }
 
         internal static string? ManagedProfilerDirectory { get; }
 
+        internal static string? GetTracerHomePath<TEnvVars>(TEnvVars envVars)
+            where TEnvVars : IEnvironmentVariableProvider
+        {
+            // allow override with DD_DOTNET_TRACER_HOME
+            var tracerHomeDirectory = envVars.GetEnvironmentVariable(TracerHomePathKey);
+
+            if (!string.IsNullOrWhiteSpace(tracerHomeDirectory))
+            {
+                // Safe to use ! here because we just checked !string.IsNullOrWhiteSpace above
+                var trimmedPath = tracerHomeDirectory!.Trim();
+                StartupLogger.Debug("Using tracer home from {0}=\"{1}\"", TracerHomePathKey, trimmedPath);
+                return trimmedPath;
+            }
+
+            // try to compute the path from the architecture-specific "COR_PROFILER_PATH_*" or "CORECLR_PROFILER_PATH_*"
+            var archEnvVarName = GetProfilerPathEnvVarNameForArch();
+
+            if (ComputeTracerHomePathFromProfilerPath(envVars, archEnvVarName) is { } archTracerHomePath)
+            {
+                StartupLogger.Debug("Derived tracer home from {0}=\"{1}\"", archEnvVarName, archTracerHomePath);
+                return archTracerHomePath;
+            }
+
+            // try to compute the path from "COR_PROFILER_PATH" or "CORECLR_PROFILER_PATH" (no architecture)
+            var fallbackEnvVarName = GetProfilerPathEnvVarNameFallback();
+
+            if (ComputeTracerHomePathFromProfilerPath(envVars, fallbackEnvVarName) is { } fallbackTracerHomePath)
+            {
+                StartupLogger.Debug("Derived tracer home from {0}=\"{1}\"", fallbackEnvVarName, fallbackTracerHomePath);
+                return fallbackTracerHomePath;
+            }
+
+            return null;
+        }
+
+        internal static string? ComputeTracerHomePathFromProfilerPath<TEnvVars>(TEnvVars envVars, string envVarName)
+            where TEnvVars : IEnvironmentVariableProvider
+        {
+            var envVarValue = envVars.GetEnvironmentVariable(envVarName)?.Trim();
+
+            if (string.IsNullOrWhiteSpace(envVarValue))
+            {
+                return null;
+            }
+
+            try
+            {
+                var directory = Directory.GetParent(envVarValue);
+
+                if (directory is null)
+                {
+                    StartupLogger.Log("Unable to determine tracer home directory from {0}={1}", envVarName, envVarValue);
+                    return null;
+                }
+
+                // if the directory name is one of the well-known "os-arch" child directories (e.g. "win-x64"), go one level higher
+                if (ArchitectureDirectories.Contains(directory.Name))
+                {
+                    directory = directory.Parent;
+
+                    if (directory is null)
+                    {
+                        StartupLogger.Log("Unable to determine tracer home directory from {0}={1}", envVarName, envVarValue);
+                        return null;
+                    }
+                }
+
+                return directory.FullName;
+            }
+            catch (Exception ex)
+            {
+                StartupLogger.Log(ex, "Error resolving tracer home directory from {0}={1}", envVarName, envVarValue);
+                return null;
+            }
+        }
+
         private static void TryInvokeManagedMethod(string typeName, string methodName, string? loaderHelperTypeName = null)
         {
             try

tracer/test/Datadog.Trace.ClrProfiler.IntegrationTests/InstrumentationTests.cs

@@ -251,6 +251,25 @@ public async Task WhenUsingPathWithDotsInInTracerHome_InstrumentsApp()
             agent.Telemetry.Should().NotBeEmpty();
         }
 
+        [SkippableFact]
+        [Trait("RunOnWindows", "True")]
+        public async Task WhenOmittingTracerHome_InstrumentsApp()
+        {
+            // Verify that DD_DOTNET_TRACER_HOME is not set to ensure we're actually testing the fallback behavior
+            EnvironmentHelper.CustomEnvironmentVariables.Should().NotContainKey("DD_DOTNET_TRACER_HOME");
+            Environment.GetEnvironmentVariable("DD_DOTNET_TRACER_HOME").Should().BeNullOrEmpty();
+
+            SetLogDirectory();
+
+            // DD_DOTNET_TRACER_HOME is not set, so the tracer should derive it from the profiler path
+            Output.WriteLine("DD_DOTNET_TRACER_HOME not set, relying on profiler path environment variables");
+
+            using var agent = EnvironmentHelper.GetMockAgent(useTelemetry: true);
+            using var processResult = await RunSampleAndWaitForExit(agent, "traces 1");
+            agent.Spans.Should().NotBeEmpty();
+            agent.Telemetry.Should().NotBeEmpty();
+        }
+
         [SkippableTheory]
         [CombinatorialData]
         [Trait("RunOnWindows", "True")]
@@ -426,7 +445,7 @@ public async Task OnEolFrameworkInSsi_WhenForwarderPathExists_CallsForwarderWith
 
             var pointsJson = """
                              [{
-                               "name": "library_entrypoint.abort", 
+                               "name": "library_entrypoint.abort",
                                "tags": ["reason:eol_runtime"]
                              },{
                                "name": "library_entrypoint.abort.runtime"
@@ -459,7 +478,7 @@ public async Task OnEolFrameworkInSsi_WhenOverriden_CallsForwarderWithExpectedTe
 
             var pointsJson = """
                              [{
-                               "name": "library_entrypoint.complete", 
+                               "name": "library_entrypoint.complete",
                                "tags": ["injection_forced:true"]
                              }]
                              """;
@@ -498,7 +517,7 @@ public async Task OnPreviewFrameworkInSsi_CallsForwarderWithExpectedTelemetry()
 
             var pointsJson = """
                              [{
-                               "name": "library_entrypoint.complete", 
+                               "name": "library_entrypoint.complete",
                                "tags": ["injection_forced:true"]
                              }]
                              """;
@@ -529,7 +548,7 @@ public async Task OnPreviewFrameworkInSsi_WhenForwarderPathExists_CallsForwarder
 
             var pointsJson = """
                              [{
-                               "name": "library_entrypoint.abort", 
+                               "name": "library_entrypoint.abort",
                                "tags": ["reason:incompatible_runtime"]
                              },{
                                "name": "library_entrypoint.abort.runtime"
@@ -588,7 +607,7 @@ public async Task OnSupportedFrameworkInSsi_CallsForwarderWithExpectedTelemetry(
 
             var pointsJson = """
                              [{
-                               "name": "library_entrypoint.complete", 
+                               "name": "library_entrypoint.complete",
                                "tags": ["injection_forced:false"]
                              }]
                              """;

tracer/test/Datadog.Trace.ClrProfiler.IntegrationTests/SmokeTests/SmokeTestBase.cs

@@ -29,7 +29,11 @@ protected SmokeTestBase(
                 this.GetType(),
                 output,
                 samplesDirectory: "test/test-applications/regression",
-                prependSamplesToAppName: false);
+                prependSamplesToAppName: false)
+            {
+                // Don't set DD_DOTNET_TRACER_HOME in smoke tests to verify the fallback logic works
+                SetTracerHomeEnvironmentVariable = false
+            };
         }
 
         protected ITestOutputHelper Output { get; }

tracer/test/Datadog.Trace.TestHelpers/EnvironmentHelper.cs

@@ -70,6 +70,8 @@ public EnvironmentHelper(
 
         public bool DebugModeEnabled { get; set; }
 
+        public bool SetTracerHomeEnvironmentVariable { get; set; } = true;
+
         public Dictionary<string, string> CustomEnvironmentVariables { get; set; } = new Dictionary<string, string>();
 
         public string SampleName { get; }
@@ -196,7 +198,11 @@ public void SetEnvironmentVariables(
             bool ignoreProfilerProcessesVar = false)
         {
             string profilerEnabled = AutomaticInstrumentationEnabled ? "1" : "0";
-            environmentVariables["DD_DOTNET_TRACER_HOME"] = MonitoringHome;
+
+            if (SetTracerHomeEnvironmentVariable)
+            {
+                environmentVariables["DD_DOTNET_TRACER_HOME"] = MonitoringHome;
+            }
 
             // see https://github.com/DataDog/dd-trace-dotnet/pull/3579
             environmentVariables["DD_INTERNAL_WORKAROUND_77973_ENABLED"] = "1";