Skip to main content

Profiler chaining for the .NET agent

You can use profiler chaining to run the .NET agent alongside another .NET APM profiler.

The Contrast .NET agent is tested and proven to be compatible with the following profiling tools, given the combination of runtime, deployment type, and OS:

Profiling tool

Versions tested

.NET Core runtime

.NET Framework runtime (?)

Third-party profiler deployment type

OS

AppDynamics

.Net Core: 21.8.1

.NET Framework: 4.5.18.1

6.0.

Installed, Nuget Package

Windows

Dynatrace One Agent

1.253.245

6.0

Installed

Windows, Linux

New Relic

8.23.107

6.0

NuGet Package

Windows, Linux

Riverbed SteelCentral Aternity APM

12.9.0

6.0

Installed

Windows

Datadog

2.35.0

6.0

Installed, NuGet Package

Windows, Linux

Note

The agent is likely compatible with other profiling tools if those tools follow the conventions of the CoreCLR Profiling API and do not make assumptions about the profiling environment.

Chaining is enabled by default. To disable it, set agent.dotnet.enable_chaining to false. For example:

agent:
   dotnet:
     enable_chaining: false

Windows and IIS automatic steps

When using the .NET installer for IIS, the installer configures chaining automatically for all hosted .NET applications.

  1. Install the third-party agent first (recommended), then the Contrast .NET agent.

    If you install the Contrast .NET Framework agent before the third-party agent, you need to restart the Contrast.NET Main Service under Windows Services. <NOTE TO REVIEWERS: DOES THIS APPLY TO .NET FRAMEWORK ONLY OR BOTH?>

  2. Restart the IIS workers (by default, the agent installer does this automatically). On restart, the Contrast .NET agent automatically detects the presence of other profiling tools registered with IIS and configures the environment to load both the Contrast .NET agent profiler and the third-party profiler.

Linux automatic steps

Under Linux, configure automatic chaining by setting the LD_PRELOAD environment variable:

LD_PRELOAD=<path to the extracted Contrast files>/runtimes/linux-x64/native/ContrastChainLoader.so

For example, if the Contrast agent was extracted to /contrast, then the following would setup chaining automatically.

LD_PRELOAD=/contrast/runtimes/linux-x64/native/ContrastChainLoader.so dotnet ./HelloWorld

Some APM profilers already set LD_PRELOAD (e.g. Dynatrace). In this case, ensure the Contrast module is loaded first - separate LD_PRELOAD are delimited by colons :. For example:

LD_PRELOAD=/contrast/runtimes/linux-x64/native/ContrastChainLoader.so:/<path to Dynatrace>/liboneagentproc.so dotnet ./HelloWorld

Note

When running under Kubernetes, the Contrast Agent Operator will automatically setup chaining and is the preferred route to add agents to existing Kubernete workloads.

Manual steps

Chaining may need to be be manually setup, for example, in the following environments:

  • Hosted outside of IIS.

  • Environments that use the third-party agent's Nuget package (rather than the installed agent).

Note

Chaining with the Dynatrace agent is only supported using the automatic options.

  1. Replace the CLR environment variables for the profiling tool with CONTRAST_CCC_CORECLR versions. Any of these names should be transformed:

    • .NET Core

      Change this:

      To this:

      CORECLR_PROFILER

      CONTRAST_CCC_CORECLR_PROFILER

      CORECLR_PROFILER_PATH

      CONTRAST_CCC_CORECLR_PROFILER_PATH

      CORECLR_PROFILER_PATH_32

      CONTRAST_CCC_CORECLR_PROFILER_PATH_32

      CORECLR_PROFILER_PATH_64

      CONTRAST_CCC_CORECLR_PROFILER_PATH_64

    • .NET Framework

      Change this:

      To this:

      COR_PROFILER

      CONTRAST_CCC_COR_PROFILER

      COR_PROFILER_PATH

      CONTRAST_CCC_COR_PROFILER_PATH

      COR_PROFILER_PATH_32

      CONTRAST_CCC_COR_PROFILER_PATH_32

      COR_PROFILER_PATH_64

      CONTRAST_CCC_COR_PROFILER_PATH_64

  2. Add the agent manually.

AppInsights in Azure App Service

As of version 20.9.3, the Contrast .NET Framework Site Extension now supports compatibility with Application Insights (using the CLR Instrumentation Engine (CIE)).

There is no further action required to use AppInsights with the Contrast .NET Framework Site Extension. The .NET Framework agent's profiler will be loaded by the CIE if it is registered as the profiling tool in the Azure AppService instance (for example because AppInsights is enabled).

In this section: