Enabling the .NET Profiler
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
- 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:
Feature | Required dd-trace-dotnet version | Required .NET Runtime versions |
---|
Wall time profiling | 2.7.0+ | All supported runtime versions. |
CPU profiling | 2.15.0+ | All supported runtime versions. |
Exceptions profiling | 2.31.0+ | All supported runtime versions. |
Allocations profiling | Preview, 2.18.0+ | .NET Framework beta (requires Datadog Agent 7.51+) and .NET 6+ |
Lock Contention profiling | 2.49.0+ | .NET Framework beta (requires Datadog Agent 7.51+) and .NET 5+ |
Live heap profiling | Preview, 2.22.0+ | .NET 7+ |
Code Hotspots | 2.7.0+ | All supported runtime versions. |
Endpoint Profiling | 2.15.0+ | All supported runtime versions. |
Timeline | 2.30.0+ | All supported runtime versions (except .NET 5+ required for garbage collection details). |
Continuous Profiler is not supported for AWS Lambda.
Installation
Ensure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+. 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:
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:
- 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:
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.
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:
- 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:
- 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.
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.
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
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
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
Note: Use 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.
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
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
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
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.
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
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.
- 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 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 .NET Tracer\logs\ . (Prior to v2.24, the default directory was %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 Exception profiling. Defaults to false . |
DD_PROFILING_ALLOCATION_ENABLED | Boolean | If set to true , enables Allocation profiling (in Preview). Defaults to false . |
DD_PROFILING_LOCK_ENABLED | Boolean | If set to true , enables Lock Contention profiling. Defaults to false . |
DD_PROFILING_HEAP_ENABLED | Boolean | If set to true , enables Live Heap profiling (in Preview). Defaults to false . |
DD_PROFILING_GC_ENABLED | Boolean | If set to false , disable Garbage Collection profiling used in Timeline user interface. Defaults to true . |
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.
Additional helpful documentation, links, and articles: