Tracing .NET Core Applications
Rapport de recherche Datadog : Bilan sur l'adoption de l'informatique sans serveur Rapport : Bilan sur l'adoption de l'informatique sans serveur

Tracing .NET Core Applications

Cette page n'est pas encore disponible en français, sa traduction est en cours.
Si vous avez des questions ou des retours sur notre projet de traduction actuel, n'hésitez pas à nous contacter.

Getting Started

If you already have a Datadog account you can find step-by-step instructions in our in-app guides for host-based and container-based set ups.

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.

Note: The .NET Tracer supports all .NET-based languages (C#, F#, Visual Basic, etc).

Automatic Instrumentation

Automatic instrumentation can collect performance data about your application with zero code changes and minimal configuration. The .NET Tracer automatically instruments all supported libraries out of the box.

Automatic instrumentation captures:

  • Execution time of instrumented calls
  • Relevant trace data, such as URL and status response codes for web requests or SQL queries for database access
  • Unhandled exceptions, including stacktraces if available
  • A total count of traces (e.g. web requests) flowing through the system

The .NET Tracer supports automatic instrumentation on .NET Core 2.1, 3.0, and 3.1. It also supports .NET Framework.

Note: The .NET Tracer works on .NET Core 2.0, 2.2, and 3.0, but these versions reached their end of life and are no longer supported by Microsoft. See Microsoft’s support policy for more details. We recommend using the latest patch version of .NET Core 2.1 or 3.1.

Note: Older versions of .NET Core on Linux/x64 have JIT compiler bugs that can cause applications to throw exceptions when using automatic instrumentation. If your application is running on .NET Core 2.0, 2.1.0-2.1.11, or 2.2.0-2.2.5, we strongly recommend you update your .NET Core runtime. If you cannot update, you may need to set the environment variable DD_CLR_DISABLE_OPTIMIZATIONS=true to work around the issue. See DataDog/dd-trace-dotnet/issues/302 for more details.

Installation

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

Required Environment Variables

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:

NameValue
CORECLR_ENABLE_PROFILING1
CORECLR_PROFILER{846F5F1C-F9AE-4B07-969E-05C26BC060D8}

For example, to 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

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, the following environment variables are required to enable automatic instrumentation:

NameValue
CORECLR_ENABLE_PROFILING1
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

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"]

Note: The .NET runtime tries to load a profiler into any .NET process that is started with these environment variables are 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.

Integrations

The .NET Tracer can instrument the following libraries automatically:

Framework or libraryNuGet packageIntegration Name
ASP.NET CoreMicrosoft.AspNetCore
Microsoft.AspNetCore.App
2.0+ and 3.0+
AspNetCore
ADO.NETSystem.Data.Common
System.Data.SqlClient 4.0+
AdoNet
HttpClient / HttpClientHandlerSystem.Net.Http 4.0+HttpMessageHandler
WebClient / WebRequestSystem.Net.Requests 4.0+WebRequest
Redis (StackExchange client)StackExchange.Redis 1.0.187+StackExchangeRedis
Redis (ServiceStack client)ServiceStack.Redis 4.0.48+ServiceStackRedis
ElasticsearchElasticsearch.Net 5.3.0+ElasticsearchNet
MongoDBMongoDB.Driver.Core 2.1.0+MongoDb
PostgreSQLNpgsql 4.0+AdoNet

Note: The ADO.NET integration instruments calls made through the DbCommand abstract class or the IDbCommand interface, regardless of the underlying implementation. It also instruments direct calls to SqlCommand.

Don’t see your desired frameworks? Datadog is continually adding additional support. Check with the Datadog team for help.

Manual Instrumentation

To manually instrument your code, add the Datadog.Trace NuGet package to your application. In your code, access the global tracer through the Datadog.Trace.Tracer.Instance property to create new spans.

For more details on manual instrumentation and custom tagging, see Manual instrumentation documentation.

Manual instrumentation is supported on .NET Framework 4.5 and above on Windows and on .NET Core 2.1, 3.0, and 3.1 on Windows and Linux.

Configuration

There are multiple ways to configure the .NET Tracer:

  • in .NET code
  • setting environment variables
  • creating a datadog.json file

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.ServiceName = "MyService";
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 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_SERVICE_NAME=MyService
SET DD_ADONET_ENABLED=false

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_SERVICE_NAME=MyService
export DD_ADONET_ENABLED=false

# Launch application
dotnet example.dll

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_SERVICE_NAME": "MyService",
  "DD_ADONET_ENABLED": "false"
}

Configuration Variables

The following tables list the supported configuration variables. Use the first name (e.g. DD_TRACE_AGENT_URL) when setting environment variables or configuration files. The second name, if present (e.g. AgentUri), indicates the name the TracerSettings propery to use when changing settings in the code.

The first table below lists configuration variables that are available for both automatic and manual instrumentation.

Setting NameDescription
DD_TRACE_AGENT_URL

AgentUri
Sets the URL endpoint where traces are sent. Overrides DD_AGENT_HOST and DD_TRACE_AGENT_PORT if set. Default value is http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>.
DD_AGENT_HOSTSets the host where traces are sent (the host running the Agent). Can be a hostname or an IP address. Ignored if DD_TRACE_AGENT_URL is set. Default is value localhost.
DD_TRACE_AGENT_PORTSets the port where traces are sent (the port where the Agent is listening for connections). Ignored if DD_TRACE_AGENT_URL is set. Default value is 8126.
DD_ENV

Environment
If specified, adds the env tag with the specified value to all generated spans. See Agent configuration for more details about the env tag.
DD_SERVICE_NAME

ServiceName
If specified, sets the default service name. Otherwise, the .NET Tracer tries to determine service name automatically from application name (e.g. IIS application name, process entry assembly, or process name).
DD_LOGS_INJECTION

LogsInjectionEnabled
Enables or disables automatic injection of correlation identifiers into application logs.
DD_TRACE_GLOBAL_TAGS

GlobalTags
If specified, adds all of the specified tags to all generated spans.
DD_TRACE_DEBUGEnables or disables debug logging. Valid values are: true or false (default).

The following table lists configuration variables that are available only when using automatic instrumentation.

Setting NameDescription
DD_TRACE_ENABLED

TraceEnabled
Enables or disables all automatic instrumentation. Setting the environment variable to false completely disables the CLR profiler. For other configuration methods, the CLR profiler is still loaded, but traces will not be generated. Valid values are: true (default) or false.
DD_TRACE_DEBUGEnables or disables debug logs in the Tracer. Valid values are: true or false (default). Setting this as an environment variable also enabled debug logs in the CLR Profiler.
DD_TRACE_LOG_PATHSets the path for the CLR profiler’s log file.

Windows default: %ProgramData%\Datadog .NET Tracer\logs\dotnet-profiler.log

Linux default: /var/log/datadog/dotnet/dotnet-profiler.log
DD_DISABLED_INTEGRATIONS

DisabledIntegrationNames
Sets a list of integrations to disable. All other integrations remain enabled. If not set, all integrations are enabled. Supports multiple values separated with semicolons. Valid values are the integration names listed in the Integrations section above.
DD_TRACE_ANALYTICS_ENABLED

AnalyticsEnabled
Shorthand that enables default App Analytics settings for web framework integrations. Valid values are: true or false (default).

The following table lists configuration variables that are available only when using automatic instrumentation and can be set for each integration. Use the first name (e.g. DD_<INTEGRATION>_ENABLED) when setting environment variables or configuration files. The second name (e.g. Enabled), indicates the name the IntegrationSettings propery to use when changing settings in the code. Access these properties through the TracerSettings.Integrations[] indexer. Integration names are listed in the Integrations section above.

Setting NameDescription
DD_<INTEGRATION>_ENABLED

Enabled
Enables or disables a specific integration. Valid values are: true (default) or false.
DD_<INTEGRATION>_ANALYTICS_ENABLED

AnalyticsEnabled
Enables or disable App Analytics for a specific integration. Valid values are: true or false (default).
DD_<INTEGRATION>_ANALYTICS_SAMPLE_RATE

AnalyticsSampleRate
Sets the App Analytics sampling rate for a specific integration. A floating number between 0.0 and 1.0 (default).

Further Reading