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, 111.4.1, and 112.1.0 |
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, 23.5.1, and 23.6.0 |
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 and 6.0.0 - 8.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 |
Messaging | Version |
---|---|
Azure Queue Storage | 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, and 12.18.0 |
Microsoft Message Queue | All .Net Framework versions from 4.5.2 as system library |
EasyNetQ | 3.3.9 |
RabbitMQ | 3.6.9, 5.0.1, 6.0.0, 6.5.0, 6.6.0, 6.7.0, and 6.8.1 |
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, 3.12.0, and 3.13.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:
# .NET Full Framework tracing
com.instana.plugin.clr:
# # Tracing for .NET Full Framework CLR. Enabled by default
tracing:
# # Enabling tracing will instruct the agent to register the IL-rewriting components for .NET
# # alongside with the instrumentation-libraries.
# # It will also set the environment-variables for any IIS hosted .NET applications.
# # Non-IIS hosted applications which you want to trace need these env-vars to be set
# # manually before starting the actual process
# # (see the docs here: https://docs.instana.io/ecosystem/dot-net/#enabling-tracing-for-non-iis-hosted-applications)
enabled: true
instrumentation:
suppressions:
# # The absolute path to a batch-file that should be executed when the tracing-components for
# # NET Full Framework (Windows) have been updated. You can use this script to automate tasks
# # that should be executed when new tracing-components get installed. This usually will be
# # process-restarts or issuing an iisreset command, so that the processes can pickup the new components.
# # The commands issued in the script should be executed asynchronously (start /b <cmd>) in order to not
# # slow down the startup-time of InstanaPCP. In case of long-running synchronous tasks (like iisreset) you might
# # see warnings in the log concerning the unavailability of InstanaPCP for the duration of the execution.
# update_script: <absolute_path_to_batchfile>
# # Memory-limits for InstanaPCP.
# # You can specify these limits to account for high expected load and/or a lot of
# # infrastructure-components being monitored. Values are in mega-bytes.
# pcp_warn_limit: 150
# pcp_stop_limit: 250
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
InstanaPCP automatically sets the environment variables and installs the necessary files to work with your .NET Framework applications. After the Instana agent and InstanaPCP application start running, run the iisreset
command.
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:
- Go to the Registry Editor in the
HKLM\System\CurrentControlSet\Services\<ServiceName>
directory. - Add the
MULTI_SZ
value with the name,Environment
. - If
MULTI_SZ
does not exist, copy the variablesCOR_ENABLE_PROFILING=1
andCOR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}
into that value. To set the contents of aMULTI_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}
- 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 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.