Datadog.Trace 3.6.1

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

// Install Datadog.Trace as a Cake Tool
#tool nuget:?package=Datadog.Trace&version=3.6.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.6.1 32,547 11/26/2024
3.6.0 46,977 11/19/2024
3.5.0 100,213 11/6/2024
3.4.1 85,385 10/28/2024
3.4.0 26,585 10/24/2024
3.3.1 340,028 9/18/2024
3.3.0 28,940 9/16/2024
3.2.0 145,621 9/2/2024
3.1.0-prerelease 1,281 8/14/2024
3.0.0-prerelease 761 7/29/2024
2.61.0 14,776 11/6/2024
2.60.0 40,080 10/24/2024
2.59.0 107,045 9/16/2024
2.58.0 59,523 9/2/2024
2.57.0 325,442 8/14/2024
2.56.0 236,219 7/25/2024
2.55.0 87,419 7/18/2024
2.54.0 164,150 7/9/2024
2.53.2 1,527,929 6/19/2024
2.53.1 82,807 6/17/2024
2.53.0 166,242 6/11/2024
2.52.0 551,743 5/23/2024
2.51.0 499,225 5/6/2024
2.50.0 378,926 4/17/2024
2.49.0 742,716 3/18/2024
2.48.0 1,049,712 2/29/2024
2.47.0 683,578 2/14/2024
2.46.0 666,335 1/24/2024
2.45.0 306,568 1/10/2024
2.44.0 511,499 12/19/2023
2.43.0 382,603 12/5/2023
2.42.0 252,764 11/21/2023
2.41.0 892,268 11/6/2023
2.40.0 507,623 10/16/2023
2.39.0 87,558 10/11/2023
2.38.0 383,467 9/20/2023
2.37.0 613,889 8/31/2023
2.36.0 364,279 8/23/2023
2.35.0 372,859 7/31/2023
2.34.0 38,859 7/25/2023
2.33.0 303,010 7/4/2023
2.32.0 343,032 6/20/2023
2.31.0 591,287 5/31/2023
2.30.0 749,113 5/5/2023
2.29.0 371,859 4/17/2023
2.28.0 107,090 4/12/2023
2.27.0 550,987 3/24/2023
2.26.0 351,798 3/9/2023
2.24.1 756,609 2/27/2023
2.24.0 51,790 2/24/2023
2.23.0 590,297 2/8/2023
2.22.0 576,977 1/24/2023
2.21.0 463,771 12/20/2022
2.20.0 487,741 12/2/2022
2.19.0 458,975 11/10/2022
2.18.0 844,095 10/25/2022
2.17.0 999,510 10/11/2022
2.16.0 75,082 10/7/2022
2.15.0 411,618 9/26/2022
2.14.0 544,627 8/23/2022
2.13.0 281,998 8/3/2022
2.12.0 426,662 7/13/2022
2.11.0 518,740 6/22/2022
2.10.0 362,306 6/9/2022
2.9.0 803,734 5/13/2022
2.8.0 347,587 5/5/2022
2.7.0 327,609 4/22/2022
2.6.0 572,106 4/7/2022
2.5.1 268,044 3/25/2022
2.4.4 884,975 3/16/2022
2.4.3 478,883 3/2/2022
2.4.2 105,929 2/25/2022
2.4.1 5,200 2/24/2022
2.4.0 17,255 2/22/2022
2.3.0 462,640 2/10/2022
2.2.0 204,426 2/2/2022
2.1.1 383,390 1/19/2022
2.1.0 497,048 1/7/2022
2.0.1 445,166 12/20/2021
2.0.0-prerelease 14,174 12/10/2021
1.31.2 395,424 2/22/2022 1.31.2 is deprecated because it is no longer maintained.
1.31.1 39,244 12/21/2021 1.31.1 is deprecated because it is no longer maintained.
1.31.0 306,240 12/2/2021 1.31.0 is deprecated because it is no longer maintained.
1.30.1 131,898 11/24/2021 1.30.1 is deprecated because it is no longer maintained.
1.30.0 429,776 11/16/2021 1.30.0 is deprecated because it is no longer maintained.
1.29.1-prerelease 66,146 10/28/2021 1.29.1-prerelease is deprecated because it is no longer maintained.
1.29.0 944,711 10/15/2021 1.29.0 is deprecated because it is no longer maintained.
1.28.8 114,652 9/29/2021 1.28.8 is deprecated because it is no longer maintained.
1.28.7 170,185 9/14/2021 1.28.7 is deprecated because it is no longer maintained.
1.28.6 71,126 9/8/2021 1.28.6 is deprecated because it is no longer maintained.
1.28.5-prerelease 858 8/30/2021 1.28.5-prerelease is deprecated because it is no longer maintained.
1.28.4 177,872 8/30/2021 1.28.4 is deprecated because it is no longer maintained.
1.28.3-prerelease 431 8/17/2021 1.28.3-prerelease is deprecated because it is no longer maintained.
1.28.2 228,718 8/4/2021 1.28.2 is deprecated because it is no longer maintained.
1.28.1-prerelease 539 7/14/2021 1.28.1-prerelease is deprecated because it is no longer maintained.
1.28.0 246,025 7/12/2021 1.28.0 is deprecated because it is no longer maintained.
1.27.1 812,586 6/16/2021 1.27.1 is deprecated because it is no longer maintained.
1.27.0 176,602 6/2/2021 1.27.0 is deprecated because it is no longer maintained.
1.26.3 441,737 5/11/2021 1.26.3 is deprecated because it is no longer maintained.
1.25.2-prerelease 2,552 4/2/2021 1.25.2-prerelease is deprecated because it is no longer maintained.
1.25.0 440,159 3/22/2021 1.25.0 is deprecated because it is no longer maintained.
1.24.0 365,860 2/23/2021 1.24.0 is deprecated because it is no longer maintained.
1.23.0 296,537 2/3/2021 1.23.0 is deprecated because it is no longer maintained.
1.22.2-prerelease 443 2/1/2021 1.22.2-prerelease is deprecated because it is no longer maintained.
1.22.1-prerelease 465 1/28/2021 1.22.1-prerelease is deprecated because it is no longer maintained.
1.22.0 211,727 1/14/2021 1.22.0 is deprecated because it is no longer maintained.
1.21.2-prerelease 3,050 12/21/2020 1.21.2-prerelease is deprecated because it is no longer maintained.
1.21.1 68,976 12/17/2020 1.21.1 is deprecated because it is no longer maintained.
1.21.0 115,323 11/25/2020 1.21.0 is deprecated because it is no longer maintained.
1.20.0 330,379 11/3/2020 1.20.0 is deprecated because it is no longer maintained.
1.19.6-prerelease 1,564 10/15/2020 1.19.6-prerelease is deprecated because it is no longer maintained.
1.19.5 374,587 10/7/2020 1.19.5 is deprecated because it is no longer maintained.
1.19.4 106,291 9/29/2020 1.19.4 is deprecated because it is no longer maintained.
1.19.3 179,532 9/17/2020 1.19.3 is deprecated because it is no longer maintained.
1.19.2 274,327 8/31/2020 1.19.2 is deprecated because it is no longer maintained.
1.19.1 693,937 8/10/2020 1.19.1 is deprecated because it is no longer maintained.
1.19.0 69,682 8/7/2020 1.19.0 is deprecated because it is no longer maintained.
1.18.3 204,302 7/17/2020 1.18.3 is deprecated because it is no longer maintained.
1.18.2 55,799 7/9/2020 1.18.2 is deprecated because it is no longer maintained.
1.18.1-prerelease 574 7/6/2020 1.18.1-prerelease is deprecated because it is no longer maintained.
1.18.0 35,323 6/25/2020 1.18.0 is deprecated because it is no longer maintained.
1.17.1-prerelease 626 6/23/2020 1.17.1-prerelease is deprecated because it is no longer maintained.
1.17.0 422,061 5/15/2020 1.17.0 is deprecated because it is no longer maintained.
1.16.3-prerelease 588 5/13/2020 1.16.3-prerelease is deprecated because it is no longer maintained.
1.16.2 56,092 5/5/2020 1.16.2 is deprecated because it is no longer maintained.
1.16.1 234,687 4/20/2020 1.16.1 is deprecated because it is no longer maintained.
1.16.0 41,835 4/2/2020 1.16.0 is deprecated because it is no longer maintained.
1.15.1-prerelease 698 3/30/2020 1.15.1-prerelease is deprecated because it is no longer maintained.
1.15.0 259,651 3/23/2020 1.15.0 is deprecated because it is no longer maintained.
1.14.2 19,060 3/13/2020 1.14.2 is deprecated because it is no longer maintained.
1.14.1-prerelease 526 3/12/2020 1.14.1-prerelease is deprecated because it is no longer maintained.
1.14.0 7,674 3/9/2020 1.14.0 is deprecated because it is no longer maintained.
1.13.4-prerelease 1,526 3/4/2020 1.13.4-prerelease is deprecated because it is no longer maintained.
1.13.3-prerelease 593 2/24/2020 1.13.3-prerelease is deprecated because it is no longer maintained.
1.13.2 118,282 2/21/2020 1.13.2 is deprecated because it is no longer maintained.
1.13.0 363,215 2/14/2020 1.13.0 is deprecated because it is no longer maintained.
1.12.0 101,620 2/5/2020 1.12.0 is deprecated because it is no longer maintained.
1.11.1-prerelease 1,408 1/13/2020 1.11.1-prerelease is deprecated because it is no longer maintained.
1.11.0 129,212 12/11/2019 1.11.0 is deprecated because it is no longer maintained.
1.10.3-prerelease 665 12/11/2019 1.10.3-prerelease is deprecated because it is no longer maintained.
1.10.2-prerelease 580 12/10/2019 1.10.2-prerelease is deprecated because it is no longer maintained.
1.10.1-prerelease 716 12/10/2019 1.10.1-prerelease is deprecated because it is no longer maintained.
1.10.0 76,967 11/27/2019 1.10.0 is deprecated because it is no longer maintained.
1.9.1-prerelease 1,061 11/14/2019 1.9.1-prerelease is deprecated because it is no longer maintained.
1.9.0 203,066 11/7/2019 1.9.0 is deprecated because it is no longer maintained.
1.8.0 203,045 10/17/2019 1.8.0 is deprecated because it is no longer maintained.
1.7.0 95,389 9/10/2019 1.7.0 is deprecated because it is no longer maintained.
1.6.2 83,745 8/20/2019 1.6.2 is deprecated because it is no longer maintained.
1.6.1 21,853 8/14/2019 1.6.1 is deprecated because it is no longer maintained.
1.6.0 81,719 7/20/2019 1.6.0 is deprecated because it is no longer maintained.
1.4.1 358,333 6/26/2019 1.4.1 is deprecated because it is no longer maintained.
1.4.0 67,771 6/20/2019 1.4.0 is deprecated because it is no longer maintained.
1.2.0 70,852 5/20/2019 1.2.0 is deprecated because it is no longer maintained.
1.1.0 87,347 4/17/2019 1.1.0 is deprecated because it is no longer maintained.
1.0.0 79,756 4/5/2019 1.0.0 is deprecated because it is no longer maintained.
0.8.2-beta 9,293 3/28/2019 0.8.2-beta is deprecated because it is no longer maintained.
0.8.1-beta 2,307 3/21/2019 0.8.1-beta is deprecated because it is no longer maintained.
0.8.0-beta 1,980 3/11/2019 0.8.0-beta is deprecated because it is no longer maintained.
0.7.1-beta 51,475 1/31/2019 0.7.1-beta is deprecated because it is no longer maintained.
0.7.0-beta 29,825 1/17/2019 0.7.0-beta is deprecated because it is no longer maintained.
0.6.0-beta 74,583 12/21/2018 0.6.0-beta is deprecated because it is no longer maintained.
0.5.2-beta 29,422 12/4/2018 0.5.2-beta is deprecated because it is no longer maintained.
0.5.1-beta 11,408 11/20/2018 0.5.1-beta is deprecated because it is no longer maintained.
0.5.0-beta 612,605 10/30/2018 0.5.0-beta is deprecated because it is no longer maintained.
0.4.1-beta 2,894 10/23/2018 0.4.1-beta is deprecated because it is no longer maintained.
0.4.0-beta 1,006 10/12/2018 0.4.0-beta is deprecated because it is no longer maintained.
0.3.2-beta 2,057 9/26/2018 0.3.2-beta is deprecated because it is no longer maintained.
0.3.1-beta 1,112 9/21/2018 0.3.1-beta is deprecated because it is no longer maintained.
0.3.0-beta 948 9/13/2018 0.3.0-beta is deprecated because it is no longer maintained.
0.2.4-alpha 936 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.