The profiler is shipped within Datadog tracing libraries. If you are already using APM to collect traces for your application, you can skip installing the library and go directly to enabling the profiler.

Requirements

For a summary of the minimum and recommended runtime and tracer versions across all languages, read Supported Language and Tracer Versions.

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.17+ (for example, CentOS 7+) and musl-based (Alpine)
Windows 10
Windows Server starting from version 2012
Serverless
Azure App Service Windows and Linux - Web Apps only, Function Apps are not supported
Supported .NET runtimes (64-bit applications)
.NET Framework 4.6.1+
.NET Core 2.1, 3.1
.NET 5
.NET 6
.NET 7
.NET 8
Note: For containers, at least one core is required. Read the Troubleshooting documentation for more details.
Supported languages
Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.

The following profiling features are available in the following minimum versions of the dd-trace-dotnet library:

FeatureRequired dd-trace-dotnet versionRequired .NET Runtime versions
Wall time profiling2.7.0+All supported runtime versions.
CPU profiling2.15.0+All supported runtime versions.
Exceptions profiling2.31.0+All supported runtime versions.
Allocations profilingbeta, 2.18.0+.NET 6+
Lock Contention profiling2.31.0+.NET 5+
Live heap profilingbeta, 2.22.0+.NET 7+
Code Hotspots2.7.0+All supported runtime versions.
Endpoint Profiling2.15.0+All supported runtime versions.
Timeline2.30.0+All supported runtime versions (except .NET 5+ required for garbage collection details).

Installation

If you are already using Datadog, upgrade your Agent to version 7.20.2+ or 6.20.2+. The profiler ships together with the tracing library (beginning with v2.8.0), so if you are already using APM to collect traces for your application, you can skip installing the library and go directly to Enabling the profiler.

Otherwise, install the profiler using the following steps, depending on your operating system.

Note: Datadog's automatic instrumentation relies on the .NET CLR Profiling API. Since this API allows only one subscriber, run only one APM solution in your application environment.

You can install the Datadog .NET Profiler machine-wide so that all services on the machine can be instrumented, or you can install it on a per-application basis to allow developers to manage the instrumentation through the application’s dependencies. To see machine-wide installation instructions, click the Windows or Linux tab. To see per-application installation instructions, click the NuGet tab.

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 && sudo /opt/datadog/createLogPath.sh
    CentOS 7+ or Fedora
    sudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && sudo /opt/datadog/createLogPath.sh
    Alpine or other musl-based distributions
    sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-musl.tar.gz && sudo sh /opt/datadog/createLogPath.sh
    Other distributions
    sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-tar.gz && sudo /opt/datadog/createLogPath.sh

To install the .NET Profiler machine-wide:

  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: This installation does not instrument applications running in IIS. For applications running in IIS, follow the Windows machine-wide installation process.

To install the .NET Profiler per-application:

  1. Add the Datadog.Trace.Bundle NuGet package to your application.
Note: Only Web Apps are supported. Functions are not supported.

To install the .NET Profiler per-webapp:

  1. Install the Azure App Service Datadog APM Extension for Windows or use the Linux setup for your webapp.

Enabling the Profiler

Note: Datadog does not recommend enabling the profiler at machine-level or for all IIS applications. If you do have enabled it machine-wide, read the Troubleshooting documentation for information about reducing the overhead that is associated with enabling the profiler for all system applications.
  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. With Single Step Instrumentation, set the following required environment variables for automatic instrumentation to attach to your application:

    LD_PRELOAD=/opt/datadog/apm/library/dotnet/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. 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 environment variable in the Registry under HKLM\System\CurrentControlSet\Services\WAS and HKLM\System\CurrentControlSet\Services\W3SVC nodes.

    Starting v2.14.0, you don't need to set CORECLR_PROFILER or COR_PROFILER if you installed the tracer using the MSI.

    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.

  2. 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.
  3. 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 environment variable in the Registry key associated to the service. If the profiler is running alone (the tracer is deactivated), you can optionally add the DD_SERVICE, DD_ENV and DD_VERSION environment variables.

    Starting v2.14.0, you don't need to set CORECLR_PROFILER or COR_PROFILER if you installed the tracer using the MSI.

    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
    
  2. A minute or two after you start your application, your profiles appear on the Datadog APM > Profiler page.

Starting v2.14.0, you don't need to set CORECLR_PROFILER or COR_PROFILER if you installed the tracer using the MSI.
  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 environment variable. If the profiler is running alone (the tracer is deactivated), you can optionally set the DD_SERVICE, DD_ENV 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.

  1. Set the following required environment variables for profiling to attach to your application:

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
    CORECLR_PROFILER_PATH=<System-dependent path>
    DD_PROFILING_ENABLED=1
    LD_PRELOAD=<System-dependent path>
    DD_SERVICE=MyService
    DD_ENV=production
    DD_VERSION=1.2.3
    DD_DOTNET_TRACER_HOME=<APP_DIRECTORY>/datadog
    

    The value for the <APP_DIRECTORY> placeholder is the path to the directory containing the application’s .dll files. The value for the CORECLR_PROFILER_PATH environment variable varies based on the system where the application is running:

    Operating System and Process ArchitectureCORECLR_PROFILER_PATH ValueLD_PRELOAD Value
    Alpine Linux x64<APP_DIRECTORY>/datadog/linux-musl-x64/Datadog.Trace.ClrProfiler.Native.so<APP_DIRECTORY>/datadog/linux-musl-x64/Datadog.Linux.ApiWrapper.x64.so
    Linux x64<APP_DIRECTORY>/datadog/linux-x64/Datadog.Trace.ClrProfiler.Native.so<APP_DIRECTORY>/datadog/linux-x64/Datadog.Linux.ApiWrapper.x64.so
    Linux ARM64<APP_DIRECTORY>/datadog/linux-arm64/Datadog.Trace.ClrProfiler.Native.so<APP_DIRECTORY>/datadog/linux-arm64/Datadog.Linux.ApiWrapper.x64.so
    Windows x64<APP_DIRECTORY>\datadog\win-x64\Datadog.Trace.ClrProfiler.Native.dllN/A
    Windows x86<APP_DIRECTORY>\datadog\win-x86\Datadog.Trace.ClrProfiler.Native.dllN/A
  2. For Docker images running on Linux, configure the image to run the createLogPath.sh script:

    RUN /<APP_DIRECTORY>/datadog/createLogPath.sh
    

    Docker examples are available in the dd-trace-dotnet repository.

  3. For standalone applications, manually restart the application.

  1. Follow these installation guidelines (Windows or Linux) to set DD_PROFILING_ENABLED:true to enable the profiler.

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 .NET Tracer\logs\. (Prior to v2.24, the default directory was %ProgramData%\Datadog-APM\logs\)
DD_PROFILING_ENABLEDBooleanIf set to true, enables the .NET Profiler. Defaults to false.
DD_PROFILING_WALLTIME_ENABLEDBooleanIf set to false, disables the Wall time profiling. Defaults to true.
DD_PROFILING_CPU_ENABLEDBooleanIf set to false, disables the CPU profiling. Defaults to true.
DD_PROFILING_EXCEPTION_ENABLEDBooleanIf set to true, enables the Exceptions profiling (beta). Defaults to false.
DD_PROFILING_ALLOCATION_ENABLEDBooleanIf set to true, enables the Allocations profiling (beta). Defaults to false.
DD_PROFILING_LOCK_ENABLEDBooleanIf set to true, enables the Lock Contention profiling (beta). Defaults to false.
DD_PROFILING_HEAP_ENABLEDBooleanIf set to true, enables the Live Heap profiling (beta). Defaults to false.
DD_PROFILING_GC_ENABLEDBooleanIf set to false, disable Garbage Collection profiling used in Timeline user interface. Defaults to true.
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.