Datadog.Trace 3.4.1

Prefix Reserved
dotnet add package Datadog.Trace --version 3.4.1                
NuGet\Install-Package Datadog.Trace -Version 3.4.1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Datadog.Trace" Version="3.4.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Datadog.Trace --version 3.4.1                
#r "nuget: Datadog.Trace, 3.4.1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Datadog.Trace as a Cake Addin
#addin nuget:?package=Datadog.Trace&version=3.4.1

// Install Datadog.Trace as a Cake Tool
#tool nuget:?package=Datadog.Trace&version=3.4.1                

Datadog.Trace NuGet package

This package contains the Datadog .NET APM tracer for configuring custom instrumentation.

⚠ Starting with version 3.0.0, this package requires that you also configure automatic instrumentation. Using this package without automatic instrumentation is no longer supported

If you are only using automatic instrumentation, you do not need this package. Please read our documentation for details on how to install the tracer for automatic instrumentation.

If you are using automatic instrumentation and would like to interact with APM only through C# attributes, see the Datadog.Trace.Annotations NuGet package.

Please note that Datadog does not support tracing (manual or automatic) in partial-trust environments.

Getting Started

  1. Configure the Datadog agent for APM as described in our documentation.
  2. Configure automatic instrumentation as described in our documentation.
  3. Configure custom instrumentation, as shown below
  4. View your live data on Datadog.

Configuring Datadog in code

There are multiple ways to configure your application: using environment variables, a web.config file, or a datadog.json file, as described in our documentation. This NuGet package also allows you to configure settings in code.

To override configuration settings, create an instance of TracerSettings, and pass it to the static Tracer.Configure() method:

using Datadog.Trace;

// Create a settings object using the existing
// environment variables and config sources
var settings = TracerSettings.FromDefaultSources();

// Override a value
settings.GlobalTags.Add("SomeKey", "SomeValue");

// Replace the tracer configuration
Tracer.Configure(settings);

Calling Tracer.Configure() will replace the settings for all subsequent traces, both for custom instrumentation and for automatic instrumentation.

⚠️ Replacing the configuration should be done once, as early as possible in your application.

Create custom traces

To create and activate a custom span, use Tracer.Instance.StartActive(). If a trace is already active (when created by automatic instrumentation, for example), the span will be part of the current trace. If there is no current trace, a new one will be started.

⚠️ Ensure you dispose of the scope returned from StartActive. Disposing the scope will close the span, and ensure the trace is flushed to Datadog once all its spans are closed.

using Datadog.Trace;

// Start a new span
using (var scope = Tracer.Instance.StartActive("custom-operation"))
{
    // Do something
}

Release Notes

You can view the notes for the latest release on GitHub.

Upgrading from 2.x to 3.0

The .NET tracer v3.0.0 includes breaking changes that you must be aware of before upgrading your applications. The most important high-level changes are listed below, and described in more detail later in this document

  • Breaking changes
    • Custom-only tracing (using the Datadog.Trace NuGet package), without any automatic tracing, is no longer supported. Custom instrumentation with the Datadog.Trace NuGet where you have also configured automatic-instrumentation is still supported as it was in v2.x.x.
    • The public API surface has changed in the Datadog.Trace NuGet package. A number of previously obsolete APIs have been removed, and some other APIs have been marked obsolete. Most changes are related to how you create TracerSettings and Tracer instances.
    • Changes to default settings. The default values of some settings have changed, and others have been removed. See below for more details.
    • Changes in behavior. The semantic requirements and meaning of some settings have changed, as have some of the tags added to traces. See below for more details.
    • The 32-bit MSI installer will no longer be available. The 64-bit MSI installer already includes support for tracing 32-bit processes, so you should use this installer instead.
    • The client library will still be injected when DD_TRACE_ENABLED=0. In v2.x.x, setting DD_TRACE_ENABLED=0 would prevent the client library from being injected into the application completely. In v3.0.0+, the client library will still be injected, but tracing will be disabled.
    • Referencing the Datadog.Trace.AspNet module is no longer supported. In v1.x.x and 2.x.x ASP.NET support allowed adding a reference to the Datadog.Trace.AspNet module in your web.config. This is no longer supported in v3.x.x.
  • Deprecation notices
    • .NET Core 2.1 is marked EOL in v3.0.0+ of the tracer. That means versions 2.0, 2.1, 2.2 and 3.0 of .NET Core are now EOL. These versions may still work with v3.0.0+, but they will no longer receive significant testing and you will receive limited support for issues arising with EOL versions.
    • Datadog.Trace.OpenTracing is now obsolete. OpenTracing is considered deprecated, and so Datadog.Trace.OpenTracing is considered deprecated. See the following details on future deprecation.
    • macOS 11 is no longer supported for CI Visibility in v3.0.0+. Only macOS 12 and above are supported.
  • Major version policy and future deprecation
    • Announcing a major version roadmap. We intend to make yearly major releases, starting from v3.0.0 in 2024, and v4.0.0 in 2025. We clearly will aim for minimal breaking changes, with the primary focus being on maintaining support for new versions of .NET and removal of EOL frameworks and operating systems.
    • Planned removal of support for .NET Core 2.x and .NET Core 3.0 in version v4.0.0+. We intend to completely remove support for .NET Core 2.x and .NET Core 3.0 in v4.0.0. .NET Framework 4.6.1+ will continue to be supported.
    • Planned removal of support for some linux distributions. In version v4.0.0, we intend to drop support for CentOS 7, RHEL 7, and CentOS Stream 8.
    • Planned remove of support for App Analytics. In version v4.0.0, we intend to drop support for App Analytics and associated settings.

For a full list of changes and a guide to migrating your application, please see the migration guide.

Get in touch

If you have questions, feedback, or feature requests, reach our support.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 is compatible. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (11)

Showing the top 5 NuGet packages that depend on Datadog.Trace:

Package Downloads
Datadog.Trace.Bundle

Auto-instrumentation assets for Datadog APM

Datadog.Trace.OpenTracing

Provides OpenTracing support for Datadog APM

Datadog.Monitoring.Distribution

Auto-instrumentation assets for Datadog APM

Lucca.Logs.Shared

Lucca.Logs

Datadog.Trace.BenchmarkDotNet

BenchmarkDotNet exporter for Datadog CI Visibility

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Datadog.Trace:

Repository Stars
DataDog/dd-trace-dotnet
.NET Client Library for Datadog APM
Version Downloads Last updated
3.4.1 15,226 10/28/2024
3.4.0 12,658 10/24/2024
3.3.1 210,983 9/18/2024
3.3.0 20,020 9/16/2024
3.2.0 106,981 9/2/2024
3.1.0-prerelease 1,263 8/14/2024
3.0.0-prerelease 755 7/29/2024
2.60.0 2,638 10/24/2024
2.59.0 53,537 9/16/2024
2.58.0 42,757 9/2/2024
2.57.0 255,139 8/14/2024
2.56.0 185,385 7/25/2024
2.55.0 77,095 7/18/2024
2.54.0 143,188 7/9/2024
2.53.2 1,129,039 6/19/2024
2.53.1 59,203 6/17/2024
2.53.0 146,130 6/11/2024
2.52.0 440,920 5/23/2024
2.51.0 450,473 5/6/2024
2.50.0 325,789 4/17/2024
2.49.0 652,615 3/18/2024
2.48.0 993,662 2/29/2024
2.47.0 621,121 2/14/2024
2.46.0 620,261 1/24/2024
2.45.0 290,120 1/10/2024
2.44.0 459,792 12/19/2023
2.43.0 350,875 12/5/2023
2.42.0 236,623 11/21/2023
2.41.0 825,318 11/6/2023
2.40.0 471,614 10/16/2023
2.39.0 82,672 10/11/2023
2.38.0 359,518 9/20/2023
2.37.0 570,738 8/31/2023
2.36.0 353,091 8/23/2023
2.35.0 362,916 7/31/2023
2.34.0 37,942 7/25/2023
2.33.0 298,485 7/4/2023
2.32.0 332,144 6/20/2023
2.31.0 570,349 5/31/2023
2.30.0 726,186 5/5/2023
2.29.0 364,585 4/17/2023
2.28.0 104,207 4/12/2023
2.27.0 527,907 3/24/2023
2.26.0 344,711 3/9/2023
2.24.1 710,295 2/27/2023
2.24.0 51,610 2/24/2023
2.23.0 580,100 2/8/2023
2.22.0 562,749 1/24/2023
2.21.0 456,554 12/20/2022
2.20.0 480,268 12/2/2022
2.19.0 447,768 11/10/2022
2.18.0 829,706 10/25/2022
2.17.0 986,886 10/11/2022
2.16.0 72,556 10/7/2022
2.15.0 405,082 9/26/2022
2.14.0 537,794 8/23/2022
2.13.0 280,219 8/3/2022
2.12.0 414,577 7/13/2022
2.11.0 506,004 6/22/2022
2.10.0 358,446 6/9/2022
2.9.0 781,733 5/13/2022
2.8.0 340,781 5/5/2022
2.7.0 316,669 4/22/2022
2.6.0 561,578 4/7/2022
2.5.1 266,841 3/25/2022
2.4.4 849,133 3/16/2022
2.4.3 474,537 3/2/2022
2.4.2 103,607 2/25/2022
2.4.1 5,188 2/24/2022
2.4.0 17,199 2/22/2022
2.3.0 455,226 2/10/2022
2.2.0 203,194 2/2/2022
2.1.1 379,593 1/19/2022
2.1.0 471,018 1/7/2022
2.0.1 438,340 12/20/2021
2.0.0-prerelease 13,834 12/10/2021
1.31.2 366,821 2/22/2022 1.31.2 is deprecated because it is no longer maintained.
1.31.1 39,086 12/21/2021 1.31.1 is deprecated because it is no longer maintained.
1.31.0 300,446 12/2/2021 1.31.0 is deprecated because it is no longer maintained.
1.30.1 131,702 11/24/2021 1.30.1 is deprecated because it is no longer maintained.
1.30.0 421,184 11/16/2021 1.30.0 is deprecated because it is no longer maintained.
1.29.1-prerelease 65,946 10/28/2021 1.29.1-prerelease is deprecated because it is no longer maintained.
1.29.0 906,042 10/15/2021 1.29.0 is deprecated because it is no longer maintained.
1.28.8 114,408 9/29/2021 1.28.8 is deprecated because it is no longer maintained.
1.28.7 168,714 9/14/2021 1.28.7 is deprecated because it is no longer maintained.
1.28.6 70,981 9/8/2021 1.28.6 is deprecated because it is no longer maintained.
1.28.5-prerelease 855 8/30/2021 1.28.5-prerelease is deprecated because it is no longer maintained.
1.28.4 176,368 8/30/2021 1.28.4 is deprecated because it is no longer maintained.
1.28.3-prerelease 427 8/17/2021 1.28.3-prerelease is deprecated because it is no longer maintained.
1.28.2 226,605 8/4/2021 1.28.2 is deprecated because it is no longer maintained.
1.28.1-prerelease 536 7/14/2021 1.28.1-prerelease is deprecated because it is no longer maintained.
1.28.0 245,035 7/12/2021 1.28.0 is deprecated because it is no longer maintained.
1.27.1 807,447 6/16/2021 1.27.1 is deprecated because it is no longer maintained.
1.27.0 170,879 6/2/2021 1.27.0 is deprecated because it is no longer maintained.
1.26.3 439,398 5/11/2021 1.26.3 is deprecated because it is no longer maintained.
1.25.2-prerelease 2,548 4/2/2021 1.25.2-prerelease is deprecated because it is no longer maintained.
1.25.0 435,190 3/22/2021 1.25.0 is deprecated because it is no longer maintained.
1.24.0 364,702 2/23/2021 1.24.0 is deprecated because it is no longer maintained.
1.23.0 295,841 2/3/2021 1.23.0 is deprecated because it is no longer maintained.
1.22.2-prerelease 440 2/1/2021 1.22.2-prerelease is deprecated because it is no longer maintained.
1.22.1-prerelease 461 1/28/2021 1.22.1-prerelease is deprecated because it is no longer maintained.
1.22.0 207,681 1/14/2021 1.22.0 is deprecated because it is no longer maintained.
1.21.2-prerelease 3,046 12/21/2020 1.21.2-prerelease is deprecated because it is no longer maintained.
1.21.1 68,631 12/17/2020 1.21.1 is deprecated because it is no longer maintained.
1.21.0 114,949 11/25/2020 1.21.0 is deprecated because it is no longer maintained.
1.20.0 319,855 11/3/2020 1.20.0 is deprecated because it is no longer maintained.
1.19.6-prerelease 1,561 10/15/2020 1.19.6-prerelease is deprecated because it is no longer maintained.
1.19.5 369,761 10/7/2020 1.19.5 is deprecated because it is no longer maintained.
1.19.4 106,150 9/29/2020 1.19.4 is deprecated because it is no longer maintained.
1.19.3 177,474 9/17/2020 1.19.3 is deprecated because it is no longer maintained.
1.19.2 273,544 8/31/2020 1.19.2 is deprecated because it is no longer maintained.
1.19.1 664,812 8/10/2020 1.19.1 is deprecated because it is no longer maintained.
1.19.0 69,646 8/7/2020 1.19.0 is deprecated because it is no longer maintained.
1.18.3 201,355 7/17/2020 1.18.3 is deprecated because it is no longer maintained.
1.18.2 55,004 7/9/2020 1.18.2 is deprecated because it is no longer maintained.
1.18.1-prerelease 570 7/6/2020 1.18.1-prerelease is deprecated because it is no longer maintained.
1.18.0 35,239 6/25/2020 1.18.0 is deprecated because it is no longer maintained.
1.17.1-prerelease 623 6/23/2020 1.17.1-prerelease is deprecated because it is no longer maintained.
1.17.0 421,043 5/15/2020 1.17.0 is deprecated because it is no longer maintained.
1.16.3-prerelease 584 5/13/2020 1.16.3-prerelease is deprecated because it is no longer maintained.
1.16.2 56,083 5/5/2020 1.16.2 is deprecated because it is no longer maintained.
1.16.1 233,277 4/20/2020 1.16.1 is deprecated because it is no longer maintained.
1.16.0 41,571 4/2/2020 1.16.0 is deprecated because it is no longer maintained.
1.15.1-prerelease 694 3/30/2020 1.15.1-prerelease is deprecated because it is no longer maintained.
1.15.0 256,941 3/23/2020 1.15.0 is deprecated because it is no longer maintained.
1.14.2 18,890 3/13/2020 1.14.2 is deprecated because it is no longer maintained.
1.14.1-prerelease 522 3/12/2020 1.14.1-prerelease is deprecated because it is no longer maintained.
1.14.0 7,668 3/9/2020 1.14.0 is deprecated because it is no longer maintained.
1.13.4-prerelease 1,522 3/4/2020 1.13.4-prerelease is deprecated because it is no longer maintained.
1.13.3-prerelease 589 2/24/2020 1.13.3-prerelease is deprecated because it is no longer maintained.
1.13.2 118,235 2/21/2020 1.13.2 is deprecated because it is no longer maintained.
1.13.0 360,252 2/14/2020 1.13.0 is deprecated because it is no longer maintained.
1.12.0 100,764 2/5/2020 1.12.0 is deprecated because it is no longer maintained.
1.11.1-prerelease 1,400 1/13/2020 1.11.1-prerelease is deprecated because it is no longer maintained.
1.11.0 128,078 12/11/2019 1.11.0 is deprecated because it is no longer maintained.
1.10.3-prerelease 662 12/11/2019 1.10.3-prerelease is deprecated because it is no longer maintained.
1.10.2-prerelease 577 12/10/2019 1.10.2-prerelease is deprecated because it is no longer maintained.
1.10.1-prerelease 712 12/10/2019 1.10.1-prerelease is deprecated because it is no longer maintained.
1.10.0 76,490 11/27/2019 1.10.0 is deprecated because it is no longer maintained.
1.9.1-prerelease 1,058 11/14/2019 1.9.1-prerelease is deprecated because it is no longer maintained.
1.9.0 198,911 11/7/2019 1.9.0 is deprecated because it is no longer maintained.
1.8.0 200,751 10/17/2019 1.8.0 is deprecated because it is no longer maintained.
1.7.0 95,380 9/10/2019 1.7.0 is deprecated because it is no longer maintained.
1.6.2 81,919 8/20/2019 1.6.2 is deprecated because it is no longer maintained.
1.6.1 21,847 8/14/2019 1.6.1 is deprecated because it is no longer maintained.
1.6.0 81,689 7/20/2019 1.6.0 is deprecated because it is no longer maintained.
1.4.1 358,210 6/26/2019 1.4.1 is deprecated because it is no longer maintained.
1.4.0 67,086 6/20/2019 1.4.0 is deprecated because it is no longer maintained.
1.2.0 70,684 5/20/2019 1.2.0 is deprecated because it is no longer maintained.
1.1.0 86,592 4/17/2019 1.1.0 is deprecated because it is no longer maintained.
1.0.0 78,598 4/5/2019 1.0.0 is deprecated because it is no longer maintained.
0.8.2-beta 8,659 3/28/2019 0.8.2-beta is deprecated because it is no longer maintained.
0.8.1-beta 2,299 3/21/2019 0.8.1-beta is deprecated because it is no longer maintained.
0.8.0-beta 1,974 3/11/2019 0.8.0-beta is deprecated because it is no longer maintained.
0.7.1-beta 51,441 1/31/2019 0.7.1-beta is deprecated because it is no longer maintained.
0.7.0-beta 28,943 1/17/2019 0.7.0-beta is deprecated because it is no longer maintained.
0.6.0-beta 73,942 12/21/2018 0.6.0-beta is deprecated because it is no longer maintained.
0.5.2-beta 29,417 12/4/2018 0.5.2-beta is deprecated because it is no longer maintained.
0.5.1-beta 11,403 11/20/2018 0.5.1-beta is deprecated because it is no longer maintained.
0.5.0-beta 612,552 10/30/2018 0.5.0-beta is deprecated because it is no longer maintained.
0.4.1-beta 2,888 10/23/2018 0.4.1-beta is deprecated because it is no longer maintained.
0.4.0-beta 1,001 10/12/2018 0.4.0-beta is deprecated because it is no longer maintained.
0.3.2-beta 2,049 9/26/2018 0.3.2-beta is deprecated because it is no longer maintained.
0.3.1-beta 1,105 9/21/2018 0.3.1-beta is deprecated because it is no longer maintained.
0.3.0-beta 940 9/13/2018 0.3.0-beta is deprecated because it is no longer maintained.
0.2.4-alpha 930 9/13/2018 0.2.4-alpha is deprecated because it is no longer maintained.

See release notes at https://github.com/DataDog/dd-trace-dotnet/releases.
     Please note that Datadog does not support tracing (manual or automatic) in partial-trust environments.