Tracing .NET Framework Applications

Getting Started

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 Framework 4.5 and above. It also supports .NET Core.

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

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:

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

To set environment variables for a Windows Service, use the multi-string key HKLM\System\CurrentControlSet\Services\{service name}\Environment in the Windows Registry.

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:

Update: Starting with .NET Tracer version 1.12.0, the ASP.NET integration is enabled automatically. The NuGet packages Datadog.Trace.AspNet or Datadog.Trace.ClrProfiler.Managed are no longer required. Remove them from your application when you update the .NET Tracer.

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
• editing the application’s app.config/web.config file (.NET Framework only)
• creating a datadog.json file

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;

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

<configuration>
  <appSettings>
    <add key="DD_TRACE_AGENT_URL" value="http://localhost:8126"/>
    <add key="DD_SERVICE_NAME" value="MyService"/>
    <add key="DD_ADONET_ENABLED" value="false"/>
  </appSettings>
</configuration>

{
    "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.

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

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.

Further Reading

お役に立つドキュメント、リンクや記事:

Source codeGITHUB .NET monitoring with Datadog APM and distributed tracingBLOG Explore your services, resources and tracesDOCUMENTATION Advanced UsageADVANCED USAGE