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.
The following profiling features are available in the following minimum versions of the dd-trace-dotnet library:
| Feature | Required dd-trace-dotnet version |
|---|---|
| Wall time profiling | |
| CPU profiling | 2.15.0+ |
| Exceptions profiling | beta, 2.10.0+ |
| Allocations profiling | beta, 2.18.0+ |
| Lock Contention profiling | beta, 2.18.0+ |
| Live heap profiling | beta, 2.22.0+ |
| Code Hotspots | 2.7.0+ |
| Endpoint Profiling | 2.15.0+ |
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.
Note: The profiler ships with the tracer starting with version 2.8.0. If you’re using an older version of the tracer, you need to upgrade first.
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:
Download the latest .NET Tracer package that supports your operating system and architecture.
Run one of the following commands to install the package and create the .NET log directory /var/log/datadog/dotnet with the appropriate permissions:
sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb && sudo /opt/datadog/createLogPath.shsudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && sudo /opt/datadog/createLogPath.shsudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-musl.tar.gz && sudo sh /opt/datadog/createLogPath.shsudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-tar.gz && sudo /opt/datadog/createLogPath.shTo install the .NET Profiler machine-wide:
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.
Run the installer with administrator privileges.
To install the .NET Profiler per-application:
Datadog.Trace.Bundle NuGet package to your application.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
For standalone applications, manually restart the application as you normally would.
A minute or two after starting your application, your profiles appear on the Datadog APM > Profiler page.
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.
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
DD_PROFILING_ENABLED=1
DD_ENV=production
DD_VERSION=1.2.3
For .NET Framework:
COR_ENABLE_PROFILING=1
DD_PROFILING_ENABLED=1
DD_ENV=production
DD_VERSION=1.2.3
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.
Completely stop and start IIS by running the following commands as an administrator:
net stop /y was
net start w3svc
stop and start commands. A reset or restart does not always work.A minute or two after starting your application, your profiles appear on the Datadog APM > Profiler page.
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.
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
DD_PROFILING_ENABLED=1
DD_SERVICE=MyService
DD_ENV=production
DD_VERSION=1.2.3
For .NET Framework:
COR_ENABLE_PROFILING=1
DD_PROFILING_ENABLED=1
DD_SERVICE=MyService
DD_ENV=production
DD_VERSION=1.2.3
With a PowerShell script:
For .NET Core and .NET 5+:
[string[]] $v = @(
"CORECLR_ENABLE_PROFILING=1",
"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",
"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
A minute or two after you start your application, your profiles appear on the Datadog APM > Profiler page.
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 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 DD_PROFILING_ENABLED=1
SET DD_SERVICE=MyService
SET DD_ENV=production
SET DD_VERSION=1.2.3
REM start the application here
A minute or two after you start your application, your profiles appear on the Datadog APM > Profiler page.
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 Architecture | CORECLR_PROFILER_PATH Value | LD_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.dll | N/A |
| Windows x86 | <APP_DIRECTORY>\datadog\win-x86\Datadog.Trace.ClrProfiler.Native.dll | N/A |
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.
For standalone applications, manually restart the application.
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 variable | Type | Description |
|---|---|---|
DD_ENV | String | The environment name, for example, production. If not set, will be unspecified-environment |
DD_SERVICE | String | The 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_VERSION | String | The version of your service. If not set, will be unspecified-version |
DD_TAGS | String | Tags to apply to an uploaded profile. Must be a list of <key>:<value> separated by commas such as: layer:api,team:intake. |
DD_AGENT_HOST | String | Sets 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_PORT | String | Sets 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_URL | String | Sets 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_DEBUG | Boolean | Enables or disables debug logging (Could help in case of troubleshooting investigation). Valid values are: true or false. Defaults to false. |
DD_PROFILING_LOG_DIR | String | Sets the directory for .NET Profiler logs. Defaults to %ProgramData%\Datadog-APM\logs\. |
DD_PROFILING_ENABLED | Boolean | If set to true, enables the .NET Profiler. Defaults to false. |
DD_PROFILING_WALLTIME_ENABLED | Boolean | If set to false, disables the Wall time profiling. Defaults to true. |
DD_PROFILING_CPU_ENABLED | Boolean | If set to false, disables the CPU profiling. Defaults to true. |
DD_PROFILING_EXCEPTION_ENABLED | Boolean | If set to true, enables the Exceptions profiling (beta). Defaults to false. |
DD_PROFILING_ALLOCATION_ENABLED | Boolean | If set to true, enables the Allocations profiling (beta). Defaults to false. |
DD_PROFILING_LOCK_ENABLED | Boolean | If set to true, enables the Lock Contention profiling (beta). Defaults to false. |
DD_PROFILING_HEAP_ENABLED | Boolean | If set to true, enables the Live Heap profiling (beta). Defaults to false. |
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.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.
