Enabling the .NET Profiler

Datadog .NET Profiler is currently in public beta. Datadog recommends evaluating the profiler in a non-sensitive environment before deploying in production.

The following profiling features are available:

  • Method durations shows the overall time taken by each method from your code.
  • CPU shows the time taken executing CPU tasks (see Configuration section to enable it).
  • Exceptions shows the type and messages of thrown exceptions (see Configuration section to enable it).

Requirements

Supported operating systems for .NET Framework
Windows 10
Windows Server starting from version 2012
Supported operating systems for .NET Core and .NET 5+
Linux with glibc 2.18+ (for example CentOS 7 is not supported)
Windows 10
Windows Server starting from version 2012
Serverless
Continuous Profiler is not supported on serverless platforms, such as AWS Lambda.
Supported .NET runtimes (64-bit applications)
.NET Framework 4.6.1+
.NET Core 2.1, 3.1
.NET 5
.NET 6
Supported languages
Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.

Installation

Note: Datadog's .NET Tracer and Profiler rely on the .NET CLR Profiling API. This API allows only one subscriber (for example, APM). To ensure maximum visibility, run only one APM solution in your application environment.

If you are already using Datadog, upgrade your Agent to version 7.20.2+ or 6.20.2+. The profiler ships together with the tracer, so install it using the following steps, depending on your operating system.

To install the .NET Profiler machine-wide:

  1. Download the latest .NET Tracer package that supports your operating system and architecture.

  2. Run one of the following commands to install the package and create the .NET log directory /var/log/datadog/dotnet with the appropriate permissions:

    Debian or Ubuntu
    sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb && /opt/datadog/createLogPath.sh
    CentOS 8+ or Fedora
    sudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && /opt/datadog/createLogPath.sh
    Alpine or other musl-based distributions
    sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-musl.tar.gz && sh /opt/datadog/createLogPath.sh
    Other distributions
    sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-tar.gz && /opt/datadog/createLogPath.sh
  1. Install or upgrade to the latest version, using the .NET Monitoring MSI installer. Continuous Profiler supports 64-bit Windows, so you need the file like datadog-dotnet-apm-<VERSION>-x64.msi.

  2. Run the installer with administrator privileges.


Note: The following steps include setting environment variables to enable the profiler. Datadog does not recommend setting those environment variables at machine-level. If set at machine-level, every .NET application running on the machine is profiled and this incurs a significant overhead on the CPU and memory of your machine.
  1. Set the following required environment variables for automatic instrumentation to attach to your application:

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
    DD_DOTNET_TRACER_HOME=/opt/datadog
    LD_PRELOAD=/opt/datadog/continuousprofiler/Datadog.Linux.ApiWrapper.x64.so
    DD_PROFILING_ENABLED=1
    DD_ENV=production
    DD_VERSION=1.2.3
    
  2. For standalone applications, manually restart the application as you normally would.

  3. A minute or two after starting your application, your profiles appear on the [Datadog APM > Profiler page][1].

  1. Set needed environment variables to configure and enable Profiler. To enable the Profiler for IIS applications, it is required to set the DD_PROFILING_ENABLED, DD_ENV, DD_SERVICE, and DD_VERSION environment variables in the Registry under HKLM\System\CurrentControlSet\Services\WAS and HKLM\System\CurrentControlSet\Services\W3SVC nodes.

    With the Registry Editor:

    In the Registry Editor, modify the multi-string value called Environment in the HKLM\System\CurrentControlSet\Services\WAS and HKLM\System\CurrentControlSet\Services\W3SVC nodes and set the value data as follows:

    For .NET Core and .NET 5+:

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    DD_PROFILING_ENABLED=1
    DD_ENV=production
    DD_VERSION=1.2.3
    
Using the Registry Editor to create environment variables for a .NET Core application in IIS

For .NET Framework:

COR_ENABLE_PROFILING=1
COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
DD_PROFILING_ENABLED=1
DD_ENV=production
DD_VERSION=1.2.3
Using the Registry Editor to create environment variables for a .NET Framework application in IIS

Note: the environment variables are applied for all IIS applications. Starting with IIS 10, you can set environment variables for each IIS application in the C:\Windows\System32\inetsrv\config\applicationhost.config file. Read the Microsoft documentation for more details.

  1. Completely stop and start IIS by running the following commands as an administrator:

    net stop /y was
    net start w3svc
    
    Note: Use stop and start commands. A reset or restart does not always work.
  2. A minute or two after starting your application, your profiles appear on the Datadog APM > Profiler page.

  1. Set needed environment variables to configure and enable Profiler. To enable the Profiler for your service, it is required to set the DD_PROFILING_ENABLED, DD_ENV, DD_SERVICE, and DD_VERSION environment variables in the Registry key associated to the service.

    With the Registry Editor:

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

    For .NET Core and .NET 5+:

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    DD_PROFILING_ENABLED=1
    DD_SERVICE=MyService
    DD_ENV=production
    DD_VERSION=1.2.3
    
Using the Registry Editor to create environment variables for a Windows service

For .NET Framework:

COR_ENABLE_PROFILING=1
COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
DD_PROFILING_ENABLED=1
DD_SERVICE=MyService
DD_ENV=production
DD_VERSION=1.2.3
Using the Registry Editor to create environment variables for a Windows service

With a PowerShell script:

For .NET Core and .NET 5+:

[string[]] $v = @(
    "CORECLR_ENABLE_PROFILING=1",
    "CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}",
    "DD_PROFILING_ENABLED=1",
    "DD_SERVICE=MyService",
    "DD_ENV=production",
    "DD_VERSION=1.2.3"
)
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\MyService -Name Environment -Value $v

For .NET Framework:

[string[]] $v = @(
    "COR_ENABLE_PROFILING=1",
    "COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}",
    "DD_PROFILING_ENABLED=1",
    "DD_SERVICE=MyService",
    "DD_ENV=production",
    "DD_VERSION=1.2.3"
)
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\MyService -Name Environment -Value $v
  1. A minute or two after you start your application, your profiles appear on the Datadog APM > Profiler page.
  1. Set needed environment variables to configure and enable Profiler for a non-service application, such as console, ASP.NET (Core), Windows Forms, or WPF. To enable the Profiler for Standalone applications, it is required to set the DD_PROFILING_ENABLED, DD_ENV, DD_SERVICE, and DD_VERSION environment variables. The recommended approach is to create a batch file that sets these and starts the application, and run your application using the batch file.

    For .NET Core and .NET 5+:

    SET CORECLR_ENABLE_PROFILING=1
    SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    SET DD_PROFILING_ENABLED=1
    SET DD_SERVICE=MyService
    SET DD_ENV=production
    SET DD_VERSION=1.2.3
    
    REM start the application here
    

    For .NET Framework:

    SET COR_ENABLE_PROFILING=1
    SET COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    SET DD_PROFILING_ENABLED=1
    SET DD_SERVICE=MyService
    SET DD_ENV=production
    SET DD_VERSION=1.2.3
    
    REM start the application here
    
  2. A minute or two after you start your application, your profiles appear on the Datadog APM > Profiler page.

Configuration

You can configure the profiler using the following environment variables. Note that most of these settings also apply to the Tracer configuration. Restart the application after any of these settings is changed.

Environment variableTypeDescription
DD_ENVStringThe environment name, for example, production. If not set, will be unspecified-environment
DD_SERVICEStringThe service name, for example, web-backend. If this is not specified, the .NET Profiler tries to determine the service name automatically from the application name (process entry assembly or process name).
DD_VERSIONStringThe version of your service. If not set, will be unspecified-version
DD_TAGSStringTags to apply to an uploaded profile. Must be a list of <key>:<value> separated by commas such as: layer:api,team:intake.
DD_AGENT_HOSTStringSets the host where profiles are sent (the host running the Agent). Can be a hostname or an IP address. Ignored if DD_TRACE_AGENT_URL is set. Defaults to localhost.
DD_TRACE_AGENT_PORTStringSets the port where profiles are sent (the port where the Agent is listening for connections). Ignored if DD_TRACE_AGENT_URL is set. Defaults to8126.
DD_TRACE_AGENT_URLStringSets the URL endpoint where profiles are sent. Overrides DD_AGENT_HOST and DD_TRACE_AGENT_PORT if set. Defaults to http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>.
DD_TRACE_DEBUGBooleanEnables or disables debug logging (Could help in case of troubleshooting investigation). Valid values are: true or false. Defaults to false.
DD_PROFILING_LOG_DIRStringSets the directory for .NET Profiler logs. Defaults to %ProgramData%\Datadog-APM\logs\.
DD_PROFILING_ENABLEDBooleanIf set to true, enables the .NET Profiler. Defaults to false.
DD_PROFILING_CPU_ENABLEDBooleanIf set to true, enables the CPU profiling. Defaults to false.
DD_PROFILING_EXCEPTION_ENABLEDBooleanIf set to true, enables the Exceptions profiling. Defaults to false.
Note: For IIS applications, you must set environment variables in the Registry (under HKLM\System\CurrentControlSet\Services\WAS and HKLM\System\CurrentControlSet\Services\W3SVC nodes) as shown in the Windows Service tab, above. The environment variables are applied for all IIS applications. Starting with IIS 10, you can set environment variables for each IIS application in the C:\Windows\System32\inetsrv\config\applicationhost.config file. Read the Microsoft documentation for more details.

Further Reading

The Getting Started with Profiler guide takes a sample service with a performance problem and shows you how to use Continuous Profiler to understand and fix the problem.