New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

Tracing .NET Applications

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.

Note: The .NET Tracer supports all .NET-based languages (C#, VB.Net, etc).

Configuration

There are multiple ways to configure the .NET Tracer:

  • via code, using properties on the TracerSettings class
  • environment variables
  • <appSettings> section of the app.config/web.config file (.NET Framework only)

The following table lists the supported configuration variables. The first column indicates the name used in environment variables or configuration files. The second column indicates the name of the propery on the TracerSettings class. You can access these properties in the code through Tracer.Instance.Settings.

Setting nameProperty NameDescription
DD_TRACE_ENABLEDTraceEnabledEnables or disables the profiler. Valid values are: true (default) or false
DD_TRACE_LOG_PATHN/ASets the path for the profiler’s log file.

Windows default: %ProgramData%\Datadog .NET Tracer\logs\dotnet-profiler.log

Linux default: /var/log/datadog/dotnet-profiler.log
DD_TRACE_AGENT_URLAgentUriSets the URL endpoint where traces are sent. Overrides DD_AGENT_HOST and DD_TRACE_AGENT_PORT if set. Default value is http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>.
DD_AGENT_HOSTN/ASets the host where traces are sent (the host running the Agent). Can be a hostname or an IP address. Ignored if DD_TRACE_AGENT_URL is set. Default is value localhost.
DD_TRACE_AGENT_PORTN/ASets the port where traces are sent (the port where the Agent is listening for connections). Ignored if DD_TRACE_AGENT_URL is set. Default value is 8126.
DD_ENVEnvironmentAdds the env tag with the specified value to generated spans. See Agent configuration for more details about the env tag. Default is empty (no env tag).
DD_SERVICE_NAMEServiceNameSets 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). The default is to determine the service name automatically.
DD_LOGS_INJECTIONLogsInjectionEnabledEnables or disables automatic injection of correlation identifiers into application logs.

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>/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>/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>/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

In addition to the settings listed in Getting Started, the following tables list configuration variables specific to automatic instrumentation. The first column indicates the name used in environment variables or configuration files. The second column indicates the name of the propery on the TracerSettings class. You can access these properties in the code through Tracer.Instance.Settings.

Setting nameProperty NameDescription
DD_DISABLED_INTEGRATIONSDisabledIntegrationNamesSets 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.
DD_TRACE_ANALYTICS_ENABLEDAnalyticsEnabledShorthand that enables default Trace Search and Analytics settings for web framework integrations. Valid values are: true or false (default).

The following table lists integration-specific settings. The first column indicates the name used in environment variables or configuration files. The second column indicates the name of the propery on the IntegrationSettings class. You can access these properties in the code through Tracer.Instance.Settings.Integrations["<INTEGRATION>"]. Integration names are listed in the Integrations section below.

Setting nameProperty NameDescription
DD_<INTEGRATION>_ENABLEDEnabledEnables or disables a specific integration. Valid values are: true (default) or false.
DD_<INTEGRATION>_ANALYTICS_ENABLEDAnalyticsEnabledEnables or disable Trace Search and Analytics for a specific integration. Valid values are: true or false (default).
DD_<INTEGRATION>_ANALYTICS_SAMPLE_RATEAnalyticsSampleRateSets the Trace Search and Analytics sampling rate for a specific integration. A floating number between 0.0 and 1.0 (default).

Runtime Compatibility

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

RuntimeVersionsOS
.NET Framework4.5+Windows
.NET Core 12.0+Windows, Linux

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 libraryNuGet package namePackage versionsIntegration Name
ASP.NET MVCMicrosoft.AspNet.Mvc5.1.0+ and 4.0.40804AspNetMvc
ASP.NET Web API 2Microsoft.AspNet.WebApi.Core5.2+AspNetWebApi2
ASP.NET Core MVCMicrosoft.AspNetCore.Mvc.Core2.0+AspNetCoreMvc2
ASP.NET Web Forms 1built-inAspNet
WCFbuilt-inWcf
ADO.NET 2built-inAdoNet
WebClient / WebRequestbuilt-inWebRequest
HttpClient / HttpClientHandlerbuilt-in or System.Net.Http4.0+HttpMessageHandler
Redis (StackExchange client)StackExchange.Redis1.0.187+StackExchangeRedis
Redis (ServiceStack client)ServiceStack.Redis4.0.48+ServiceStackRedis
ElasticsearchNEST / Elasticsearch.Net5.3.0+ElasticsearchNet
MongoDBMongoDB.Driver / MongoDB.Driver.Core2.1.0+MongoDb

Notes:

1 The AspNet integration adds instrumentation to any ASP.NET application based on System.Web.HttpApplication, which can include applications developed with Web Forms, MVC, Web API, and other web frameworks. To enable the AspNet integration, you must add the Datadog.Trace.ClrProfiler.Managed NuGet package to your application.

2 The ADO.NET integration tries to instrument all ADO.NET providers. Datadog tested SQL Server (System.Data.SqlClient) and PostgreSQL (Npgsql). Other providers (MySQL, SQLite, Oracle) are untested but should work.

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 Manual instrumentation documentation.

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:

RuntimeVersionsOS
.NET Framework4.5+Windows
.NET Core2.0+Windows, Linux, macOS
Mono5.4+Windows, Linux, macOS

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

Change Agent Hostname

Configure your application level tracers to submit traces to a custom Agent hostname:

The .NET Tracer automatically reads the environment variables DD_AGENT_HOST and DD_TRACE_AGENT_PORT to set the Agent endpoint. The Agent endpoint can also be set when creating a new Tracer instance:

using Datadog.Trace;

var uri = new Uri("http://localhost:8126/");
var tracer = Tracer.Create(agentEndpoint: uri);

// optional: set the new tracer as the new default/global tracer
Tracer.Instance = tracer;

Further Reading