Compatibility requirements
Supported .NET Framework runtimes
The .NET Tracer supports instrumentation on .NET Framework 4.6.1 and above.
For a full list of supported libraries and processor architectures (including older versions of .NET Framework), 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: APM). To ensure maximum visibility, run only one APM solution in your application environment.
Installation
- Install the tracer.
- Enable the tracer for your service.
- Configure the Datadog Agent for APM.
- 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 on a per-application basis so developers are able to manage the instrumentation through the application’s dependencies. To see machine-wide installation instructions, click the Windows 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.
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.Monitoring.Distribution
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.
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
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
Set the following required environment variables for automatic instrumentation to attach to your application:
COR_ENABLE_PROFILING=1
COR_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:
COR_ENABLE_PROFILING=1
COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
COR_PROFILER_PATH=<System-dependent path>
DD_DOTNET_TRACER_HOME=<APP_DIRECTORY>/datadog
The value for the <APP_DIRECTORY>
placeholder is the path to the directory containing the application’s .dll
files. The value for the COR_PROFILER_PATH
environment variable varies based on the system where the application is running:
Operating System and Process Architecture | COR_PROFILER_PATH Value |
---|
Windows x64 | <APP_DIRECTORY>\datadog\win-x64\Datadog.Trace.ClrProfiler.Native.dll |
Windows x86 | <APP_DIRECTORY>\datadog\win-x86\Datadog.Trace.ClrProfiler.Native.dll |
For standalone applications, manually restart the application.
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:
Set apm_non_local_traffic: true
in the apm_config
section of your main datadog.yaml
configuration file.
See the specific setup instructions to ensure that the Agent is configured to receive traces in a containerized environment:
- 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.
- To ensure the Agent sends data to the right Datadog location, set
DD_SITE
in the Datadog Agent to
.
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
You can set configuration settings in the .NET Tracer with any of the following methods:
To configure the tracer using environment variables, set the variables before launching the instrumented application. To learn how to set environment variables in different environments, see Configuring process environment variables.
To configure the Tracer in application code, create a TracerSettings
instance from the default configuration sources. Set properties on this TracerSettings
instance before calling Tracer.Configure()
. 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.Exporter.AgentUri = new Uri("http://localhost:8126/");
// configure the global Tracer settings
Tracer.Configure(settings);
To configure the Tracer using an app.config
or web.config
file, use the <appSettings>
section. For example:
<configuration>
<appSettings>
<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"/>
</appSettings>
</configuration>
To configure the Tracer using a JSON file, create datadog.json
in the instrumented application’s directory. The root JSON object must be an object 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, Exporter.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:
Exporter.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.
Your logger needs to have a source
that sets the trace_id
mapping correctly. The default source for .NET Applications, csharp
, does this automatically. For more information, see correlated logs in the Trace ID panel. DD_TRACE_SAMPLE_RATE
- TracerSettings property:
GlobalSamplingRate
Enables ingestion rate control. DD_TRACE_RATE_LIMIT
- TracerSettings property:
MaxTracesSubmittedPerSecond
The number of traces allowed to be submitted per second (deprecates DD_MAX_TRACES_PER_SECOND
).
Default: 100
when DD_TRACE_SAMPLE_RATE
is set. Otherwise, delegates rate limiting to the Datadog Agent.
DD_TRACE_GLOBAL_TAGS
- TracerSettings property:
GlobalTags
If specified, adds all of the specified tags to all generated spans.
DD_TRACE_DEBUG
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\
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. DD_TRACE_EXPAND_ROUTE_TEMPLATES_ENABLED
- Expands all route parameters in the application for ASP.NET/ASP.NET Core (except ID parameters)
This can be useful if you are using parameter names to differentiate between form values, or a slug, such as in GraphQL.
Default: false
Added in version 2.5.2 DD_TRACE_METHODS
- List of methods to trace. Accepts a semicolon (
;
) separated list where each entry has the format TypeName[MethodNames]
, where MethodNames
is either a comma (,
) separated list of method names or the *
wildcard. For generic types, replace the angled brackets and the type parameters’ names with a backtick (`
) followed by the number of generic type parameters. For example, Dictionary<TKey, TValue>
must be written as Dictionary`2
. For generic methods, you only need to specify the method name.
Example: Namespace1.Class1[Method1,GenericMethod];Namespace1.GenericTypeWithOneTypeVariable`1[ExecuteAsync];Namespace2.Class2[*]
Note: The wildcard method support ([*]
) selects all methods in a type except constructors, property getters and setters, Equals
, Finalize
, GetHashCode
, and ToString
.
Added in version 2.6.0.
Wildcard support [*]
added in version 2.7.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
Headers extraction and injection
The Datadog APM Tracer supports B3 and W3C (TraceParent) headers extraction and injection for distributed tracing.
You can configure injection and extraction styles for distributed headers.
The .NET Tracer supports the following styles:
- Datadog:
Datadog
- B3:
B3
- W3C:
W3C
- B3 Single Header:
B3SingleHeader
or B3 single header
You can use the following environment variables to configure injection and extraction styles:
DD_PROPAGATION_STYLE_INJECT=Datadog, B3, W3C
DD_PROPAGATION_STYLE_EXTRACT=Datadog, B3, W3C
The environment variable values are comma-separated lists of header styles enabled for injection or extraction. By default, only the Datadog
injection style is enabled.
If multiple extraction styles are enabled, the extraction attempt is completed in order of configured styles, and uses the first successful extracted value.
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.
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, 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
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:
COR_ENABLE_PROFILING=1
COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
[string[]] $v = @("COR_ENABLE_PROFILING=1", "COR_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 COR_ENABLE_PROFILING=1
SET COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
rem Start application
dotnet.exe example.dll
Further reading
Additional helpful documentation, links, and articles: