.NET¶

To install the .NET Tracer machine-wide, perform the following steps:

1. Download the .NET Tracer MSI installer. Select the MSI installer for the architecture that matches your operating system (x64 or x86).
2. Run the .NET Tracer MSI installer with administrator privileges. You can also script the MSI installer by running the following command in PowerShell: Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-apm.msi'.

To install the .NET Tracer machine-wide, perform the following steps:

1. Download the .NET Tracer MSI installer. Select the MSI installer for the architecture that matches your operating system (x64 or x86).
2. Run the relevant installation package according to your operating system, and use appropriate permissions to create the directory /var/log/datadog/dotnet for .NET tracer logs:

   Debian or Ubuntu
   sudo dpkg -i ./datadog-dotnet-apm_<TRACER_VERSION>_amd64.deb && /opt/datadog/createLogPath.sh
   CentOS or Fedora
   sudo rpm -Uvh datadog-dotnet-apm<TRACER_VERSION>-1.x86_64.rpm && /opt/datadog/createLogPath.sh
   Alpine or other musl-based distributions
   sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-<TRACER_VERSION>-musl.tar.gz && sh /opt/datadog/createLogPath.sh
   Other distributions
   sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<TRACER_VERSION>-tar.gz && /opt/datadog/createLogPath.sh

To install the .NET Tracer in a slim or distroless Docker image (without a shell), use commands like the following in your Dockerfile:

• Use ADD to place the tracer files into the container.
• Use COPY --chown=$APP_UID with an empty folder as the source to create the log directory.

For example, in the Dockerfile you could write:

ADD datadog-dotnet-apm-<TRACER_VERSION>.tar.gz /opt/datadog/
COPY --chown=$APP_UID --from=<OTHER_STAGE> /empty/ /var/log/datadog/dotnet/

Add the .NET Tracer to your application

1. Add Datadog.Trace.Bundle to your application using the NuGet package.

Internet Information Services (IIS):

1. The .NET Tracer MSI installer adds all required environment variables. Additional environment variables need to be configured here.
2. To automatically instrument applications hosted in IIS, run the following commands as an administrator to completely stop and start IIS:

   net stop /y was
   net start w3svc
   

Non-IIS Applications

1. Set the following required environment variables for automatic instrumentation to attach to the application:

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

2. Restart the application.

1. Add the necessary environment variables for automatic instrumentation of the 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  
   

2. Restart the application.

Add custom probes for .NET applications:

1. In your application code, access the global tracer via the Datadog.Trace.Tracer.Instance property to create new spans.

After installing the MSI, IIS sites are automatically instrumented without additional configuration. To set additional environment variables inherited by all IIS sites, follow these steps:

1. Open the Registry Editor, find the multi-string value named Environment in the HKLM\System\CurrentControlSet\Services\WAS registry key, and add environment variables, one per line. For example, to add log 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 command to restart IIS:

   net stop /y was
   net start w3svc
   # Additionally, any other services that were stopped when WAS was shut down have been started.
   

   

To automatically instrument a console application, set the environment variables from a batch file before starting the 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

Set the required environment variables from bash before starting the 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

Configure environment variables in a 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"]

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

1. Create a file named environment.env containing:

   # Set environment variables
   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 it as an EnvironmentFile in the service block:

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

3. Restart the .NET service.

When running a .NET application as a service using systemctl, 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. Run systemctl show environment to verify that the environment variables were set successfully.

3. Restart the application service.