Tracing .NET Core Applications

Compatibility requirements

Supported .NET Core runtimes

The .NET Tracer supports instrumentation on .NET Core 2.1, 3.1, .NET 5, .NET 6, and .NET 7.

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

Installation and getting started

Installation

1. Configure the Datadog Agent for APM.
2. Install the tracer.
3. Enable the tracer for your service.
4. View your live data.

Configure the Datadog Agent for APM

Install and configure the Datadog Agent to receive traces from your instrumented application. By default the Datadog Agent is enabled in your datadog.yaml file under apm_config with enabled: true and listens for trace data on http://localhost:8126.

For containerized, serverless, and cloud environments:

1. Set apm_non_local_traffic: true in the apm_config section of your main datadog.yaml configuration file.

2. See the specific setup instructions to ensure that the Agent is configured to receive traces in a containerized environment:

3. The tracing client attempts to send traces to the following:

   • The /var/run/datadog/apm.socket Unix domain socket by default.
   • If the socket does not exist, then traces are sent to localhost:8126.
   • If a different socket, host, or port is required, use the DD_TRACE_AGENT_URL environment variable: DD_TRACE_AGENT_URL=http://custom-hostname:1234 or DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket
   • Using Unix Domain Sockets for trace transport is only supported on .NET Core 3.1 and later.

For more information on how to configure these settings, see Configuration.

4. To ensure the Agent sends data to the right Datadog location, set DD_SITE in the Datadog Agent to .

Tracing is available for other environments, including Heroku, Cloud Foundry, and AWS Elastic Beanstalk.

For all other environments, see the Integrations documentation for that environment and contact Datadog support if you encounter setup issues.

Install the tracer

You can install the Datadog .NET Tracer machine-wide so that all services on the machine are 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.

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 as you require, 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, you must 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:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

[string[]] $v = @("CORECLR_ENABLE_PROFILING=1", "CORECLR_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 CORECLR_ENABLE_PROFILING=1
rem Unless v2.14.0+ and you installed the tracer with the MSI
SET CORECLR_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

Linux

Bash script

To set the required environment variables from a bash file before starting your application:

# Set environment variables
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
export CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
export DD_DOTNET_TRACER_HOME=/opt/datadog

# Set additional Datadog environment variables
export DD_LOGS_INJECTION=true
export DD_RUNTIME_METRICS_ENABLED=true

# Start your application
dotnet example.dll

Linux Docker container

To set the required environment variables on a Linux Docker container:

# Set environment variables
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
ENV CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
ENV DD_DOTNET_TRACER_HOME=/opt/datadog

# Set additional Datadog environment variables
ENV DD_LOGS_INJECTION=true
ENV DD_RUNTIME_METRICS_ENABLED=true

# Start your application
CMD ["dotnet", "example.dll"]

systemctl (per service)

When using systemctl to run .NET applications as a service, you can add the required environment variables to be loaded for a specific service.

1. Create a file called environment.env containing:

   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
   
   # Set additional Datadog environment variables
   DD_LOGS_INJECTION=true
   DD_RUNTIME_METRICS_ENABLED=true
   

2. In the service’s configuration file, reference this as an EnvironmentFile in the service block:

   [Service]
   EnvironmentFile=/path/to/environment.env
   ExecStart=<command used to start the application>
   

3. Restart the .NET service for the environment variable settings to take effect.

systemctl (all services)

When using systemctl to run .NET applications as a service, you can also set environment variables to be loaded for all services run by systemctl.

1. Set the required environment variables by running systemctl set-environment:

   systemctl set-environment CORECLR_ENABLE_PROFILING=1
   systemctl set-environment CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
   systemctl set-environment CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
   systemctl set-environment DD_DOTNET_TRACER_HOME=/opt/datadog
   
   # Set additional Datadog environment variables
   systemctl set-environment DD_LOGS_INJECTION=true
   systemctl set-environment DD_RUNTIME_METRICS_ENABLED=true
   

2. Verify that the environment variables were set by running systemctl show-environment.

3. Restart the .NET service for the environment variables to take effect.

Further reading

Documentation, liens et articles supplémentaires utiles:

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 Deploy ASP.NET Core applications to Azure App ServiceBLOG Optimize your .NET application performance with the Datadog Continuous ProfilerBLOG Examples of custom instrumentationGITHUB Source codeGITHUB