Tracing .NET Framework Applications

Tracing .NET Framework Applications

Compatibility requirements

The .NET Tracer supports automatic instrumentation on .NET Framework 4.5 and above. For a full list of supported libraries, visit the Compatibility Requirements page.

Installation and getting started

Automatic instrumentation

Note: If you are using both automatic and custom instrumentation, it is important to keep the package versions (for example, MSI and NuGet) in sync.

Follow these instructions to begin tracing .NET applications:

Applications hosted in IIS

To start tracing an application hosted in IIS:

  1. Install and configure the Windows Datadog Agent.

  2. Download the .NET Tracer MSI installer. Select the MSI installer for the architecture that matches the operating system (x64 or x86).

  3. Run the .NET Tracer MSI installer with administrator privileges.

  4. Stop, then start IIS using the following commands as an administrator:

    Note: You must use a stop and start command. This is not the same as a reset or restart command.
    net stop /y was
    net start w3svc
  5. Create application load.

  6. Visit APM Live Traces.

Applications not hosted in IIS

To enable automatic instrumentation on Windows applications not in IIS, you must set two environment variables before starting your application:

Note: The .NET runtime tries to load a profiler into any .NET process started with these environment variables set. You should limit instrumentation only to the applications that need to be traced. Don't set these environment variables globally because this causes all .NET processes on the host to load the profiler.
Windows services

To automatically instrument a Windows service, set the COR_ENABLE_PROFILING and COR_PROFILER environment variables:

  1. In the Windows Registry Editor, create a multi-string value named Environment in HKLM\System\CurrentControlSet\Services\<SERVICE NAME>

  2. Set the value data to:


Alternatively, you can set the environment variables by using the following PowerShell snippet:


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

To automatically instrument a console application, set the COR_ENABLE_PROFILING and COR_PROFILER environment variables from a batch file before starting your application:

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

rem Start application

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_enabled: true and listens for trace traffic at localhost:8126. For containerized environments, follow the in-app Quickstart instructions to enable trace collection within the Datadog Agent.

Ensure you set DD_SITE in the Datadog Agent to so that the Agent sends data to the right Datadog location.

Custom instrumentation

Note: If you are using both automatic and custom instrumentation, it is important to keep the package versions (for example, MSI and NuGet) in sync.

To use custom instrumentation in your .NET application:

  1. Add the Datadog.Trace NuGet package to your application.
  2. In your application code, access the global tracer through the Datadog.Trace.Tracer.Instance property to create new spans.

For additional details on custom instrumentation and custom tagging, see .NET Custom Instrumentation.


The .NET Tracer has configuration settings which you can set by any of these methods:

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

For example:

rem Set environment variables
SET DD_TRACE_AGENT_URL=http://localhost:8126

rem Launch application
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, as described above.

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

Note: Settings must be set on TracerSettings before creating the Tracer. Changes made to TracerSettings properties after the Tracer is created are ignored.
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/");

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

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

To configure the Tracer using an app.config or web.config file, use the <appSettings> section. For example:

    <add key="DD_TRACE_AGENT_URL" value="http://localhost:8126"/>
    <add key="DD_ENV" value="prod"/>
    <add key="DD_SERVICE" value="MyService"/>
    <add key="DD_VERSION" value="abc123"/>

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

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.

TracerSettings property: Environment
If specified, adds the env tag with the specified value to all generated spans. Added in version 1.17.0
TracerSettings property: ServiceName
If specified, sets the 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). Added in version 1.17.0
TracerSettings property: ServiceVersion
If specified, sets the version of the service. Added in version 1.17.0

Additional optional configuration

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

TracerSettings property: AgentUri
Sets the URL endpoint where traces are sent. Overrides DD_AGENT_HOST and DD_TRACE_AGENT_PORT if set.
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
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
TracerSettings property: LogsInjectionEnabled
Enables or disables automatic injection of correlation identifiers into application logs.
TracerSettings property: DebugEnabled
Enables or disables debug logging. Valid values are: true or false.
Default: false
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.
TracerSettings property: GlobalTags
If specified, adds all of the specified tags to all generated spans. Added in version 1.17.0.
Example: layer:api,team:intake
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.
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 configuration variables are available only when using automatic instrumentation:

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
Sets the directory for .NET Tracer logs.
Default: %ProgramData%\Datadog .NET Tracer\logs\
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.
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.
Sets status code ranges that will cause HTTP client spans to be marked as errors.
Default: 400-499
Sets status code ranges that will cause HTTP server spans to be marked as errors.
Default: 500-599
Enables .NET runtime metrics. Valid values are true or false. Added in version 1.23.0.
Default: false
TracerSettings property: AdoNetExcludedTypes
Sets a list of AdoNet types (for example, System.Data.SqlClient.SqlCommand) that will be excluded from automatic instrumentation.

Disable integration configuration

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

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 configuration variables are for features that are available for use but may change in future releases.

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.
Default: false
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

Further reading