Monitoring .NET Framework-based applications

Supported operating systems

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

Supported versions

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

Supported libraries and frameworks for tracing

The following table outlines Instana-supported versions of HTTP libraries and their corresponding support policy:

The following table outlines the Instana-supported versions of database libraries and their corresponding support policy:

The following table outlines the Instana-supported versions of ORM libraries and their corresponding support policy:

The following table outlines the Instana-supported versions of remoting libraries and their corresponding support policy:

The following table outlines the Instana-supported versions of messaging libraries and their corresponding support policy:

The following table outlines the Instana-supported versions of logging libraries and their corresponding support policy:

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

The following table outlines the Instana-supported versions of scheduler and task-management libraries and their corresponding support policy:

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.

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 that is 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}

4. After the last line, press Enter.

Custom tracing

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

Ignoring processes

You can exclude specific processes from .NET tracing by configuring an environment variable.

To ignore monitoring of certain processes in Windows, complete the following steps:

1. Add the INSTANA_REWRITER_BACKOFF environment variable on the host level.

2. Set its value to a list of pool names or process names that is separated by semicolons as shown in the following example:

   INSTANA_REWRITER_BACKOFF=my_pool_1;process_1;my_pool_2
   

3. Restart the IIS services with the iisreset command so that IIS can load a new environment.

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 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.