Tracing .NET Core Applications

Compatibility requirements

Supported .NET Core runtimes

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

For a full list of supported libraries and processor architectures, see Compatibility Requirements.

Installation and getting started

Installation

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

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.

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 traffic at localhost:8126.

For containerized, serverless, and cloud environments:

• Dropdown

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. After instrumenting 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 DD_AGENT_HOST and DD_TRACE_AGENT_PORT environment variables. For more information on how to set these variables, see Configuration.

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

To set up Datadog APM in AWS Lambda, see Tracing Serverless Functions.

To set up Datadog APM in Azure App Service, see Tracing Azure App Service Extension.

Tracing is available for a number of 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 are encountering setup issues.

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

You can set configuration settings in the .NET Tracer with any of the following methods:

using Datadog.Trace;
using Datadog.Trace.Configuration;

// 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/");

// configure the global Tracer settings
Tracer.Configure(settings);

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

Configuration settings

Using the methods described above, customize your tracing configuration with the following variables. Use the environment variable name (for example, DD_TRACE_AGENT_URL) when setting environment variables or configuration files. Use the TracerSettings property (for example, AgentUri) when changing settings in code.

Unified Service Tagging

To use Unified Service Tagging, configure the following settings for your services:

DD_ENV

TracerSettings property: Environment
If specified, adds the env tag with the specified value to all generated spans. Added in version 1.17.0.

DD_SERVICE

TracerSettings property: ServiceName
If specified, sets the service name. Otherwise, the .NET Tracer tries to determine service name automatically from application name (IIS application name, process entry assembly, or process name). Added in version 1.17.0.

DD_VERSION

TracerSettings property: ServiceVersion
If specified, sets the version of the service. Added in version 1.17.0.

Optional configuration

The following configuration variables are available for both automatic and custom instrumentation:

DD_TRACE_AGENT_URL

TracerSettings property: AgentUri
Sets the URL endpoint where traces are sent. Overrides DD_AGENT_HOST and DD_TRACE_AGENT_PORT if set.
Default: http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>

DD_AGENT_HOST

Sets 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: localhost

DD_TRACE_AGENT_PORT

Sets the port where traces are sent (the port where the Agent is listening for connections). Ignored if DD_TRACE_AGENT_URL is set.
Default: 8126

DD_LOGS_INJECTION

TracerSettings property: LogsInjectionEnabled
Enables or disables automatic injection of correlation identifiers into application logs.

DD_TRACE_SAMPLE_RATE

TracerSettings property: GlobalSamplingRate
Enables Tracing without Limits.

DD_MAX_TRACES_PER_SECOND

TracerSettings property: MaxTracesSubmittedPerSecond
The number of traces allowed to be submitted per second.

DD_TRACE_GLOBAL_TAGS

TracerSettings property: GlobalTags
If specified, adds all of the specified tags to all generated spans.

DD_TRACE_DEBUG

TracerSettings property: DebugEnabled
Enables or disables debug logging. Valid values are: true or false.
Default: false

DD_TRACE_HEADER_TAGS

TracerSettings property:HeaderTags
Accepts a map of case-insensitive header keys to tag names and automatically applies matching header values as tags on root spans. Also accepts entries without a specified tag name.
Example: CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name
Added in version 1.18.3. Response header support and entries without tag names added in version 1.26.0.

DD_TAGS

TracerSettings property: GlobalTags
If specified, adds all of the specified tags to all generated spans.
Example: layer:api, team:intake
Added in version 1.17.0.
Note that the delimiter is a comma and a whitespace: , .

DD_TRACE_LOG_DIRECTORY

Sets the directory for .NET Tracer logs.
Default: %ProgramData%\Datadog .NET Tracer\logs\ on Windows, /var/log/datadog/dotnet on Linux

DD_TRACE_LOGGING_RATE

Sets rate limiting for log messages. If set, unique log lines are written once per x seconds. For example, to log a given message once per 60 seconds, set to 60. Setting to 0 disables log rate limiting. Added in version 1.24.0. Disabled by default.

DD_TRACE_SERVICE_MAPPING

Rename services using configuration. Accepts a map of service name keys to rename, and the name to use instead, in the format [from-key]:[to-name].
Example: mysql:main-mysql-db, mongodb:offsite-mongodb-service
The from-key value is specific to the integration type, and should exclude the application name prefix. For example, to rename my-application-sql-server to main-db, use sql-server:main-db. Added in version 1.23.0

Automatic instrumentation optional configuration

The following configuration variables are available only when using automatic instrumentation:

DD_TRACE_ENABLED

TracerSettings property: 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 or false.
Default: true

DD_HTTP_CLIENT_ERROR_STATUSES

Sets status code ranges that will cause HTTP client spans to be marked as errors.
Default: 400-499

DD_HTTP_SERVER_ERROR_STATUSES

Sets status code ranges that will cause HTTP server spans to be marked as errors.
Default: 500-599

DD_RUNTIME_METRICS_ENABLED

Enables .NET runtime metrics. Valid values are true or false.
Default: false
Added in version 1.23.0.

Automatic instrumentation integration configuration

The following table lists configuration variables that are available only when using automatic instrumentation and can be set for each integration.

DD_DISABLED_INTEGRATIONS

TracerSettings property: 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.

DD_TRACE_<INTEGRATION_NAME>_ENABLED

TracerSettings property: Integrations[<INTEGRATION_NAME>].Enabled
Enables or disables a specific integration. Valid values are: true or false. Integration names are listed in the Integrations section.
Default: true

Experimental features

The following configuration variables are for features that are available for use but may change in future releases.

DD_TRACE_PARTIAL_FLUSH_ENABLED

Enables incrementally flushing large traces to the Datadog Agent, reducing the chance of rejection by the Agent. Use only when you have long-lived traces or traces with many spans. Valid values are true or false. Added in version 1.26.0, only compatible with the Datadog Agent 7.26.0+.
Default: false

Deprecated settings

DD_TRACE_LOG_PATH

Sets the path for the automatic instrumentation log file and determines the directory of all other .NET Tracer log files. Ignored if DD_TRACE_LOG_DIRECTORY is set.

DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED

Enables improved resource names for web spans when set to true. Uses route template information where available, adds an additional span for ASP.NET Core integrations, and enables additional tags. Added in version 1.26.0. Enabled by default in 2.0.0
Default: true

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

• Dropdown

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

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
SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

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

# 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

# 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
   # any other environment variable used by the application
   

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
   

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

Additional helpful documentation, links, and articles:

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 Examples of custom instrumentationGITHUB Source codeGITHUB Deploy ASP.NET Core applications to Azure App ServiceBLOG