Monitoring .NET Framework

The .NET sensor is automatically deployed and installed after you install the Instana agent.

This page is about our support for .NET Full Framework based applications. If you are looking for support on .Net or .NET Core, see Monitoring .NET and .NET Core based applications.

Supported information

Supported operating systems

Monitoring .NET Framework is supported only on the Windows operating systems listed in Windows agent requirements.

Supported versions

Instana supports monitoring applications that run on .NET Framework 4.5.1 and later versions.

Runtime Support status
.NET Framework 4.5.1 and later GA

Supported libraries and frameworks for tracing

HTTP Support policy Version
ASP.NET MVC 45 days 5.0.0, 5.2.2, 5.2.3, 5.2.4, 5.2.5, 5.2.6, 5.2.7, 5.2.8, 5.2.9, and 5.3.0
ASP.NET WebAPI 45 days 5.0.0, 5.1.0, 5.2.2, 5.2.3, 5.2.4, 5.2.5, 5.2.6, 5.2.9, and 5.3.0
ASP.NET WebForms 45 days All .Net Framework versions from 4.5.2 as system library
ASP.NET Core 45 days 1.0.3, 1.0.4, 1.1.2, 1.1.3, 1.1.7, 2.0.0, 2.0.1, 2.0.2, and 2.2.0
RestSharp 45 days 106.11.7.0, 106.12.0, 106.13.0, 106.14.0, 106.15.0, 107.0.0, 107.0.1, 107.0.2, 107.0.3, 107.1.1, 107.1.2, 107.2.0, 107.2.1, 107.3.0, 108.0.0, 108.0.1, 108.0.2, 108.0.3, 109.0.0, 109.0.1, 110.0.0, 110.1.0, 110.2.0, 111.0.0, 111.2.0, 111.3.0, 111.4.0, and 111.4.1
ServiceStack On demand 4.5.14, 5.0.0, 5.0.2, 5.1.0, 5.2.0, 5.4.0, 5.5.0, 5.6.0, 5.7.0, 5.8.0, 5.9.0, 5.9.2, 5.10.0, 5.10.2, 5.10.4, 5.11.0, 5.12.0, 5.13.0, 5.13.2, 5.14.0, 6.0.0, 6.0.2, 6.1.0, 6.2.0, 6.3.0, 6.4.0, 6.5.0, 6.6.0, 6.7.0, 6.8.0, 6.9.0, 6.10.0, 6.11.0, 8.0.0, 8.1.0, 8.1.2, 8.2.0, 8.2.2, and 8.3.0
System.Net.Http.HttpClient 45 days All .Net Framework versions from 4.5.2 as system library and 4.3.4
System.Net.HttpWebRequest 0 day All .Net Framework versions from 4.5.2 as system library
Databases Support policy Version
Microsoft SQL-Server (System.Data.SqlClient) 45 days 4.8.2, 4.8.5, and 4.8.6
Oracle ODP (Oracle.DataAccess.Client) 45 days 2.102.5, 2.112.1, 4.112.2, 4.112.3, 4.121.2, and 4.121.3 - 4.122.21.1
Oracle Devart (Oracle.ManagedDataAccess.Client) 45 days 12.1.22, 19.12.0, 21.10.0, 21.11.0, 21.12.0, 21.13.0, 21.14.0, 21.15.0, 23.4.0, 23.5.0, and 23.5.1
PostgreSQL (NpgSql) 45 days 2.0.12.1, 2.1.0, 2.2.0, 3.0.0–7.0.4, and 8.0.3
Cassandra On demand 3.4.0, 3.7.0, 3.8.0, 3.9.0, 3.10.0–3.11.0, and 3.20.1
Couchbase 45 days 3.1.7, 3.2.0, 3.2.1, 3.2.3, 3.2.4, 3.2.5, 3.2.6, and 3.2.7 - 3.6.2
Elasticsearch 45 days 6.0.0, 7.0.0, 7.0.1, 7.1.0, 7.2.0, 7.2.1, 7.3.0, 7.3.1, 7.4.0, 7.4.1, 7.4.2, 7.5.0, 7.5.1, 7.6.0, 7.6.1, 7.6.2, 7.7.0, 7.7.1, 7.8.0, 7.8.1, 7.8.2, 7.9.0, 7.10.0, 7.11.1, 7.12.0, 7.12.1, 7.13.0, 7.13.1, 7.13.2, 7.14.0, 7.14.1, 7.15.0, 7.15.1, 7.15.2, 7.16.0, 7.17.0, 7.17.1, 7.17.2, 7.17.3, 7.17.4, and 7.17.5
MongoDB 45 days 2.4.4, 2.10.0, 2.10.1, 2.10.2, 2.10.3, 2.10.4, 2.11.0, 2.11.1, 2.11.2, 2.11.3, 2.11.4, 2.11.5, 2.11.6, 2.12.0, 2.12.1, 2.12.2, 2.12.3, 2.12.4, 2.12.5, 2.13.0, 2.13.1, 2.13.2, 2.13.3, 2.14.0, 2.14.1, 2.15.0, 2.15.1, 2.16.0, 2.16.1, 2.17.0, 2.17.1, 2.18.0, 2.19.0, 2.19.1, 2.19.2, 2.20.0, 2.21.0, and 2.22.0-2.28.0
Redis Service Stack On demand 5.0.0
Redis Stack Exchange 45 days 2.0.519
Memcached 45 days 2.11.0, 2.12.0, 2.13.0, and 2.16.0
IBM Db2 Deprecated 11.5.4000.4, 11.5.4000.4861, and 11.5.9000.4
MySql (MySql.Data) 45 days 8.0.18, 8.0.19, 8.0.20, 8.0.21, 8.0.22, 8.0.23, 8.0.24, 8.0.25, 8.0.26, 8.0.27, 8.0.28, 8.0.29, 8.0.30, 8.0.31, 8.0.32, 8.0.32.1, and 8.0.33–8.1.0, 8.2.0, 8.3.0, 8.4.0, and 9.0.0
Sql (System.Data) 0 day All .NET Framework versions from 4.5.2 as system library
ORM Support policy Version
Entity Framework 45 days All .Net Framework versions from 4.5.2 as system library
Remoting Support policy Version
Windows Communication Foundation Services 0 day All .Net Framework versions from 4.5.2 as system library
.NET Remoting 0 day All .Net Framework versions from 4.5.2 as system library
System.ServiceModel 0 day All .Net Framework versions from 4.5.2 as system library
Messaging Support policy Version
Azure Queue Storage 45 days 12.8.0, 12.9.0, 12.10.0, 12.11.0, 12.12.0, 12.13.0, 12.14.0, 12.15.0, 12.16.0, 12.17.0, 12.17.1, 12.18.0, 12.19.0, and 12.19.1
Microsoft Message Queue 0 day All .Net Framework versions from 4.5.2 as system library
EasyNetQ On demand 3.3.9 and 3.4.0 - 7.8.0
RabbitMQ 45 days 3.6.9, 5.0.1, 6.0.0, 6.5.0, 6.6.0, 6.7.0, and 6.8.1
Logging Support policy Version
NLog 45 days 4.5.11, 4.6.8, 4.7.10, 5.1.1, 5.1.2–5.2.4, 5.2.8, 5.3.2, and 5.3.3
Log4Net 45 days 2.0.0, 2.0.10, 2.0.11, 2.0.12, 2.0.13, 2.0.14, 2.0.15, 2.0.4, 2.0.5, 2.0.7, 2.0.8, 2.0.15, and 2.0.17
Serilog 45 days 2.8.0, 2.9.0, 2.10.0, 2.11.0, 2.12.0, 3.0.1, 3.1.1, 4.0.0, and 4.0.1

To prevent creating spans for logs with a level lower than the default value WARN, you can set the INSTANA_LOG_LEVEL_CAPTURE environment variable to WARN, ERROR, or OFF. If you set the value to OFF, the spans are not created for logs.

Schedulers and Task-Management Support policy Version
Hangfire On demand 1.6.20, 1.8.5, 1.8.6, 1.8.7, 1.8.9, 1.8.10, 1.8.12, 1.8.13, and 1.8.14
Quartz On demand 3.0.7, 3.9.0, and 3.12.0

Viewing metrics

The following metrics are collected for .NET Framework:

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

Health signatures for raising issues and incidents

For every sensor, a curated knowledge base of health signatures is evaluated continuously against the incoming metrics. Issues or incidents are raised depending on the user impact.

  • Built-in events trigger issues or incidents based on the failing health signatures on entities. For more information about built-in events for the .NET sensor, see Built-in events reference.
  • custom events trigger issues or incidents based on the metric thresholds of an entity.

InstanaPCP and performance counters

For more information about InstanaPCP and performance counters, see Monitoring Windows processes.

.NET Framework Tracing

When you enable tracing by changing the configuration file, tracing data is collected for all applications that use the supported technologies. .NET Framework Tracing uses the same scheme as all other tracing packages. Distributed traces in polyglot applications are automatically collected, and they are displayed in the Instana UI.

When you enable tracing for an application at start-up, the start-up might take longer. The increase in start-up time is due to attaching the profiler, inspecting the classes contained in the referenced assemblies, and then just-in-time compiling some methods' code for instrumentation. After you apply the instrumentation, the impact on the runtime performance of your applications is low, as with any other tracing-package that Instana provides.

The agent automatically sets up the tracing component. However, you must manually set up tracing.

Setting up tracing for .NET Framework

When the Instana agent starts on your Windows machine, the Instana agent installs the tracing extension for .NET Framework. The extension is composed of several files that contain the tracing components. Because Instana uses the Profiling API defined in the .NET framework, it involves COM-Libraries and managed assemblies. With tracing enabled, the files are registered so that all applications can use them for tracing. The sensor and tracing-extensions are enabled by default.

When the agent is started, InstanaPCP logs information about the process of trace enablement. The configuration.yaml file with .NET Framework Tracing enabled is shown in the following example:

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 COM-DLL (profiler), with 3 managed assemblies. The extension contains the instrumentation code that is required for the instrumentation for Instana.ManagedTracing.dll, Instana.ManagedTracing.Base.dll, System.Collections.Immutable.dll. After the extension registers the components, the extension updates the registry so that any instances of W3SVC or WebSphere Application Server attaches the profiler the next time when they start. A warning about restarting already running applications is added to the logs. Instana does not restart these services automatically to prevent interruptions to your services.

Enabling tracing for IIS-hosted applications

If you are running IIS hosted applications, InstanaPCP automaticaly sets up tracing. After the Instana agent and InstanaPCP application start running, run the IIS reset. To check whether InstanaPCP is running, use Task Manager on Windows.

If IIS is not reset, IIS workers aren't instrumented, and you cannot trace IIS-hosted applications.

Enabling tracing for non-IIS hosted applications

The Instana agent does not enable tracing for all the .NET-based applications. For example, tracing Windows system applications that are not in the scope of your monitoring needs.

Setting up environment variables for Processes

IIS and WebSphere Application Server are configured to attach the profiler automatically by setting appropriate environment variables. However, standalone-processes are not configured. To enable tracing for the standalone-processes, complete one of the following steps:

  • If you use specific users to run your applications, set the environment variables on the user level
  • Set the environment variables before starting the process

To enable tracing for a process, set the following environment variables:

The following example shows the environment variable required to enable tracing:

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

You can put these settings into a batch or shell script that sets the environment variables then starts your processes.

Setting up environment variables for Windows-Services

If you are running Windows-Services, you can add these settings into the registry, on a per-service basis. Adding these settings gives you better control on choosing the services to trace.

To set up the environment variable for Windows-Services, complete the following steps:

  1. Go to the Registry Editor in the HKLM\System\CurrentControlSet\Services\<ServiceName> directory.
  2. Add the MULTI_SZ value with the name, Environment.
  3. If MULTI_SZ does not exist, copy the variables COR_ENABLE_PROFILING=1 and COR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3} into that value. To set the contents of a MULTI_SZ value, add one key-value pair per line as shown in the following example:
COR_ENABLE_PROFILING=1
COR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}
  1. After last line, press Enter.

Custom tracing

.NET Tracing SDK on Instana enables custom tracing for components that Instana does not trace automatically.

Disabling tracing for .NET Framework

To stop tracing for the .NET Framework applications, change the Configuration.yaml file back to its initial state or set the corresponding flag to false.

The following example shows an extract from the Configuration.yaml file with .NET Framework-Tracing disabled:

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

After changing the configuration back to its initial state, restart the agent for the changes to take effect.

Disabling tracing in the agent does not remove or detach the profiler from processes that have been started with tracing enabled (that is, your worker-processes). To make sure the profiler is not loaded into the application, restart the host-process.

Open Telemetry Integration

Instana provides .NET components for integrating with OpenTelemetry, which are described in the page Open Telemetry Integration.

Troubleshooting

If you encounter an issue that is not listed in Troubleshooting, contact IBM Support.

Review the steps that are needed to enable tracing.

  • Focus on one application first. Try to get the application monitored, and then instrumented.
  • Look for details about how to enable tracing.
  • After the agent starts and runs for a few minutes, you can view the information on the Task Manager InstanaPCP.exe. If you see the information and your application is IIS hosted, then run iisreset to check whether the instrumentation is attached to the applications hosted by IIS.
  • If your application is IIS hosted and iisreset is run, look for the application in the Instana UI. The application is displayed within a minute.
  • Try sending requests to that application, and then try searching for that service in the UI. For example, find that process on that host, go to the service, and then click Analyze traces. If this does not work, try turning on agent tracing logs. First, set tracing to capture only metrics so that you can check whether the sensor finds that application in the list of metrics that it sends to the backend. You can do the same by comparing the agent logs with the process ID of that application. Check if the log includes information that a CLR sensor is created for a process ID.
  • If you find those metrics or logs, then enable tracing logs for the agent so that the agent captures traces that it sends to the backend. Those traces contain the process ID and name, so try to match the traces with the application that you are trying to instrument.

Environment variable not defined

Monitoring issue type: clr_env_var_not_defined

At least one environment variable that is required to activate the Instana .NET Framework tracing is not set correctly.

  • For applications that are hosted on IIS, the iisreset might not have been issued, or it was issued before the agent could register the libraries that are needed for tracing. Try running iisreset from an elevated command prompt. If the issues is not resolved, consider restarting the machine. Restart might be required depending on the Windows version that is running and whether applications were being installed or uninstalled when the Instana agent started.

  • For the environment variables required for tracing the .NET Framework applications that are not hosted on IIS, see Enabling Tracing for Non-IIS Hosted Applications.

Environment variable contains an invalid value

Monitoring issue type: clr_env_var_invalid_value

The correct value is not set for at least one environment variable, which is required to activate the Instana .NET Framework tracing. Depending on the environment variables that are missing, metrics might be displayed in the Instana dashboard for your .NET Framework application. However, traces are not displayed. For the list of environment variables that are required for tracing your .NET Framework applications with Instana, see Enabling Tracing for Non-IIS Hosted Applications.

Also, an environment variable might have the wrong value because another APM tool is present. To attach to the .NET runtime, various APM tools use similar mechanisms. You can check the APM tools present in the Instana UI.

For Instana to trace your .NET Framework application, turn off the other APM agent, at least for .NET Framework monitoring. For information about how to turn off the other APM agent, refer to the documentation of the APM tool.