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
<PackageReference Include="Datadog.Trace" Version="3.3.1" />
paket add Datadog.Trace --version 3.3.1
#r "nuget: Datadog.Trace, 3.3.1"
// 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
- Configure the Datadog agent for APM as described in our documentation.
- Configure automatic instrumentation as described in our documentation.
- Configure custom instrumentation, as shown below
- 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
andTracer
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, settingDD_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 theDatadog.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 | Versions 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. |
-
.NETCoreApp 3.1
- System.Diagnostics.DiagnosticSource (>= 4.4.1)
-
.NETFramework 4.6.1
- No dependencies.
-
.NETStandard 2.0
- System.Diagnostics.DiagnosticSource (>= 4.4.1)
- System.Reflection.Emit (>= 4.3.0)
- System.Reflection.Emit.Lightweight (>= 4.3.0)
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.1 | 39,033 | 12/21/2021 | |
1.31.0 | 293,217 | 12/2/2021 | |
1.30.1 | 131,637 | 11/24/2021 | |
1.30.0 | 413,809 | 11/16/2021 | |
1.29.1-prerelease | 65,842 | 10/28/2021 | |
1.29.0 | 880,556 | 10/15/2021 | |
1.28.8 | 114,243 | 9/29/2021 | |
1.28.7 | 167,335 | 9/14/2021 | |
1.28.6 | 70,819 | 9/8/2021 | |
1.28.5-prerelease | 851 | 8/30/2021 | |
1.28.4 | 173,641 | 8/30/2021 | |
1.28.3-prerelease | 424 | 8/17/2021 | |
1.28.2 | 224,962 | 8/4/2021 | |
1.28.1-prerelease | 532 | 7/14/2021 | |
1.28.0 | 244,216 | 7/12/2021 | |
1.27.1 | 803,291 | 6/16/2021 | |
1.27.0 | 165,938 | 6/2/2021 | |
1.26.3 | 437,321 | 5/11/2021 | |
1.25.2-prerelease | 2,544 | 4/2/2021 | |
1.25.0 | 430,202 | 3/22/2021 | |
1.24.0 | 363,850 | 2/23/2021 | |
1.23.0 | 294,931 | 2/3/2021 | |
1.22.2-prerelease | 435 | 2/1/2021 | |
1.22.1-prerelease | 457 | 1/28/2021 | |
1.22.0 | 204,771 | 1/14/2021 | |
1.21.2-prerelease | 3,042 | 12/21/2020 | |
1.21.1 | 68,342 | 12/17/2020 | |
1.21.0 | 114,698 | 11/25/2020 | |
1.20.0 | 313,644 | 11/3/2020 | |
1.19.6-prerelease | 1,556 | 10/15/2020 | |
1.19.5 | 365,980 | 10/7/2020 | |
1.19.4 | 105,949 | 9/29/2020 | |
1.19.3 | 175,325 | 9/17/2020 | |
1.19.2 | 273,007 | 8/31/2020 | |
1.19.1 | 645,428 | 8/10/2020 | |
1.19.0 | 69,621 | 8/7/2020 | |
1.18.3 | 198,742 | 7/17/2020 | |
1.18.2 | 54,289 | 7/9/2020 | |
1.18.1-prerelease | 565 | 7/6/2020 | |
1.18.0 | 35,016 | 6/25/2020 | |
1.17.1-prerelease | 617 | 6/23/2020 | |
1.17.0 | 420,237 | 5/15/2020 | |
1.16.3-prerelease | 579 | 5/13/2020 | |
1.16.2 | 56,077 | 5/5/2020 | |
1.16.1 | 232,080 | 4/20/2020 | |
1.16.0 | 41,292 | 4/2/2020 | |
1.15.1-prerelease | 690 | 3/30/2020 | |
1.15.0 | 255,127 | 3/23/2020 | |
1.14.2 | 18,696 | 3/13/2020 | |
1.14.1-prerelease | 516 | 3/12/2020 | |
1.14.0 | 7,661 | 3/9/2020 | |
1.13.4-prerelease | 1,518 | 3/4/2020 | |
1.13.3-prerelease | 585 | 2/24/2020 | |
1.13.2 | 118,162 | 2/21/2020 | |
1.13.0 | 357,179 | 2/14/2020 | |
1.12.0 | 100,110 | 2/5/2020 | |
1.11.1-prerelease | 1,396 | 1/13/2020 | |
1.11.0 | 127,105 | 12/11/2019 | |
1.10.3-prerelease | 657 | 12/11/2019 | |
1.10.2-prerelease | 570 | 12/10/2019 | |
1.10.1-prerelease | 708 | 12/10/2019 | |
1.10.0 | 76,094 | 11/27/2019 | |
1.9.1-prerelease | 1,047 | 11/14/2019 | |
1.9.0 | 194,694 | 11/7/2019 | |
1.8.0 | 199,395 | 10/17/2019 | |
1.7.0 | 95,339 | 9/10/2019 | |
1.6.2 | 79,957 | 8/20/2019 | |
1.6.1 | 21,842 | 8/14/2019 | |
1.6.0 | 81,664 | 7/20/2019 | |
1.4.1 | 358,080 | 6/26/2019 | |
1.4.0 | 66,400 | 6/20/2019 | |
1.2.0 | 70,630 | 5/20/2019 | |
1.1.0 | 86,080 | 4/17/2019 | |
1.0.0 | 77,896 | 4/5/2019 | |
0.8.2-beta | 8,495 | 3/28/2019 | |
0.8.1-beta | 2,295 | 3/21/2019 | |
0.8.0-beta | 1,968 | 3/11/2019 | |
0.7.1-beta | 51,416 | 1/31/2019 | |
0.7.0-beta | 28,657 | 1/17/2019 | |
0.6.0-beta | 73,512 | 12/21/2018 | |
0.5.2-beta | 29,412 | 12/4/2018 | |
0.5.1-beta | 11,398 | 11/20/2018 | |
0.5.0-beta | 612,495 | 10/30/2018 | |
0.4.1-beta | 2,882 | 10/23/2018 | |
0.4.0-beta | 996 | 10/12/2018 | |
0.3.2-beta | 2,045 | 9/26/2018 | |
0.3.1-beta | 1,100 | 9/21/2018 | |
0.3.0-beta | 936 | 9/13/2018 | |
0.2.4-alpha | 926 | 9/13/2018 |
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.