Datadog.Tracer从2.x升级到3.3.1后无法创建自定义Span求助

核心原因 #

Datadog.Trace 3.x版本移除了2.x的自动默认Tracer初始化逻辑，必须显式初始化Tracer或确保自动Instrumentation正确加载，否则Tracer.Instance会返回NullTracer，导致生成NullSpan。

具体解决方案 #

1. 手动初始化Tracer（适用于不需要全量自动Instrumentation的场景）

在应用启动入口处添加初始化代码，确保在创建Span前完成配置：

using Datadog.Trace;
using Datadog.Trace.Configuration;

// 应用启动时执行一次
var settings = new TracerSettings
{
    ServiceName = "你的服务名称",
    Environment = "你的环境标识（如dev/prod）",
    AgentUri = new Uri("http://localhost:8126") // 对应本地或部署的Datadog Agent地址
};
Tracer.Configure(settings);

// 之后正常创建自定义Span
using (var scope = Tracer.Instance.StartActive("custom-operation"))
{
    // 业务逻辑代码
}

2. 正确配置自动Instrumentation（适用于需要全链路自动埋点的场景）

自动Instrumentation依赖CLR Profiler，必须在进程启动前设置以下环境变量，运行时动态设置无效：

• CORECLR_ENABLE_PROFILING=1
• CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}（固定GUID，对应Datadog Profiler）
• CORECLR_PROFILER_PATH：指向对应平台的Profiler原生库路径（Linux为Datadog.Trace.ClrProfiler.Native.so，Windows为Datadog.Trace.ClrProfiler.Native.dll）
• DD_SERVICE=你的服务名称
• DD_ENV=你的环境标识
• DD_VERSION=你的服务版本
• DD_TRACE_ENABLED=true

同时确保已安装Datadog.Trace和Datadog.Trace.Bundle NuGet包（3.x版本推荐用Bundle包简化依赖管理）。

3. 验证Tracer初始化状态

在创建Span前添加调试代码，确认Tracer是否有效：

var tracer = Tracer.Instance;
Console.WriteLine($"当前Tracer类型：{tracer.GetType().FullName}");
// 输出应为Datadog.Trace.Tracer而非Datadog.Trace.Stubs.NullTracer

4. 常见排查点

• 检查环境变量是否在进程启动时就已配置（如Docker的ENV、启动脚本），代码内动态设置不生效。
• 确认Datadog Agent正常运行，且与应用网络连通。
• 查看应用日志，排查是否有Profiler加载失败、Agent连接失败等错误信息。

内容的提问来源于stack exchange，提问作者Hardik Parmar