Tracing .NET Core Applications
このページは日本語には対応しておりません。随時翻訳に取り組んでいます。翻訳に関してご質問やご意見ございましたら、お気軽にご連絡ください。
Compatibility requirements
Supported .NET Core runtimes
The .NET Tracer supports instrumentation on .NET Core 2.1, .NET Core 3.1, .NET 5, .NET 6, .NET 7, and .NET 8.
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
Note: Datadog's automatic instrumentation relies on the .NET CLR Profiling API. This API allows only one subscriber (for example, Datadog APM). To ensure maximum visibility, run only one APM solution in your application environment.
To instrument trimmed apps, reference the
Datadog.Trace.Trimming NuGet package in your project. Support for trimmed apps is in beta.
Installation
Before you begin, make sure you’ve already installed and configured the Agent.
- Install the tracer.
- Enable the tracer for your service.
- View your live data.
Install the tracer
After you install and configure your Datadog Agent, the next step is to add the tracing library directly in the application to instrument it. Read more about compatibility information.
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.
To install the .NET Tracer machine-wide:
Download the .NET Tracer MSI installer. Select the MSI installer for the architecture that matches the operating system (x64 or x86).
Run the .NET Tracer MSI installer with administrator privileges.
You can also script the MSI setup by running the following in PowerShell: Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-apm.msi'
To install the .NET Tracer 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 tracer log directory /var/log/datadog/dotnet with the appropriate permissions:
- 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
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 Tracer per-application:
- Add the
Datadog.Trace.Bundle NuGet package to your application.
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.
The .NET Tracer MSI installer adds all required environment variables. There are no environment variables you need to configure.
Note: You must set the
.NET CLR version for the application pool to
No Managed Code as recommended by
Microsoft.
To automatically instrument applications hosted in IIS, completely stop and start IIS by running the following commands as an administrator:
net stop /y was
net start w3svc
# Also, start any other services that were stopped when WAS was shut down.
Note: Always use the commands above to completely stop and restart IIS to enable the tracer. Avoid using the IIS Manager GUI application or iisreset.exe.
Services not in IIS
Starting v2.14.0, you don't need to set CORECLR_PROFILER if you installed the tracer using the MSI.
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}
For standalone applications and Windows services, manually restart the 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
For standalone applications, manually restart the application as you normally would.
View your live data
After enabling the .NET Tracer for your service:
Restart your service.
Create application load.
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:
Note: If you are using both automatic and custom instrumentation, you must keep the package versions (for example: MSI and NuGet) in sync.
To use custom instrumentation in your .NET application:
- Add the
Datadog.Trace NuGet package to your application. - In your application code, access the global tracer through the
Datadog.Trace.Tracer.Instance property to create new spans.
Note: If you are using both automatic and custom instrumentation, you must keep the package versions (for example, MSI and NuGet) in sync.
To use custom instrumentation in your .NET application:
- Add the
Datadog.Trace NuGet package to your application. - In your application code, access the global tracer through the
Datadog.Trace.Tracer.Instance property to create new spans.
To use custom instrumentation in your .NET application:
- In your application code, access the global tracer through the
Datadog.Trace.Tracer.Instance property to create new spans.
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
Starting v2.14.0, you don't need to set CORECLR_PROFILER if you installed the tracer using the MSI.
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:
- 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
- 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
If you are using Alpine Linux, set the CORECLR_PROFILER_PATH environment variable to a path for musl based distributions: linux-musl-x64/.
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.
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
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>
Restart the .NET service for the environment variable settings to take effect.
systemctl (all services)
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 to only the applications that need to be traced. Don't set these environment variables globally as this causes all .NET processes on the host to load the profiler.
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.
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
Verify that the environment variables were set by running systemctl show-environment.
Restart the .NET service for the environment variables to take effect.
Further reading
