.NET

Supported Versions

Instana supports monitoring and tracing of applications running on the .NET-Framework beginning with version 4.0. .NET Core is not yet supported.

HTTP
ASP.NET MVC
ASP.NET WebAPI
ASP.NET WebForms
ASP.NET Core
System.Net.Http.HttpClient
Databases
Microsoft SQL-Server (System.Data.SqlClient)
Oracle (ODP, Devart)
PostgreSQL (Devart, NpgSql)
Elasticsearch (NEST)
MongoDB
Redis
Memcached
Remoting
Windows Communication Foundation Services
Messaging
Microsoft Message Queue
RabbitMQ
Schedulers / Task-Management
Hangfire

Sensor Data Collection

Tracked Configuration Metrics
Name GC Activity
Version Memory Usage
Arguments Thread-locks
Contention

Health Signatures

  • Garbage Collection Activity

Tracing

This page describes how to setup .NET Tracing for your environment and how it works.

Prerequisites

Tracing for .NET uses several components to hook into CLR-processes and gather information. Since one of these components is a native component written using Visual C++, you will need the appropriate VC++ runtime on your target machine. Please make sure to install the runtime using the appropriate package matching your architecture from here: https://www.microsoft.com/en-us/download/developer-tools.aspx

Setting up Tracing for .NET

The tracing component setup is a mostly automatic function of the agent. However, there are is a manual step involved, which we describe in the following sections.

Enabling tracing for .NET

When the Instana agent starts on your machine running windows, it will install the tracing-extension for .NET. The extension is composed from several files which contain the actual tracing-components. Since Instana uses the Profiling API defined in the .NET framework, this involves COM-Libraries as well as managed assemblies. When tracing is enabled, the files will be registered appropriately, so that all applications can use them for tracing. To enable tracing of .NET applications, you have to change the agent’s configuration file, as tracing for .NET is currently disabled by default.

configuration.yaml with .NET-Tracing enabled

# CLR Tracing
com.instana.plugin.clr:
  tracing:
    enabled: true

Once you changed the configuration-file, a restart of the agent is required for the changes to take effect (the configuration-file is hot reloaded, but the extension InstanaPCP.exe needs to be restarted). When you restart the agent, InstanaPCP will log information about the process of trace-enablement on startup. This will look like this (log lines shortened):

configuration.yaml with .NET-Tracing enabled

INFO  | com.instana.agent - 1.1.326 | Writing location for instrumentation-advices to registry
INFO  | com.instana.agent - 1.1.326 | Setting up tracing-environment
INFO  | com.instana.agent - 1.1.326 | Registering native profiler for .NET
INFO  | com.instana.agent - 1.1.326 | Agent UUID received:ac:bc:32:ff:fe:90:7d:bb
INFO  | com.instana.agent - 1.1.326 | Registering System.Collections.Immutable.dll in GAC
INFO  | com.instana.agent - 1.1.326 | .NET Tracing is enabled
INFO  | com.instana.agent - 1.1.326 | Registering instrumentation-DLLs in GAC
INFO  | com.instana.agent - 1.1.326 | Registering Instana.ManagedTracing.dll in GAC
INFO  | com.instana.agent - 1.1.326 | Setting environment-variables for .NET tracing
INFO  | com.instana.agent - 1.1.326 | Registry-Key for WAS-Environment does not exist, will create now
INFO  | com.instana.agent - 1.1.326 | Setting environment for WAS
WARN  | com.instana.agent - 1.1.326 | You should consider restarting the service WAS in order to make it use the new profiler. Already running application will not use it until restarted.
INFO  | com.instana.agent - 1.1.326 | Registry-Key for W3SVC-Environment does not exist, will create now
INFO  | com.instana.agent - 1.1.326 | Setting environment for W3SVC
WARN  | com.instana.agent - 1.1.326 | You should consider restarting the service W3SVC in order to make it use the new profiler. Already running application will not use it until restarted.
INFO  | com.instana.agent - 1.1.326 | Setting memoryUsageExcessThreshold set to configured value of 100000000
INFO  | com.instana.agent - 1.1.326 | Self-Monitoring for Windows-Extensions has been started successfully
INFO  | com.instana.agent - 1.1.326 | Setting memoryUsageWarningThreshold set to configured value of 80000000
INFO  | com.instana.agent - 1.1.326 | Starting tracing-session
INFO  | com.instana.agent - 1.1.326 | Windows-Extension REST-Endpoint has been setup successfully at http://localhost:42657
INFO  | com.instana.agent - 1.1.326 | Registering Instana.ManagedTracing.Modules.dll in GAC
INFO  | com.instana.agent - 1.1.326 | Instana ETW-Reader setup and listening

The extension registers a native COM-DLL (profiler), along with 3 managed assemblies, which contain the actual instrumentation code or are required for the instrumentation to work (Instana.ManagedTracing.dll, Instana.ManagedTracing.Base.dll, System.Collections.Immutable.dll). After registering the components, the extension applies changes to the registry, so that any instances of W3SVC or WAS will attach the profiler the next time they are being started. This is why you will find a warning in the logs regarding restarting already running applications. Instana does not restart these services automatically, as we do not want to interrupt your services.

How Tracing Works

Once you enabled tracing by changing the configuration-file, trace-data will be collected for all applications that make use of the supported technologies. Since .NET-Tracing follows the same scheme as all the other tracing-packages, distributed traces in polyglot applications will automatically be collected and displayed in Instana’s UI.

When an application with tracing enabled starts up, you might find the startup-time to be increased in comparison to startup without tracing. This is due to the profiler attaching, inspecting the classes contained in the referenced assemblies, and then rejitting some methods’ code for instrumentation. After the instrumentation has been applied, the impact on the runtime performance of your applications is extremely low, as with any other tracing-package that Instana provides.

Disabling Tracing for .NET

When you want to stop tracing of .NET applications for whatever reason, you can simply do so by changing the configuration file back to its initial state, or by just setting the corresponding flag to “false.”

configuration.yaml with .NET-Tracing disabled

# CLR Tracing
com.instana.plugin.clr:
  tracing:
    enabled: false

After changing the config back, you will have to restart the agent for the changes to take effect.

Due to the nature of how the Profiling API works, disabling tracing in the agent will not remove / detach the profiler from processes that have been started with tracing enabled (i.e. your worker-processes). To make sure the profiler is not loaded into the application, you have to restart the host-process.

Enabling Tracing for Non-IIS Hosted Applications

Our tracing does not enable tracing for every .NET based applications on purpose, since this might produce undesired component behavior that are not in scope of your monitoring needs. While IIS and WAS get configured to attach the profiler automatically by setting the appropriate environment-variables, standalone-processes are not. You can enable tracing for these processes by providing the necessary environment-variables by either setting them on the user level (when you use specific technical users which run your applications), or by setting the environment-variables before starting the actual process.

To enable tracing for a specific process you have to provide the following environment-variables with their respective values:

Environment variables needed for tracing

SET COR_ENABLE_PROFILING=1
SET COR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}

You can put these settings into a batch or powershell-script which starts your processes after setting the env-vars.

Custom Tracing

Instana’s .NET Tracing SDK enables to your own custom tracing in situation where our automatic instrumentation does not apply (i.e., you are using components we are not automatically supporting).