Datadog.Trace 2.5.1

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Datadog.Trace --version 2.5.1
NuGet\Install-Package Datadog.Trace -Version 2.5.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="2.5.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Datadog.Trace --version 2.5.1
#r "nuget: Datadog.Trace, 2.5.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=2.5.1

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

Datadog.Trace NuGet package

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

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.

Getting Started

  1. Configure the Datadog agent for APM as described in our documentation.
  2. For automatic instrumentation, install and enable the tracer 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 1.x to 2.0

.NET Tracer 2.0 introduces several breaking changes to the API which allow various performance improvements, add new features, and deprecate problematic ways of using the package. Most of these changes do not require any changes to your code, but some patterns are no longer supported or recommended.

This section describes some of the most important breaking changes. For full details see the release notes on GitHub.

Supported .NET versions

.NET Tracer 2.0 adds support for .NET 6.0 and raises the minimum supported version of .NET Framework from .NET Framework 4.5 to .NET Framework 4.6.1. If you are currently targeting version < 4.6.1, we suggest you upgrade in line with Microsoft's guidance.

For full details of supported versions, see our documentation on .NET Framework compatibility requirements and .NET/.NET Core compatibility requirements.

Singleton Tracer instances

In .NET Tracer 1.x, you could create new Tracer instances with different settings for each instance, using the Tracer constructor. In .NET Tracer 2.0 this constructor is marked [Obsolete] and it is no longer possible to create Tracer instances with different settings. This was done to avoid multiple problematic patterns that were hard for users to detect.

To update your code:

using Datadog.Trace;

// Create your settings as before
var settings = new TracerSettings();

// var tracer = new Tracer(settings) // <- Delete this line
Tracer.Configure(settings);          // <- Add this line

Immutable Tracer.Settings

In .NET Tracer 1.x the TracerSettings object passed into a Tracer instance could be modified later. Depending on the changes, the tracer may or may not respect the changes. In .NET Tracer 2.0, an ImmutableTracerSettings object is created when the Tracer instance is configured. The property Tracer.Settings now returns ImmutableTracerSettings, not TracerSettings. Subsequent changes to the original TracerSettings instance will not be observed by Tracer.

To update your code:

using Datadog.Trace;

var settings = TracerSettings.FromDefaultSources();
settings.TraceEnabled = false;   // TracerSettings are mutable

Tracer.Configure(settings);

// All properties on Tracer.Settings are now read-only
// Tracer.Instance.Settings.TraceEnabled = false; // <- DOES NOT COMPILE

Exporter settings

Exporter-related settings were grouped into the TracerSettings.Exporter property.

To update your code:

using Datadog.Trace;

var settings = TracerSettings.FromDefaultSources();

// settings.AgentUri = "http://localhost:8126";        // <- Delete this line
settings.Exporter.AgentUri = "http://localhost:8126";  // <- Add this line

Tracer.Configure(settings);

Configure ADO.NET integrations individually

In .NET Tracer 1.x, you could configure automatic instrumentation of all ADO.NET integrations using the AdoNet integration ID. In .NET Tracer 2.0, you can now configure specific integrations using the following integration IDs:

  • MySql
  • Npgsql (PostgreSQL)
  • Oracle
  • SqlClient (SQL Server)
  • Sqlite

See our documentation for a complete list of supported integration IDs. Note that you can still disable all ADO.NET integrations using the AdoNet integration ID.

This change also removes the now-obsolete TracerSettings.AdoNetExcludedTypes setting and the corresponding environment variable DD_TRACE_ADONET_EXCLUDED_TYPES. Replace usages of these with TracerSettings.Integrations["<INTEGRATION_NAME>"].Enabled and DD_TRACE_<INTEGRATION_NAME>_ENABLED, respectively:

using Datadog.Trace;

var settings = TracerSettings.FromDefaultSources();

// settings.AdoNetExcludedTypes.Add("MySql");    // <- Delete this line
settings.Integrations["MySql"].Enabled = false;  // <- Add this line

ElasticsearchNet5 integration ID removed

In .NET Tracer 1.x, the integration ID for version 5.x of Elasticsearch.Net was ElasticsearchNet5, and the integration ID for versions 6 and above was ElasticsearchNet. In .NET Tracer 2.0, ElasticsearchNet5 was removed. Use ElasticsearchNet for all versions of Elasticsearch.Net.

To update your code:

using Datadog.Trace;

var settings = TracerSettings.FromDefaultSources();

settings.Integrations["ElasticsearchNet5"].Enabled = false; // <- Delete this line
settings.Integrations["ElasticsearchNet"].Enabled = false;  // <- Add this line

Obsolete APIs have been removed

The following deprecated APIs were removed.

  • TracerSettings.DebugEnabled was removed. Set the DD_TRACE_DEBUG environment variable to 1 to enable debug mode.
  • Tags.ForceDrop and Tags.ForceKeep were removed. Use Tags.ManualDrop and Tags.ManualKeep respectively instead.
  • SpanTypes associated with automatic instrumentation spans, such as MongoDb and Redis, were removed.
  • Tags associated with automatic instrumentation spans, such as AmqpCommand and CosmosDbContainer, were removed.
  • Tracer.Create() was removed. Use Tracer.Configure() instead.
  • TracerSettings.AdoNetExcludedTypes was removed. Use TracerSettings.Integrations to configure ADO.NET automatic instrumentation.
  • Various internal APIs not intended for public consumption were removed.

In addition, some settings were marked obsolete in 2.0:

  • Environment variables DD_TRACE_ANALYTICS_ENABLED, DD_TRACE_{0}_ANALYTICS_ENABLED, and DD_TRACE_{0}_ANALYTICS_SAMPLE_RATE for controlling App Analytics are obsolete. App Analytics has been replaced with Tracing Without Limits. See our documentation for details.
  • TracerSettings.AnalyticsEnabled, IntegrationSettings.AnalyticsEnabled, and IntegrationSettings.AnalyticsSampleRate were marked obsolete.
  • Environment variable DD_TRACE_LOG_PATH is deprecated. Use DD_TRACE_LOG_DIRECTORY instead.

Introduction of interfaces ISpan, IScope, and ITracer

.NET Tracer 2.0 makes the public Scope and Span classes internal. Instead, we now expose public IScope and ISpan interfaces and the tracer API was updated accordingly. If you are currently using explicit types (instead of inferring types with var), replace usages of Scope with IScope and Span with ISpan.

This Tracer release also adds the new ITracer interface, implemented by the Tracer class. The type of static property Tracer.Instance is still Tracer, so use of ITracer is not required, but the new interface can be useful for testing with mocks and dependency injection.

To update your Scope/Span code:

using Datadog.Trace;

// No changes required here (using var)
using (var scope = Tracer.Instance.StartActive("my-operation"))
{
    var span = scope.Span;
    // ...
}

// No longer compiles (Scope and Span are no longer public)
using (Scope scope = Tracer.Instance.StartActive("my-operation"))
{
    Span span = scope.Span;
    // ...
}

// Correct usage with explicit types (using IScope and ISpan)
using (IScope scope = Tracer.Instance.StartActive("my-operation"))
{
    ISpan span = scope.Span;
    // ...
}

Simplification of the tracer interface

In addition to returning IScope, several parameters parameters in the Tracer.StartActive method signature were replaced with a single SpanCreationSettings. The span's service name can no longer be set from Tracer.StartActive. Instead, set Span.ServiceName after creating the span.

To update your Scope/Span code:

using Datadog.Trace;

// No changes required here (using only operation name)
using (var scope = Tracer.Instance.StartActive("my-operation"))
{
    // ...
}

// No longer compiles (most parameters removed)
using (var scope = Tracer.Instance.StartActive("my-operation", parent: spanContext, serviceName: "my-service", ...))
{
    // ...
}

// Correct usage
var spanCreationSettings = new SpanCreationSettings() { Parent = spanContext };
using (var scope = Tracer.Instance.StartActive("my-operation", spanCreationSettings))
{
    scope.Span.ServiceName = "my-service";
    // ...
}

Incorrect integration names are ignored

In .NET Tracer 2.0, any changes made to an IntegrationSettings object for an unknown IntegrationId will not be persisted. Instead, a warning will be logged describing the invalid access.

using Datadog.Trace;

var tracerSettings = TracerSettings.FromDefaultSources();

// Accessing settings for an unknown integration will log a warning
var settings = tracerSettings.Integrations["MyRandomIntegration"];

// changes are not persisted
settings.Enabled = false;

// isEnabled is null, not false
bool? isEnabled = tracerSettings.Integrations["MyRandomIntegration"].Enabled;

Automatic instrumentation changes

DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED enabled by default

.NET Tracer 1.26.0 added the DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED feature flag, which enables improved span names for ASP.NET and ASP.NET Core automatic instrumentation spans, an additional span for ASP.NET Core requests, and additional tags.

In .NET Tracer 2.0, DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED is enabled by default. Due to the change in span names, you may need to update your monitors and dashboards to use the new resource names.

If you do not wish to take advantage of the improved route names, you can disable the feature by setting the DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED environment variable to 0.

Call-site instrumentation removed

Call-site automatic instrumentation was removed in .NET Tracer 2.0 and replaced with call-target instrumentation. This was the default mode since version 1.28.0 on .NET Framework 4.6 or above and .NET Core / .NET 5. Call-target instrumentation provides performance and reliability improvements over call-site instrumentation.

Note: Call-target instrumentation does not support instrumenting custom implementations of DbCommand yet. If you find ADO.NET spans are missing from your traces after upgrading, please raise an issue on GitHub, or contact support.

DD_INTEGRATIONS environment variable no longer needed

The integrations.json file is no longer required for instrumentation. You can remove references to this file, for example by deleting the DD_INTEGRATIONS environment variable.

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 (10)

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

Package Downloads
Datadog.Trace.OpenTracing The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Provides OpenTracing support for Datadog APM

Datadog.Trace.Bundle The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Auto-instrumentation assets for Datadog APM

Datadog.Monitoring.Distribution The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Auto-instrumentation assets for Datadog APM

Lucca.Logs.Shared The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Lucca.Logs

Bekk.Canonical.Logger

Package Description

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
2.49.0 25,723 3/18/2024
2.48.0 142,740 2/29/2024
2.47.0 125,103 2/14/2024
2.46.0 200,263 1/24/2024
2.45.0 146,008 1/10/2024
2.44.0 128,496 12/19/2023
2.43.0 150,920 12/5/2023
2.42.0 104,591 11/21/2023
2.41.0 375,303 11/6/2023
2.40.0 254,769 10/16/2023
2.39.0 50,029 10/11/2023
2.38.0 220,472 9/20/2023
2.37.0 311,694 8/31/2023
2.36.0 225,149 8/23/2023
2.35.0 277,085 7/31/2023
2.34.0 31,904 7/25/2023
2.33.0 244,062 7/4/2023
2.32.0 222,850 6/20/2023
2.31.0 387,704 5/31/2023
2.30.0 564,685 5/5/2023
2.29.0 305,952 4/17/2023
2.28.0 75,964 4/12/2023
2.27.0 364,511 3/24/2023
2.26.0 267,118 3/9/2023
2.24.1 455,644 2/27/2023
2.24.0 50,408 2/24/2023
2.23.0 431,671 2/8/2023
2.22.0 496,122 1/24/2023
2.21.0 394,412 12/20/2022
2.20.0 414,776 12/2/2022
2.19.0 361,915 11/10/2022
2.18.0 727,815 10/25/2022
2.17.0 860,987 10/11/2022
2.16.0 46,434 10/7/2022
2.15.0 349,719 9/26/2022
2.14.0 473,242 8/23/2022
2.13.0 259,343 8/3/2022
2.12.0 344,324 7/13/2022
2.11.0 428,982 6/22/2022
2.10.0 309,885 6/9/2022
2.9.0 644,596 5/13/2022
2.8.0 276,822 5/5/2022
2.7.0 256,362 4/22/2022
2.6.0 493,185 4/7/2022
2.5.1 245,634 3/25/2022
2.4.4 701,289 3/16/2022
2.4.3 421,692 3/2/2022
2.4.2 86,219 2/25/2022
2.4.1 5,121 2/24/2022
2.4.0 16,616 2/22/2022
2.3.0 390,178 2/10/2022
2.2.0 193,143 2/2/2022
2.1.1 332,562 1/19/2022
2.1.0 374,266 1/7/2022
2.0.1 389,404 12/20/2021
2.0.0-prerelease 12,118 12/10/2021
1.31.2 232,329 2/22/2022
1.31.1 38,829 12/21/2021
1.31.0 265,089 12/2/2021
1.30.1 130,471 11/24/2021
1.30.0 364,333 11/16/2021
1.29.1-prerelease 65,478 10/28/2021
1.29.0 742,522 10/15/2021
1.28.8 112,420 9/29/2021
1.28.7 162,777 9/14/2021
1.28.6 68,707 9/8/2021
1.28.5-prerelease 755 8/30/2021
1.28.4 162,427 8/30/2021
1.28.3-prerelease 395 8/17/2021
1.28.2 213,500 8/4/2021
1.28.1-prerelease 510 7/14/2021
1.28.0 239,285 7/12/2021
1.27.1 773,317 6/16/2021
1.27.0 151,140 6/2/2021
1.26.3 426,014 5/11/2021
1.25.2-prerelease 2,512 4/2/2021
1.25.0 405,126 3/22/2021
1.24.0 358,671 2/23/2021
1.23.0 285,626 2/3/2021
1.22.2-prerelease 402 2/1/2021
1.22.1-prerelease 427 1/28/2021
1.22.0 187,425 1/14/2021
1.21.2-prerelease 3,009 12/21/2020
1.21.1 66,306 12/17/2020
1.21.0 112,182 11/25/2020
1.20.0 273,202 11/3/2020
1.19.6-prerelease 1,516 10/15/2020
1.19.5 339,870 10/7/2020
1.19.4 103,911 9/29/2020
1.19.3 168,355 9/17/2020
1.19.2 269,111 8/31/2020
1.19.1 541,195 8/10/2020
1.19.0 69,388 8/7/2020
1.18.3 185,483 7/17/2020
1.18.2 49,982 7/9/2020
1.18.1-prerelease 536 7/6/2020
1.18.0 33,737 6/25/2020
1.17.1-prerelease 599 6/23/2020
1.17.0 414,641 5/15/2020
1.16.3-prerelease 546 5/13/2020
1.16.2 55,963 5/5/2020
1.16.1 210,872 4/20/2020
1.16.0 39,972 4/2/2020
1.15.1-prerelease 672 3/30/2020
1.15.0 238,001 3/23/2020
1.14.2 18,026 3/13/2020
1.14.1-prerelease 488 3/12/2020
1.14.0 7,505 3/9/2020
1.13.4-prerelease 1,476 3/4/2020
1.13.3-prerelease 575 2/24/2020
1.13.2 117,896 2/21/2020
1.13.0 342,832 2/14/2020
1.12.0 95,166 2/5/2020
1.11.1-prerelease 1,332 1/13/2020
1.11.0 122,836 12/11/2019
1.10.3-prerelease 638 12/11/2019
1.10.2-prerelease 546 12/10/2019
1.10.1-prerelease 669 12/10/2019
1.10.0 74,227 11/27/2019
1.9.1-prerelease 982 11/14/2019
1.9.0 175,483 11/7/2019
1.8.0 182,225 10/17/2019
1.7.0 95,117 9/10/2019
1.6.2 67,746 8/20/2019
1.6.1 21,806 8/14/2019
1.6.0 81,329 7/20/2019
1.4.1 357,548 6/26/2019
1.4.0 59,193 6/20/2019
1.2.0 70,324 5/20/2019
1.1.0 83,499 4/17/2019
1.0.0 70,520 4/5/2019
0.8.2-beta 6,757 3/28/2019
0.8.1-beta 2,261 3/21/2019
0.8.0-beta 1,939 3/11/2019
0.7.1-beta 51,171 1/31/2019
0.7.0-beta 25,253 1/17/2019
0.6.0-beta 69,645 12/21/2018
0.5.2-beta 29,335 12/4/2018
0.5.1-beta 11,231 11/20/2018
0.5.0-beta 612,171 10/30/2018
0.4.1-beta 2,851 10/23/2018
0.4.0-beta 964 10/12/2018
0.3.2-beta 2,007 9/26/2018
0.3.1-beta 1,086 9/21/2018
0.3.0-beta 890 9/13/2018
0.2.4-alpha 883 9/13/2018