Tracing .NET Framework Applications

Compatibility requirements

Supported .NET Framework runtimes

The .NET Tracer supports instrumentation on .NET Framework >= 4.6.1.

For a full list of Datadog’s .NET Framework library and processor architecture support (including legacy and maintenance versions), see Compatibility Requirements.

Installation and getting started

Installation

Before you begin, make sure you’ve already installed and configured the Agent.

1. Choose your instrumentation method
2. Install the tracer.
3. Enable the tracer for your service.
4. View your live data.

Choose your instrumentation method

After you deploy or install and configure your Datadog Agent, the next step is to instrument your application. You can do this in the following ways, depending on the infrastructure your app runs on, the language it’s written in, and the level of configuration you require.

See the following pages for supported deployment scenarios and languages:

• Inject the instrumentation library locally (at the Agent); or
• Add the tracing library directly in the application, as described in the Install the tracer section. Read more about compatibility information.

Install the tracer

Install the Datadog .NET Tracer machine-wide so that all services on the machine are instrumented or on a per-application basis, so developers can manage the instrumentation through the application’s dependencies. To see machine-wide installation instructions, click the Windows tab. To see per-application installation instructions, click the NuGet tab.

Enable the tracer for your service

To enable the .NET Tracer for your service, set the required environment variables and restart the application.

For information about the different methods for setting environment variables, see Configuring process environment variables.

View your live data

After enabling the .NET Tracer for your service:

1. Restart your service.

2. Create application load.

3. In Datadog, navigate to APM > APM Traces.

Configuration

If needed, configure the tracing library to send application performance telemetry data, including setting up Unified Service Tagging. Read Library Configuration for details.

Custom instrumentation

Your setup for custom instrumentation depends on your automatic instrumentation and includes additional steps depending on the method:

For more information on adding spans and tags for custom instrumentation, see the .NET Custom Instrumentation documentation.

Configuring process environment variables

To attach automatic instrumentation to your service, set the required environment variables before starting the application. See Enable the tracer for your service section to identify which environment variables to set based on your .NET Tracer installation method and follow the examples below to correctly set the environment variables based on the environment of your instrumented service.

Windows

Windows services

In the Registry Editor, create a multi-string value called Environment in the HKLM\System\CurrentControlSet\Services\<SERVICE NAME> key and set the value data to:

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

[string[]] $v = @("COR_ENABLE_PROFILING=1", "COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}")
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<SERVICE NAME> -Name Environment -Value $v

IIS

After installing the MSI, no additional configuration is needed to automatically instrument your IIS sites. To set additional environment variables that are inherited by all IIS sites, perform the following steps:

1. Open the Registry Editor, find the multi-string value called Environment in the HKLM\System\CurrentControlSet\Services\WAS key, and add the environment variables, one per line. For example, to add logs injection and runtime metrics, add the following lines to the value data:

   DD_LOGS_INJECTION=true
   DD_RUNTIME_METRICS_ENABLED=true
   

2. Run the following commands to restart IIS:

   net stop /y was
   net start w3svc
   # Also, start any other services that were stopped when WAS was shut down.
   

Console applications

To automatically instrument a console application, set the environment variables from a batch file before starting your application:

rem Set environment variables
SET COR_ENABLE_PROFILING=1
rem Unless v2.14.0+ and you installed the tracer with the MSI
SET COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

rem Set additional Datadog environment variables
SET DD_LOGS_INJECTION=true
SET DD_RUNTIME_METRICS_ENABLED=true

rem Start application
dotnet.exe example.dll

Further reading

Additional helpful documentation, links, and articles:

Connect .NET application logs to tracesDOCUMENTATION Runtime metricsDOCUMENTATION Microsoft Azure App Service extensionDOCUMENTATION Explore your services, resources, and tracesDOCUMENTATION .NET monitoring with Datadog APM and distributed tracingBLOG Monitor containerized ASP.NET Core applicationsBLOG Monitor containerized ASP.NET Core applications on AWS FargateBLOG Optimize your .NET application performance with the Datadog Continuous ProfilerBLOG Examples of custom instrumentationGITHUB Source codeGITHUB