Tracing .NET Core Applications

Otherwise, to begin tracing applications written in any language, first install and configure the Datadog Agent. The .NET Tracer runs in-process to instrument your applications and sends traces from your application to the Agent.

To use automatic instrumentation on Windows, install the .NET Tracer on the host using the MSI installer for Windows. Choose the installer for the architecture that matches the operating system (x64 or x86).

After installing the .NET Tracer, restart applications so they can read the new environment variables. To restart IIS, run the following commands as administrator:

net stop /y was
net start w3svc

Update: Starting with .NET Tracer version 1.8.0, the Datadog.Trace.ClrProfiler.Managed NuGet package is no longer required for automatic instrumentation in .NET Core. Remove it from your application when you update the .NET Tracer.

To use automatic instrumentation on Linux, follow these three steps:

1. Install the .NET Tracer in the environment where your application is running using one of the packages available from the dd-trace-dotnet releases page.

2. Create the required environment variables. See Required Environment Variables below for details.

3. Run the /opt/datadog/createLogPath.sh script, which creates a directory for the log files and sets appropriate directory permissions. The default directory for log files is /var/log/datadog/dotnet.

Update: Starting with .NET Tracer version 1.8.0, the Datadog.Trace.ClrProfiler.Managed NuGet package is no longer required for automatic instrumentation in .NET Core and is deprecated. Remove it from your application when you update the .NET Tracer and add the new environment variable, DD_DOTNET_TRACER_HOME. See Required Environment Variables below for details.

Update: .NET Tracer version 1.13.0 adds support for Alpine and other Musl-based distributions.

For Debian or Ubuntu, download and install the Debian package:

curl -LO https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>/datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb
sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb

For CentOS or Fedora, download and install the RPM package:

curl -LO https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>/datadog-dotnet-apm-<TRACER_VERSION>-1.x86_64.rpm
sudo rpm -Uvh datadog-dotnet-apm-<TRACER_VERSION>-1.x86_64.rpm

For Alpine or other Musl-based distributions, download the tar archive with the musl-linked binary:

sudo mkdir -p /opt/datadog
curl -L https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>/datadog-dotnet-apm-<TRACER_VERSION>-musl.tar.gz \
| sudo tar xzf - -C /opt/datadog

For other distributions, download the tar archive with the glibc-linked binary:

sudo mkdir -p /opt/datadog
curl -L https://github.com/DataDog/dd-trace-dotnet/releases/download/v<TRACER_VERSION>/datadog-dotnet-apm-<TRACER_VERSION>.tar.gz \
| sudo tar xzf - -C /opt/datadog

If your application runs in IIS, skip the rest of this section.

For Windows applications not running in IIS, set these two environment variables before starting your application to enable automatic instrumentation:

Note: The .NET runtime tries to load a profiler into any .NET process that is started with these environment variables set. You should limit instrumentation only to the applications that need to be traced. We do not recommend setting these environment variables globally as this causes all .NET processes on the host to load the profiler.

Windows Services

To automatically instrument a Windows Service, set the environment variables for that Service in the Windows Registry. Create a multi-string value called Environment in the HKLM\System\CurrentControlSet\Services\<SERVICE NAME> key. Then set the key’s data to the values in the table:

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

This can be done either through the Registry Editor as in the image below, or through a PowerShell snippet:

[String[]] $v = @("CORECLR_ENABLE_PROFILING=1", "CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}")
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<NAME> -Name Environment -Value $v

Console Apps

Set the environment variables from a batch file before starting your application:

rem Set environment variables
SET CORECLR_ENABLE_PROFILING=1
SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

rem Start application
dotnet.exe example.dll

1. Set apm_non_local_traffic: true in 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. After having instrumented your application, the tracing client sends traces to localhost:8126 by default. If this is not the correct host and port change it by setting the below env variables:

DD_AGENT_HOST and DD_TRACE_AGENT_PORT.

4. On Linux, the following environment variables are required to enable automatic instrumentation:

Note: You must change the paths above if you install the .NET Tracer into a non-default path.

For example, to set the environment variables them 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_INTEGRATIONS=/opt/datadog/integrations.json
export DD_DOTNET_TRACER_HOME=/opt/datadog

# Start your application
dotnet example.dll

To set the environment variables on a Linux Docker container, use ENV:

# 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_INTEGRATIONS=/opt/datadog/integrations.json
ENV DD_DOTNET_TRACER_HOME=/opt/datadog

# 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.

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_INTEGRATIONS=/opt/datadog/integrations.json
DD_DOTNET_TRACER_HOME=/opt/datadog
# any other environment variable used by the application

In the service configuration file, reference this as an EnvironmentFile in the service block:

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

After setting these variables, restart the .NET service for the environment variables 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 ran via systemctl. To confirm these variables have been set, use systemctl show-environment. Before using this approach, see the note below about this instrumenting all .NET processes.

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_INTEGRATIONS=/opt/datadog/integrations.json
systemctl set-environment DD_DOTNET_TRACER_HOME=/opt/datadog

Once this is set, verify that the environment variables were set with systemctl show-environment.

To configure the Tracer using environment variables, set the variables before launching the instrumented application.

For example, on Windows:

rem Set environment variables
SET DD_TRACE_AGENT_URL=http://localhost:8126
SET DD_ENV=prod
SET DD_SERVICE=MyService
SET DD_VERSION=abc123

rem Launch application
example.exe

Note: To set environment variables for a Windows Service, use the multi-string key HKLM\System\CurrentControlSet\Services\{service name}\Environment in the Windows Registry.

On Linux:

# Set environment variables
export DD_TRACE_AGENT_URL=http://localhost:8126
export DD_ENV=prod
export DD_SERVICE=MyService
export DD_VERSION=abc123

# Launch application
dotnet example.dll

To configure the Tracer in application code, create a TracerSettings from the default configuration sources. Set properties on this TracerSettings instance before passing it to a Tracer constructor. For example:

using Datadog.Trace;

// read default configuration sources (env vars, web.config, datadog.json)
var settings = TracerSettings.FromDefaultSources();

// change some settings
settings.Environment = "prod";
settings.ServiceName = "MyService";
settings.ServiceVersion = "abc123";
settings.AgentUri = new Uri("http://localhost:8126/");

// disable the AdoNet integration
settings.Integrations["AdoNet"].Enabled = false;

// create a new Tracer using these settings
var tracer = new Tracer(settings);

// set the global tracer
Tracer.Instance = tracer;

Note: Settings must be set on TracerSettings before creating the Tracer. Changes made to TracerSettings properies after the Tracer is created are ignored.

To configure the Tracer using a JSON file, create datadog.json in the instrumented application’s directory. The root JSON object must be a hash with a key/value pair for each setting. For example:

{
  "DD_TRACE_AGENT_URL": "http://localhost:8126",
  "DD_ENV": "prod",
  "DD_SERVICE": "MyService",
  "DD_VERSION": "abc123",
}