Monitoring .NET Framework

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.

Supported libraries and frameworks for tracing

To prevent creating spans for logs with a level lower 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.

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.

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.

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

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

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.

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.