.NET

Support for .NET Core

This page is about our support for .NET Full Framework based applications. If you are looking for support on .NET Core, please follow this link.

Supported Versions

Instana supports monitoring of applications running on the .NET-Framework beginning with version 4.0.

Runtime Support status
.NET Framework 4.0 and above GA
.NET Core Experimental

Supported Libraries & Frameworks for tracing

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

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.

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. The sensor and tracing-extensions are enabled by default now. However, if you wish to disable tracing, you can change the following portion of your agent’s cofiguration-file.

configuration.yaml with .NET-Tracing enabled

# CLR Tracing
com.instana.plugin.clr:
  tracing:
    enabled: false # default is 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).

Custom Performance Counters

We also support monitoring of Custom Performance Counters. To enable them, make sure to enable the plugin in configuration.yaml file like this:

com.instana.plugin.perfcounters:
  enabled: true

Note that this plugin is disabled by default.

Performance counters are defined with 4 different values. They are grouped by category, they have a name, and they can be bounded to a specific instance, or they can be host-wide. To uniquely describe a counter, often we use a syntax like this:

[host]\[category]([instance])\[counter name]

instance can in some cases be optional - it depends on the counter. Typical example of a counter would be:

\Processor Information(_Total)\% Processor Time

In this example

  • host is empty - meaning it is a counter for current host (localhost)
  • category is Processor Information
  • instance is _Total
  • counter name is % Processor Time

Our implementation can only query localhost counters.

It is worth noticing that some categories are only host-wide, meaning that they don’t have instance defined. An example of such a category is System. In that case, we would have:

\System\Processor Queue Length

Once the plugin is enabled, the next thing would be to define which counters you would like to monitor. This can be done by extending configuration:

com.instana.plugin.perfcounters:
  enabled: true
  counters:
    - category: [name of the counters category]
      instance: [instance name]
      counters:
        - [name of the counter]

Using the previous example, the configuration would look like this:

com.instana.plugin.perfcounters:
  enabled: true
  counters:
    - category: Processor Information
      instance: _Total
      counters:
        - "% Processor Time"

Note that counter name is enclosed with "" because of the special character %

If you need more counters per category, just add them to the counters array like this:

com.instana.plugin.perfcounters:
  enabled: true
  counters:
    - category: Memory
      counters:
        - Page Faults/sec
        - Cache Faults/sec
        - Page Reads/sec

Note that here we didn’t define instance because Memory category is host-wide.

Please note that querying performance counters is an inherently expensive operation. We made sure to optimize our solution, but having a lot of counters will impact the performance of the agent.

Here is another example with multiple categories and counters:

com.instana.plugin.perfcounters:
  enabled: true
    - category: System
      counters:
        - Processor Queue Length
        - System Calls/sec
    - category: Process
      instance: _Total
      counters:
        - Private bytes
        - Working Set
        - Thread Count
    - category: Memory
      counters:
        - Page Faults/sec
        - Cache Faults/sec
        - Page Reads/sec
    - category: .NET CLR Exceptions
      instance: _Global_
      counters:
        - "# of Exceps Thrown / sec"
        - "# of Pinned Objects"

Finally, here is an example of a host dashboard with some performance counters:

Example of Performance Counters dashboard