Datadog Synthetics is now available!

Tracing .NET Applications

.NET Tracing is in an open Public Beta.

Getting Started

To begin tracing applications written in any language, first install and configure the Datadog Agent. The .NET Tracer runs in-process to instrument your applications and sends traces to the Agent.

Automatic Instrumentation

Automatic instrumentation uses the Profiling API provided by .NET Framework and .NET Core to modify IL instructions at runtime and inject instrumentation code into your application. With zero code changes and minimal configuration, the .NET Tracer automatically instruments all supported libraries out of the box.

Automatic instrumentation captures:

  • Method execution time
  • Relevant trace data, such as URL and status response codes for web requests or SQL queries for database access
  • Unhandled exceptions, including stacktraces if available
  • A total count of traces (e.g. web requests) flowing through the system

Installation

There are three components needed to enable automatic instrumentation.

  • Native COM library that implements the Profiling API (a .dll file on Windows or .so on Linux) to intercept method calls
  • Managed libraries (Datadog.Trace.dll and Datadog.Trace.ClrProfiler.Managed.dll) that interact with your application to measure method execution time and extract data from method arguments
  • Several environment variables that enable the Profiling API and configure the .NET Tracer

How these components are installed on the host depends on the runtime environment:

Install the .NET Tracer on the host using the MSI installer for Windows. Choose the platform that matches your application: x64 for 64-bits or x86 for 32-bits. You can install both side-by-side if needed.

  • Native library: deployed into Program Files by default and registered as a COM library in the Windows Registry by the MSI installer.
  • Managed libraries: deployed into the Global Assembly Cache (GAC) by the MSI installer, where any .NET Framework application can access them.
  • Environment variables: added for IIS only by the MSI installer. Applications that do not run in IIS need additional configuration to set these environment variables.

Install the .NET Tracer on the host using the MSI installer for Windows. Choose the platform that matches your application: x64 for 64-bits or x86 for 32-bits. You can install both side-by-side if needed.

Add the Datadog.Trace.ClrProfiler.Managed NuGet package to your application, matching the package version to the MSI installer above. Refer to the NuGet documentation for instructions on how to add a NuGet package to your application.

  • Native library: deployed into Program Files by default and registered as a COM library in the Windows Registry by the MSI installer.
  • Managed libraries: deployed together with your application when it is published (via NuGet package).
  • Environment variables: added for IIS only by the MSI installer. Applications that do not run in IIS need additional configuration to set these environment variables.

Add the Datadog.Trace.ClrProfiler.Managed NuGet package to your application, matching the package version to the package below. Refer to the NuGet documentation for instructions on how to add a NuGet package to your application.

Install the .NET Tracer on the host using the using one of the packages available from the dd-trace-dotnet releases page.

For Debian or Ubuntu, download and install the Debian package:

curl -LO https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>-beta/datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb
sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb

For CentOS or Fedora, download and install the RPM package

curl -LO https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>-beta/datadog-dotnet-apm-<TRACER_VERSION>-1.x86_64.rpm
sudo rpm -Uvh datadog-dotnet-apm-<TRACER_VERSION>-1.x86_64.rpm

A tar archive is available for other distributions:

sudo mkdir -p /opt/datadog
curl -L https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>-beta/datadog-dotnet-apm-<TRACER_VERSION>.tar.gz \
| sudo tar xzf - -C /opt/datadog

For Alpine Linux you also need to install libc6-compat

apk add libc6-compat
  • Native library: deployed into /opt/datadog/ by default, or manually if using the tar package.
  • Managed libraries: deployed together with your application when it is published (via NuGet package).
  • Environment variables: additional configuration required.

Required Environment Variables

Note: If your application runs on IIS and you used the MSI installer, you don’t need to configure environment variables manually and you may skip this section.

Note: The .NET runtime tries to load a profiler into any .NET process that is started while these environment variables are set. You should limit profiling only to the applications that need to be traced. Do not set these environment variables globally as this causes all .NET processes on the host to be profiled.

If you used the MSI installer on Windows, the required environment variables are already set for IIS. After restarting IIS, the .NET Tracer becomes enabled. If your application runs on IIS and you used the MSI installer, you may skip the rest of this section.

For applications not running in IIS, set these two environment variables before starting your application to enable automatic instrumentation:

COR_ENABLE_PROFILING=1
COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

COR_PROFILER_PATH is not required because the MSI installer registers the native COM library’s path in the Windows Registry, and DD_INTEGRATIONS is set globally for all processes.

If you did not use the MSI installer, set all four environment variables:

COR_ENABLE_PROFILING=1
COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
COR_PROFILER_PATH=C:\Program Files\Datadog\.NET Tracer\Datadog.Trace.ClrProfiler.Native.dll
DD_INTEGRATIONS=C:\Program Files\Datadog\.NET Tracer\integrations.json

For example, to set them from a batch file before starting you application:

rem Set environment variables
SET COR_ENABLE_PROFILING=1
SET COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
SET COR_PROFILER_PATH=C:\Program Files\Datadog\.NET Tracer\Datadog.Trace.ClrProfiler.Native.dll
SET DD_INTEGRATIONS=C:\Program Files\Datadog\.NET Tracer\integrations.json

rem Start application
example.exe

For Windows Services, you can set environment variables in the multi-string key HKLM\System\CurrentControlSet\Services\{service name}\Environment.

If you used the MSI installer on Windows, the required environment variables are already set for IIS. After restarting IIS, the .NET Tracer will be enabled. If your application runs on IIS and you used the MSI installer, you may skip the rest of this section.

For applications not running in IIS, set these two environment variables before starting your application to enable automatic instrumentation:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

CORECLR_PROFILER_PATH is not required because the MSI installer registers the native COM library’s path in the Windows Registry, and DD_INTEGRATIONS is set globally for all processes.

If you did not use the MSI installer, set all four environment variables:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
CORECLR_PROFILER_PATH=C:\Program Files\Datadog\.NET Tracer\Datadog.Trace.ClrProfiler.Native.dll
DD_INTEGRATIONS=C:\Program Files\Datadog\.NET Tracer\integrations.json

For example, to set them from a batch file before starting you application:

rem Set environment variables
SET CORECLR_ENABLE_PROFILING=1
SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
SET CORECLR_PROFILER_PATH=C:\Program Files\Datadog\.NET Tracer\Datadog.Trace.ClrProfiler.Native.dll
SET DD_INTEGRATIONS=C:\Program Files\Datadog\.NET Tracer\integrations.json

rem Start application
dotnet.exe example.dll

For Windows Services, you can set environment variables in the multi-string key HKLM\System\CurrentControlSet\Services\{service name}\Environment.

On Linux, these four environment variables are required to enable automatic instrumentation:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
DD_INTEGRATIONS=/opt/datadog/integrations.json

For example, to set them from a bash file before starting you application:

# Set environment variables
EXPORT CORECLR_ENABLE_PROFILING=1
EXPORT CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
EXPORT CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
EXPORT DD_INTEGRATIONS=/opt/datadog/integrations.json

# Start your application
dotnet example.dll

To set the environment variables for a systemd service, use Environment=:

[Unit]
Description=example

[Service]
ExecStart=/usr/bin/dotnet /app/example.dll
Restart=always
Environment=CORECLR_ENABLE_PROFILING=1
Environment=CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
Environment=CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
Environment=DD_INTEGRATIONS=/opt/datadog/integrations.json

[Install]
WantedBy=multi-user.target

To set the environment variables on a Linux container in Docker, use ENV:

ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
ENV CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
ENV DD_INTEGRATIONS=/opt/datadog/integrations.json

Configuration

The .NET Tracer is configured using environment variables as follows:

Environment Variable Description Default Value
DD_TRACE_ENABLED Determines whether the profiler is enabled. Valid values are: true or false true
DD_AGENT_HOST Sets the host where traces are sent (the host running the Agent). Can be a hostname or an IP address. localhost
DD_TRACE_AGENT_PORT Sets the port where traces are sent (the port where the Agent is listening for connections). 8126
DD_ENV Adds the env tag with the specified value to generated spans. See Agent configuration for more details about the env tag. empty (no env tag)
DD_SERVICE_NAME Sets the default service name. If not set, the .NET Tracer tries to determine service name automatically from application name (e.g. IIS application name, process entry assembly, or process name). empty (determine service name automatically)
DD_DISABLED_INTEGRATIONS Sets a list of integrations to disable. All other integrations remain enabled. If not set, all integrations are enabled. Supports multiple values separated with semicolons. Valid values are the integration names listed in the Integrations section below empty (all integrations enabled)
DD_TRACE_LOG_PATH Sets the path for the profiler’s log file. Windows: %ProgramData%\Datadog .NET Tracer\logs\dotnet-profiler.log

Linux: /var/log/datadog/dotnet-profiler.log

Runtime Compatibility

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

Runtime Versions OS Support type
.NET Framework 4.5+ Windows Public Beta
.NET Core 1 2.0+ Windows, Linux Public Beta

1 There is an issue in .NET Core versions 2.1.0, 2.1.1, and 2.1.2 that can prevent profilers from working correctly. This issue is fixed in .NET Core 2.1.3. See this GitHub issue for more details.

Don’t see your desired frameworks? Datadog is continually adding additional support. Check with the Datadog team for help.

Integrations

The .NET Tracer can instrument the following libraries automatically:

Framework or library NuGet package name Package versions Support Type Integration Name
ASP.NET MVC 5 Microsoft.AspNet.Mvc 5.1.3+ Public Beta AspNetMvc
ASP.NET MVC 4 Microsoft.AspNet.Mvc 4.0.40804 Public Beta AspNetMvc
ASP.NET Web API 2 Microsoft.AspNet.WebApi.Core 5.2+ Public Beta AspNetWebApi2
ASP.NET Core MVC Microsoft.AspNetCore.Mvc.Core 2.0+ Public Beta AspNetCoreMvc2
ASP.NET Web Forms 1 built-in Experimental2 AspNet
WCF built-in Coming soon
ADO.NET 3 built-in Public Beta AdoNet
WebClient / WebRequest built-in Public Beta WebRequest
HttpClient / HttpClientHandler built-in or System.Net.Http 4.0+ Public Beta HttpMessageHandler
Redis (StackExchange client) StackExchange.Redis 1.0.187+ Public Beta StackExchangeRedis
Redis (ServiceStack client) ServiceStack.Redis 4.0.48+ Public Beta ServiceStackRedis
Elasticsearch NEST / Elasticsearch.Net 6.0.0+ Public Beta ElasticsearchNet
MongoDB MongoDB.Driver / MongoDB.Driver.Core 2.2.0+ Public Beta MongoDb

Notes:

1 The AspNet integration adds instrumentation to any application based on Systme.Web.HttpApplication, which can include applications developed with Web Forms, MVC, Web API, and other web frameworks.

2 The AspNet integration is not enabled by default in .NET Tracer 0.8. To enable it manually for testing purposes, see the release notes for .NET Tracer 0.8.

3 The ADO.NET integration tries to instrument all ADO.NET providers. Support was tested with SQL Server (System.Data.SqlClient) and PostgreSQL (Npgsql). Other providers (e.g. MySQL, SQLite, Oracle) might work, but have not been tested.

Don’t see your desired frameworks? Datadog is continually adding additional support. Check with the Datadog team for help.

Manual Instrumentation

To manually instrument your code, add the Datadog.Trace NuGet package to your application. In your code, access the global tracer through the Datadog.Trace.Tracer.Instance property to create new spans.

For more details on manual instrumentation and custom tagging, see Advanced Usage.

Runtime Compatibility

Manual instrumentation is supported on .NET Framework 4.5+ on Windows and on any platform that implements .NET Standard 2.0 or above:

Runtime Versions OS Support type
.NET Framework 4.5+ Windows Public Beta
.NET Core 2.0+ Windows, Linux, macOS Public Beta
Mono 5.4+ Windows, Linux, macOS Public Beta

For more details on supported platforms, see the .NET Standard documentation.

Further Reading