.NET and .NET Core Compatibility Requirements

The Datadog .NET Tracer supports all .NET-based languages (for example, C#, F#, Visual Basic). It has beta support for trimmed apps.

The .NET Tracer is open source. For more information, see the .NET Tracer repository.

Supported .NET and .NET Core runtimes

The .NET Tracer supports automatic instrumentation on the following .NET and .NET Core versions. It also supports .NET Framework.

.NET VersionMicrosoft End of LifeSupport levelPackage version
.NET 8GAlatest (>= 2.42.0)
.NET 705/14/2024GAlatest (>= 2.20.0)
.NET 6GAlatest (>= 2.0.0)
.NET 505/10/2022GAlatest (>= 2.0.0)
.NET Core 3.112/13/2022GAlatest
.NET Core 3.003/03/2020EOLNot recommended
.NET Core 2.212/23/2019EOLNot recommended
.NET Core 2.108/21/2021EOLNot recommended
.NET Core 2.010/01/2018EOLNot recommended

Additional information can be found in Microsoft’s .NET and .NET Core Lifecycle Policy, End of life .NET runtime versions, and .NET runtime support policy.

Supported processor architectures

The .NET Tracer supports automatic instrumentation on the following architectures:

Processor architecturesSupport levelPackage version
Windows x64 (win-x64)GAlatest
Windows x86 (win-x86)GA< 3.0.0 (e.g. 2.56.0)
Linux x64 (linux-x64)GAlatest
Alpine Linux x64 (linux-musl-x64)GAlatest
Linux ARM64 (linux-arm64)GA.NET 5+ only, added in version 1.27.0
Alpine Linux arm64 (linux-musl-arm64)GA.NET 6+ only, added in version 3.2.0

Note that running 32-bit applications on Windows x64 is supported.

Supported operating systems

The .NET Tracer supports automatic instrumentation on Windows and Linux operating systems. It supports macOS for CI Test Visibility only.

Windows

Operating SystemVersionSupport levelPackage version
Windows Server (x64)2012+GAlatest
Windows Client (x64)8.1+GAlatest
Nano Server (x64)< 2012EOL< 3.0.0 (e.g. 2.48.0)
Windows Server (x64)< 2012EOL< 3.0.0 (e.g. 2.48.0)
Windows Server (x86)All versionsEOL< 3.0.0 (e.g. 2.48.0)

Additional information on the operating systems supported by .NET and .NET Core can be found in the .NET release notes

Linux

The .NET Tracer supports Linux distributions as best-effort, based on minimum libc version compatibility:

  • x64: glibc 2.17 (from CentOS 7)
  • Arm64: glibc 2.23 (from Debian 10)
  • Alpine x64: musl 1.2.2 (from Alpine 3.14)
  • Alpine arm64: musl 1.2.4 (from Alpine 3.18)
Operating SystemVersionArchitecturesSupport levelPackage version
Alpine Linux (x64)3.14+x64,GAlatest (.NET 5+ only, v1.27.0+)
Alpine Linux (arm64)3.18+Arm64GAlatest (.NET 6+ only, v3.2.0+)
CentOS Linux7+x64Maintenancelatest (EOL in v4.0.0)
CentOS Stream Linux8x64Maintenancelatest (EOL in v4.0.0)
Debian10+x64, Arm64GAlatest
Fedora29+x64GAlatest
openSUSE15+x64GAlatest
Red Hat Enterprise Linux7+x64GAlatest
Ubuntu18.04+x64, Arm64GAlatest

macOS

The .NET Tracer supports macOS for CI Test Visibility only

Operating SystemVersionArchitecturesSupport levelPackage version
macOS12.0+x64, Arm64GAlatest
macOS11.0x64EOL< 3.0.0
macOS11.0Arm64EOL< 3.0.0 (Added in 2.20.0)

Integrations

The latest version of the .NET Tracer can automatically instrument the following libraries:

Framework or libraryNuGet packageIntegration Name
ADO.NETAll AdoNet integrationsAdoNet
AerospikeAerospike.Client 4.0.0+Aerospike
ASP.NET CoreMicrosoft.AspNetCore
Microsoft.AspNetCore.App
2.0+ and 3.0+		AspNetCore
Azure FunctionsMicrosoft.Azure.Webjobs 3.0+AzureFunctions
Amazon DynamoDBAWSSDK.DynamoDBv2 3.0+AwsDynamoDb
Amazon KinesisAWSSDK.Kinesis 3.0+AwsKinesis
Amazon SNSAWSSDK.SNS 3.0+AwsSns
Amazon SQSAWSSDK.SQS 3.0+AwsSqs
CosmosDbMicrosoft.Azure.Cosmos 3.6.0+CosmosDb
CouchbaseCouchbaseNetClient 2.2.8+Couchbase
ElasticsearchElasticsearch.Net 5.3.0+ElasticsearchNet
GraphQL .NETGraphQL 2.3.0+GraphQL
gRPCGrpc.Net.Client2.30.0+ (.NET Core 3.0+ only)
Grpc.Core 2.30.0+
Grpc.AspNetCore 2.30.0+		Grpc
HotChocolateHotChocolate 11.0.0+HotChocolate
HttpClient / HttpMessageHandlerSystem.Net.Http 4.0+HttpMessageHandler
KafkaConfluent.Kafka 1.4+Kafka
IBM MQamqmdnetstd 9.0.0+IbmMq
MongoDBMongoDB.Driver.Core 2.1.0+MongoDb
MySqlMySql.Data 6.7.0+
MySqlConnector 0.61.0+		MySql
OracleOracle.ManagedDataAccess 4.122.0+Oracle
PostgreSQLNpgsql 4.0+Npgsql
Process"System.Diagnostics.Process" 4.0+Process
RabbitMQRabbitMQ.Client 3.6.9+ .RabbitMQ
Redis (ServiceStack client)ServiceStack.Redis 4.0.48+ServiceStackRedis
Redis (StackExchange client)StackExchange.Redis 1.0.187+StackExchangeRedis
Service Fabric RemotingMicrosoft.ServiceFabric.Services.Remoting 4.0.470+ServiceRemoting
SQLiteSystem.Data.Sqlite 2.0.0+
Microsoft.Data.Sqlite 1.0.0+		Sqlite
SQL ServerSystem.Data 4.0.0+
System.Data.SqlClient 4.0.0+
Microsoft.Data.SqlClient 1.0.0+		SqlClient
WebClient / WebRequestSystem.Net.Requests 4.0+WebRequest

Don’t see the library you’re looking for? First, check if the library produces observability data compatible with OpenTelemetry (see Using OpenTelemetry Instrumentation Libraries for more details). If not, Datadog is continually adding additional support. Check with the Datadog team for help.

End of life .NET runtime versions

The .NET Tracer works on .NET Core 2.0, 2.1, 2.2, 3.0, and 3.1, and on .NET 5 and 7, but these versions reached their end of life and are no longer supported by Microsoft. See Microsoft’s support policy for more details. Datadog recommends using the latest patch version of .NET 6 or .NET 8. Older versions of .NET and .NET Core may encounter the following runtime issues when enabling automatic instrumentation:

IssueAffected .NET VersionsSolutionMore information
JIT Compiler bug on Linux/x642.0.x,
2.1.0-2.1.11,
2.2.0-2.2.5		Upgrade .NET Core to the latest patch version, or follow steps in the linked issueDataDog/dd-trace-dotnet/issues/302
Resource lookup bug with a non en-US locale2.0.0Upgrade .NET Core to 2.0.3 or abovedotnet/runtime/issues/23938
JIT Compiler bug causing crash on shutdown2.0.0-2.2.xUpgrade .NET Core to 3.1.0 or abovedotnet/runtime/pull/11885
JIT Compiler bug2.x, 3.x, 5.x, 6.x, 7.x, 8.0.0-8.0.5Upgrade .NET to 8.0.6 or abovedotnet/runtime/pull/73760
JIT Compiler bugAll versions of .NETNo current workarounddotnet/runtime/issues/85777
.NET runtime bug causing crashes when used with runtime metrics6.0.0-6.0.10Upgrade .NET 6.0.11 or above, or disable runtime metricsdotnet/runtime/pull/76431

Supported Datadog Agent versions

Datadog Agent versionPackage version
7.xLatest
6.xLatest
5.xLatest

.NET runtime support policy

The .NET Tracer depends on the host operating system, .NET runtime, certain .NET libraries, and the Datadog Agent/API. These third party software systems support specific versions of .NET and .NET Core. When the external software no longer supports a version of .NET, the .NET Tracer also limits its support for that version.

Levels of support

LevelSupport provided
UnsupportedNo implementation. Contact customer support for special requests.
BetaInitial implementation. May not yet contain all features. Support for new features, bug & security fixes provided on a best-effort basis.
General Availability (GA)Full implementation of all features. Full support for new features, bug & security fixes.
MaintenanceFull implementation of existing features. Does not receive new features. Support for bug & security fixes only.
End-of-life (EOL)No support.

Package versioning

The .NET Tracer practices semantic versioning. Version updates imply the following changes to runtime support:

  • Major version updates (for example 1.0.0 to 2.0.0) may change support for any runtime from Beta/GA to Maintenance/EOL.
  • Minor version updates (for example 1.0.0 to 1.1.0) won’t lower the level of support for one runtime but may add support for one.
  • Patch version updates (for example 1.0.0 to 1.0.1) will not change support for any runtime.

Further reading

Additional helpful documentation, links, and articles:

Instrument Your ApplicationDOCUMENTATION more more Examples of Custom InstrumentationSOURCE CODE more more Monitor containerized ASP.NET Core applicationsBLOG more more
PREVIEWING: may/unit-testing