Tracing .NET Framework Applications

Cette page n'est pas encore disponible en français, sa traduction est en cours.
Si vous avez des questions ou des retours sur notre projet de traduction actuel, n'hésitez pas à nous contacter.

Compatibility requirements

Supported .NET Framework runtimes

The .NET Tracer supports instrumentation on .NET Framework >= 4.6.1.

For a full list of Datadog’s .NET Framework library and processor architecture support (including legacy and maintenance versions), see Compatibility Requirements.

Installation and getting started

To set up Datadog APM in AWS Lambda, see Tracing Serverless Functions, in Azure App Service, see Tracing Azure App Service.
Note: Datadog's automatic instrumentation relies on the .NET CLR Profiling API. This API allows only one subscriber (for example, Datadog APM). To ensure maximum visibility, run only one APM solution in your application environment.

Installation

Before you begin, make sure you’ve already installed and configured the Agent.

  1. Install the tracer.
  2. Enable the tracer for your service.
  3. View your live data.

Install the tracer

After you install and configure your Datadog Agent, the next step is to add the tracing library directly in the application to instrument it. Read more about compatibility information.

Install the Datadog .NET Tracer machine-wide so that all services on the machine are instrumented or on a per-application basis, so developers can 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:

    1. Download the .NET Tracer MSI installer. Use the x64 MSI installer if you are running 64-bit Windows; this can instrument both 64-bit and 32-bit applications. Only choose the x86 installer if you are running 32-bit Windows. Starting with v3.0.0, only the x64 installer is provided, as we do not support 32-bit operating systems.

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

    You can also script the MSI setup by running the following in PowerShell: Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-apm.msi'

    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:

    1. Add the Datadog.Trace.Bundle 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.

      Internet Information Services (IIS)

      1. The .NET Tracer MSI installer adds all required environment variables. There are no environment variables you need to configure.

      2. 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
# Also, start any other services that were stopped when WAS was shut down.
        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

      Starting v2.14.0, you don't need to set COR_PROFILER if you installed the tracer using the MSI.

      1. 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}

      2. For standalone applications and Windows services, manually restart the application.

      Follow the instructions in the package readme, also available in dd-trace-dotnet repository. Docker examples are also available in the repository.

      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

      If needed, configure the tracing library to send application performance telemetry data, including setting up Unified Service Tagging. Read Library Configuration for details.

      Custom instrumentation

      Custom instrumentation depends on your automatic instrumentation and includes additional steps depending on the method:

        Note: Starting with v3.0.0, custom instrumentation requires you also use automatic instrumentation. You should aim to keep both automatic and custom instrumentation package versions (for example: MSI and NuGet) in sync, and ensure you don't mix major versions of packages.

        To use custom instrumentation in your .NET application:

        1. Instrument your application using automatic instrumentation.
        2. Add the Datadog.Trace NuGet package to your application.
        3. 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:

        1. 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

        Starting v2.14.0, you don't need to set COR_PROFILER if you installed the tracer using the MSI.

        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}
          Using the Registry Editor to create environment variables for a Windows service
          [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

          IIS

          After installing the MSI, no additional configuration is needed to automatically instrument your IIS sites. To set additional environment variables that are inherited by all IIS sites, perform the following steps:

          1. Open the Registry Editor, find the multi-string value called Environment in the HKLM\System\CurrentControlSet\Services\WAS key, and add the environment variables, one per line. For example, to add logs injection and runtime metrics, add the following lines to the value data:
            DD_LOGS_INJECTION=true
DD_RUNTIME_METRICS_ENABLED=true
          2. Run the following commands to restart IIS:
            net stop /y was
net start w3svc
# Also, start any other services that were stopped when WAS was shut down.
          Using the Registry Editor to create environment variables for all IIS sites

          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
rem Unless v2.14.0+ and you installed the tracer with the MSI
SET COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

rem Set additional Datadog environment variables
SET DD_LOGS_INJECTION=true
SET DD_RUNTIME_METRICS_ENABLED=true

rem Start application
dotnet.exe example.dll

          Further reading

          Documentation, liens et articles supplémentaires utiles:

          Connect .NET application logs to tracesDOCUMENTATION more more Runtime metricsDOCUMENTATION more more Microsoft Azure App Service extensionDOCUMENTATION more more Explore your services, resources, and tracesDOCUMENTATION more more .NET monitoring with Datadog APM and distributed tracingBLOG more more Monitor containerized ASP.NET Core applicationsBLOG more more Monitor containerized ASP.NET Core applications on AWS FargateBLOG more more Optimize your .NET application performance with the Datadog Continuous ProfilerBLOG more more Examples of custom instrumentationSOURCE CODE more more Source codeSOURCE CODE more more