Datadog.Trace 3.3.1

Prefix Reserved
dotnet add package Datadog.Trace --version 3.3.1                
NuGet\Install-Package Datadog.Trace -Version 3.3.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.3.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Datadog.Trace --version 3.3.1                
#r "nuget: Datadog.Trace, 3.3.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.3.1

// Install Datadog.Trace as a Cake Tool
#tool nuget:?package=Datadog.Trace&version=3.3.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.3.1 52,555 9/18/2024
3.3.0 12,051 9/16/2024
3.2.0 68,795 9/2/2024
3.1.0-prerelease 1,239 8/14/2024
3.0.0-prerelease 749 7/29/2024
2.59.0 12,967 9/16/2024
2.58.0 23,976 9/2/2024
2.57.0 184,119 8/14/2024
2.56.0 141,000 7/25/2024
2.55.0 66,907 7/18/2024
2.54.0 124,208 7/9/2024
2.53.2 847,807 6/19/2024
2.53.1 47,303 6/17/2024
2.53.0 125,439 6/11/2024
2.52.0 352,415 5/23/2024
2.51.0 382,914 5/6/2024
2.50.0 288,415 4/17/2024
2.49.0 584,437 3/18/2024
2.48.0 940,603 2/29/2024
2.47.0 564,691 2/14/2024
2.46.0 580,213 1/24/2024
2.45.0 278,044 1/10/2024
2.44.0 420,696 12/19/2023
2.43.0 323,837 12/5/2023
2.42.0 222,034 11/21/2023
2.41.0 773,947 11/6/2023
2.40.0 440,830 10/16/2023
2.39.0 76,908 10/11/2023
2.38.0 342,499 9/20/2023
2.37.0 537,843 8/31/2023
2.36.0 340,357 8/23/2023
2.35.0 354,004 7/31/2023
2.34.0 37,325 7/25/2023
2.33.0 294,197 7/4/2023
2.32.0 320,615 6/20/2023
2.31.0 551,315 5/31/2023
2.30.0 704,512 5/5/2023
2.29.0 357,220 4/17/2023
2.28.0 101,940 4/12/2023
2.27.0 506,588 3/24/2023
2.26.0 335,385 3/9/2023
2.24.1 668,229 2/27/2023
2.24.0 51,505 2/24/2023
2.23.0 570,943 2/8/2023
2.22.0 552,400 1/24/2023
2.21.0 449,155 12/20/2022
2.20.0 474,118 12/2/2022
2.19.0 438,417 11/10/2022
2.18.0 816,818 10/25/2022
2.17.0 975,277 10/11/2022
2.16.0 70,416 10/7/2022
2.15.0 398,966 9/26/2022
2.14.0 530,662 8/23/2022
2.13.0 277,928 8/3/2022
2.12.0 406,341 7/13/2022
2.11.0 495,456 6/22/2022
2.10.0 353,837 6/9/2022
2.9.0 764,590 5/13/2022
2.8.0 335,169 5/5/2022
2.7.0 308,399 4/22/2022
2.6.0 553,799 4/7/2022
2.5.1 265,786 3/25/2022
2.4.4 825,884 3/16/2022
2.4.3 470,721 3/2/2022
2.4.2 101,632 2/25/2022
2.4.1 5,179 2/24/2022
2.4.0 17,019 2/22/2022
2.3.0 448,423 2/10/2022
2.2.0 202,231 2/2/2022
2.1.1 376,748 1/19/2022
2.1.0 454,451 1/7/2022
2.0.1 431,651 12/20/2021
2.0.0-prerelease 13,600 12/10/2021
1.31.2 341,940 2/22/2022 1.31.2 is deprecated because it is no longer maintained.
1.31.1 39,033 12/21/2021 1.31.1 is deprecated because it is no longer maintained.
1.31.0 293,217 12/2/2021 1.31.0 is deprecated because it is no longer maintained.
1.30.1 131,637 11/24/2021 1.30.1 is deprecated because it is no longer maintained.
1.30.0 413,809 11/16/2021 1.30.0 is deprecated because it is no longer maintained.
1.29.1-prerelease 65,842 10/28/2021 1.29.1-prerelease is deprecated because it is no longer maintained.
1.29.0 880,556 10/15/2021 1.29.0 is deprecated because it is no longer maintained.
1.28.8 114,243 9/29/2021 1.28.8 is deprecated because it is no longer maintained.
1.28.7 167,335 9/14/2021 1.28.7 is deprecated because it is no longer maintained.
1.28.6 70,819 9/8/2021 1.28.6 is deprecated because it is no longer maintained.
1.28.5-prerelease 851 8/30/2021 1.28.5-prerelease is deprecated because it is no longer maintained.
1.28.4 173,641 8/30/2021 1.28.4 is deprecated because it is no longer maintained.
1.28.3-prerelease 424 8/17/2021 1.28.3-prerelease is deprecated because it is no longer maintained.
1.28.2 224,962 8/4/2021 1.28.2 is deprecated because it is no longer maintained.
1.28.1-prerelease 532 7/14/2021 1.28.1-prerelease is deprecated because it is no longer maintained.
1.28.0 244,216 7/12/2021 1.28.0 is deprecated because it is no longer maintained.
1.27.1 803,291 6/16/2021 1.27.1 is deprecated because it is no longer maintained.
1.27.0 165,938 6/2/2021 1.27.0 is deprecated because it is no longer maintained.
1.26.3 437,321 5/11/2021 1.26.3 is deprecated because it is no longer maintained.
1.25.2-prerelease 2,544 4/2/2021 1.25.2-prerelease is deprecated because it is no longer maintained.
1.25.0 430,202 3/22/2021 1.25.0 is deprecated because it is no longer maintained.
1.24.0 363,850 2/23/2021 1.24.0 is deprecated because it is no longer maintained.
1.23.0 294,931 2/3/2021 1.23.0 is deprecated because it is no longer maintained.
1.22.2-prerelease 435 2/1/2021 1.22.2-prerelease is deprecated because it is no longer maintained.
1.22.1-prerelease 457 1/28/2021 1.22.1-prerelease is deprecated because it is no longer maintained.
1.22.0 204,771 1/14/2021 1.22.0 is deprecated because it is no longer maintained.
1.21.2-prerelease 3,042 12/21/2020 1.21.2-prerelease is deprecated because it is no longer maintained.
1.21.1 68,342 12/17/2020 1.21.1 is deprecated because it is no longer maintained.
1.21.0 114,698 11/25/2020 1.21.0 is deprecated because it is no longer maintained.
1.20.0 313,644 11/3/2020 1.20.0 is deprecated because it is no longer maintained.
1.19.6-prerelease 1,556 10/15/2020 1.19.6-prerelease is deprecated because it is no longer maintained.
1.19.5 365,980 10/7/2020 1.19.5 is deprecated because it is no longer maintained.
1.19.4 105,949 9/29/2020 1.19.4 is deprecated because it is no longer maintained.
1.19.3 175,325 9/17/2020 1.19.3 is deprecated because it is no longer maintained.
1.19.2 273,007 8/31/2020 1.19.2 is deprecated because it is no longer maintained.
1.19.1 645,428 8/10/2020 1.19.1 is deprecated because it is no longer maintained.
1.19.0 69,621 8/7/2020 1.19.0 is deprecated because it is no longer maintained.
1.18.3 198,742 7/17/2020 1.18.3 is deprecated because it is no longer maintained.
1.18.2 54,289 7/9/2020 1.18.2 is deprecated because it is no longer maintained.
1.18.1-prerelease 565 7/6/2020 1.18.1-prerelease is deprecated because it is no longer maintained.
1.18.0 35,016 6/25/2020 1.18.0 is deprecated because it is no longer maintained.
1.17.1-prerelease 617 6/23/2020 1.17.1-prerelease is deprecated because it is no longer maintained.
1.17.0 420,237 5/15/2020 1.17.0 is deprecated because it is no longer maintained.
1.16.3-prerelease 579 5/13/2020 1.16.3-prerelease is deprecated because it is no longer maintained.
1.16.2 56,077 5/5/2020 1.16.2 is deprecated because it is no longer maintained.
1.16.1 232,080 4/20/2020 1.16.1 is deprecated because it is no longer maintained.
1.16.0 41,292 4/2/2020 1.16.0 is deprecated because it is no longer maintained.
1.15.1-prerelease 690 3/30/2020 1.15.1-prerelease is deprecated because it is no longer maintained.
1.15.0 255,127 3/23/2020 1.15.0 is deprecated because it is no longer maintained.
1.14.2 18,696 3/13/2020 1.14.2 is deprecated because it is no longer maintained.
1.14.1-prerelease 516 3/12/2020 1.14.1-prerelease is deprecated because it is no longer maintained.
1.14.0 7,661 3/9/2020 1.14.0 is deprecated because it is no longer maintained.
1.13.4-prerelease 1,518 3/4/2020 1.13.4-prerelease is deprecated because it is no longer maintained.
1.13.3-prerelease 585 2/24/2020 1.13.3-prerelease is deprecated because it is no longer maintained.
1.13.2 118,162 2/21/2020 1.13.2 is deprecated because it is no longer maintained.
1.13.0 357,179 2/14/2020 1.13.0 is deprecated because it is no longer maintained.
1.12.0 100,110 2/5/2020 1.12.0 is deprecated because it is no longer maintained.
1.11.1-prerelease 1,396 1/13/2020 1.11.1-prerelease is deprecated because it is no longer maintained.
1.11.0 127,105 12/11/2019 1.11.0 is deprecated because it is no longer maintained.
1.10.3-prerelease 657 12/11/2019 1.10.3-prerelease is deprecated because it is no longer maintained.
1.10.2-prerelease 570 12/10/2019 1.10.2-prerelease is deprecated because it is no longer maintained.
1.10.1-prerelease 708 12/10/2019 1.10.1-prerelease is deprecated because it is no longer maintained.
1.10.0 76,094 11/27/2019 1.10.0 is deprecated because it is no longer maintained.
1.9.1-prerelease 1,047 11/14/2019 1.9.1-prerelease is deprecated because it is no longer maintained.
1.9.0 194,694 11/7/2019 1.9.0 is deprecated because it is no longer maintained.
1.8.0 199,395 10/17/2019 1.8.0 is deprecated because it is no longer maintained.
1.7.0 95,339 9/10/2019 1.7.0 is deprecated because it is no longer maintained.
1.6.2 79,957 8/20/2019 1.6.2 is deprecated because it is no longer maintained.
1.6.1 21,842 8/14/2019 1.6.1 is deprecated because it is no longer maintained.
1.6.0 81,664 7/20/2019 1.6.0 is deprecated because it is no longer maintained.
1.4.1 358,080 6/26/2019 1.4.1 is deprecated because it is no longer maintained.
1.4.0 66,400 6/20/2019 1.4.0 is deprecated because it is no longer maintained.
1.2.0 70,630 5/20/2019 1.2.0 is deprecated because it is no longer maintained.
1.1.0 86,080 4/17/2019 1.1.0 is deprecated because it is no longer maintained.
1.0.0 77,896 4/5/2019 1.0.0 is deprecated because it is no longer maintained.
0.8.2-beta 8,495 3/28/2019 0.8.2-beta is deprecated because it is no longer maintained.
0.8.1-beta 2,295 3/21/2019 0.8.1-beta is deprecated because it is no longer maintained.
0.8.0-beta 1,968 3/11/2019 0.8.0-beta is deprecated because it is no longer maintained.
0.7.1-beta 51,416 1/31/2019 0.7.1-beta is deprecated because it is no longer maintained.
0.7.0-beta 28,657 1/17/2019 0.7.0-beta is deprecated because it is no longer maintained.
0.6.0-beta 73,512 12/21/2018 0.6.0-beta is deprecated because it is no longer maintained.
0.5.2-beta 29,412 12/4/2018 0.5.2-beta is deprecated because it is no longer maintained.
0.5.1-beta 11,398 11/20/2018 0.5.1-beta is deprecated because it is no longer maintained.
0.5.0-beta 612,495 10/30/2018 0.5.0-beta is deprecated because it is no longer maintained.
0.4.1-beta 2,882 10/23/2018 0.4.1-beta is deprecated because it is no longer maintained.
0.4.0-beta 996 10/12/2018 0.4.0-beta is deprecated because it is no longer maintained.
0.3.2-beta 2,045 9/26/2018 0.3.2-beta is deprecated because it is no longer maintained.
0.3.1-beta 1,100 9/21/2018 0.3.1-beta is deprecated because it is no longer maintained.
0.3.0-beta 936 9/13/2018 0.3.0-beta is deprecated because it is no longer maintained.
0.2.4-alpha 926 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.