The .NET Tracer supports instrumentation on:
For a full list of supported libraries, visit the Compatibility Requirements page.
Follow the Quickstart instructions in the Datadog app for the best experience, including:
service, env and version tags.Otherwise, to begin tracing your applications:
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.
Enable instrumentation in your service by setting the required environment variables. See the section Instrumenting your service, below.
Create application load.
Visit APM Live Traces.
Download and install the .NET Tracer into the application environment:
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
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
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
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
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.
Enable instrumentation in your service by setting the required environment variables. See the section Instrumenting your service, below.
Create application load.
Visit APM Live Traces.
To automatically instrument applications hosted in IIS, completely stop IIS and then start it by running the following commands as an administrator:
net stop /y was
net start w3svc
To automatically instrument a Windows service, set the CORECLR_ENABLE_PROFILING and CORECLR_PROFILER environment variables for the service in the Windows Registry.
Using the Registry Editor:
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}
Using PowerShell:
[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
To automatically instrument a console application, set the CORECLR_ENABLE_PROFILING and CORECLR_PROFILER 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 enable automatic instrumentation, you must set two environment variables before starting your application:
| Name | Value |
|---|---|
CORECLR_ENABLE_PROFILING | 1 |
CORECLR_PROFILER | {846F5F1C-F9AE-4B07-969E-05C26BC060D8} |
The following environment variables are required to enable automatic instrumentation:
/opt/datadog path, ensure the paths are changed to match.| Name | Value |
|---|---|
CORECLR_ENABLE_PROFILING | 1 |
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 |
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_INTEGRATIONS=/opt/datadog/integrations.json
export DD_DOTNET_TRACER_HOME=/opt/datadog
# Start your application
dotnet example.dll
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_INTEGRATIONS=/opt/datadog/integrations.json
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.
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_INTEGRATIONS=/opt/datadog/integrations.json
DD_DOTNET_TRACER_HOME=/opt/datadog
# any other environment variable used by the application
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)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_INTEGRATIONS=/opt/datadog/integrations.json
systemctl set-environment DD_DOTNET_TRACER_HOME=/opt/datadog
Verify that the environment variables were set by running systemctl show-environment.
Restart the .NET service for the environment variables to take effect.
To use custom instrumentation in your .NET application:
Datadog.Trace NuGet package to your application.Datadog.Trace.Tracer.Instance property to create new spans.For more details on custom instrumentation and custom tagging, see .NET Custom Instrumentation documentation.
Install the Datadog Agent and configure it to receive traces from your now 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 links below to enable trace collection in the Datadog Agent.
If the Agent is running on a different host or container, set apm_non_local_traffic: true in 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:
While it is 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 these environment variables:
DD_AGENT_HOSTDD_TRACE_AGENT_PORTTo set up Datadog APM in AWS Lambda, see the Tracing Serverless Functions documentation.
To set up Datadog APM in Azure App Service, see the Tracing Azure App Services Extension documentation.
Tracing is available for a number of other environments, such as Heroku, Cloud Foundry, and AWS Elastic Beanstalk.
For other environments, please refer to the Integrations documentation for that environment and contact support if you are encountering any setup issues.
The .NET Tracer has configuration settings that can be set by any of these methods:
datadog.json file.To configure the tracer using environment variables, set the variables before launching the instrumented 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.
rem Set environment variables
SET DD_TRACE_AGENT_URL=http://localhost:8126
SET DD_ENV=prod
SET DD_SERVICE=MyService
SET DD_VERSION=abc123
rem Launch application
example.exe
# Set environment variables
export DD_TRACE_AGENT_URL=http://localhost:8126
export DD_ENV=prod
export DD_SERVICE=MyService
export DD_VERSION=abc123
# Launch application
dotnet example.dll
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:
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/");
// 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;
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",
}
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.
To use Unified Service Tagging, configure the following settings for your services:
DD_ENVEnvironmentenv tag with the specified value to all generated spans. Added in version 1.17.0.DD_SERVICEServiceNameDD_VERSIONServiceVersionThe following table below lists configuration variables that are available for both automatic and custom instrumentation.
DD_TRACE_AGENT_URLAgentUriDD_AGENT_HOST and DD_TRACE_AGENT_PORT if set.http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>DD_AGENT_HOSTDD_TRACE_AGENT_URL is set.localhostDD_TRACE_AGENT_PORTDD_TRACE_AGENT_URL is set.8126DD_LOGS_INJECTIONLogsInjectionEnabledDD_TRACE_GLOBAL_TAGSGlobalTagsDD_TRACE_DEBUGDebugEnabledtrue or falsefalseDD_TRACE_HEADER_TAGSCASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-NameDD_TRACE_LOG_DIRECTORY%ProgramData%\Datadog .NET Tracer\logs\DD_TRACE_LOG_PATHDD_TRACE_LOG_DIRECTORY is set.DD_TRACE_LOGGING_RATEx 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[from-key]:[to-name].mysql:main-mysql-db, mongodb:offsite-mongodb-servicefrom-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.0DD_TAGSGlobalTagslayer:api,team:intakeThe following configuriation variables are available only when using automatic instrumentation.
DD_TRACE_ENABLEDTraceEnabledfalse 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.trueDD_DISABLED_INTEGRATIONSDisabledIntegrationNamesDD_HTTP_CLIENT_ERROR_STATUSES400-499DD_HTTP_SERVER_ERROR_STATUSES500-599DD_RUNTIME_METRICS_ENABLEDtrue or false.falseDD_TRACE_ADONET_EXCLUDED_TYPESAdoNetExcludedTypesAdoNet types (for example, System.Data.SqlClient.SqlCommand) that will be excluded from automatic instrumentation.DD_TRACE_<INTEGRATION_NAME>_ENABLEDIntegrations[<INTEGRATION_NAME>].Enabledtrue or false. Integration names are listed in the Integrations section.trueThe following configuration variables are for features that are available for use but may change in future releases.
DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLEDtrue. 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.falseDD_TRACE_PARTIAL_FLUSH_ENABLEDtrue or false. Added in version 1.26.0, only compatible with the Datadog Agent 7.26.0+.falseAdditional helpful documentation, links, and articles:
