Monitoring .NET Framework-based applications

The sensor and tracing extensions are enabled by default. When the agent is started, InstanaPCP logs information about the process of trace enablement.

The following example shows the agent configuration.yaml file with .NET Framework tracing enabled:

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

Select the guide that matches your deployment environment:

For a comprehensive overview of all setup options, see Setting up .NET Framework tracing.

After you have basic monitoring set up, you can configure the following optional features to enhance your .NET Framework monitoring capabilities:

• Custom tracing: Add custom spans using the .NET SDK.
• Ignoring processes: Exclude specific processes from .NET tracing by configuring an environment variable.
• Whitelisting processes: Trace only specific processes.
• Span filtering: Reduce data volume by filtering specific spans.
• AutoProfile: Enable continuous profiling for performance optimization.

For detailed configuration instructions, see Configuring additional features.

Instana evaluates health signatures continuously against incoming metrics and raises issues or incidents based on user impact.

Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any specific entity.

For information about built-in events for .NET Framework, see Built-in events reference.

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

Instana with CLR Sensor 1.1.148 and .NET Tracer Framework 1.315.1 release (13 March 2026) restricts instrumentation to library versions explicitly listed in the Supported libraries and frameworks for tracing section. Unsupported versions are not instrumented.

To ensure continued support, upgrade to supported versions. For more details and workaround options, see the Technote.

When an application that is originally built on .NET Framework is migrated to .NET 5 or later (including .NET 6, 7, 8, and later) and hosted on IIS, the application pool must be configured to run with No Managed Code. In this mode, Instana cannot collect IIS‑level metrics.

When an IIS Application Pool is set to No Managed Code, Instana cannot collect the following IIS-level metrics:

• Application Pool names
• w3wp.exe process metrics
• Worker process-level monitoring data

This limitation is inherent to how IIS hosts .NET 5 and later applications. Application‑level instrumentation and tracing continue to work as expected but IIS-level metrics are not available.

If you require IIS-level metrics, consider using .NET Framework 4 or earlier applications, which support managed code Application Pools.

When instrumenting multi-AppDomain applications (such as SharePoint), the System.dll is loaded in multiple or shared AppDomains. However, when Instana tries to instrument the class System.Net.HttpWebRequest class in System.dll, it rewrites methods only in the main app domain, resulting in the following error:

Loading this assembly would produce a different grant set from other instances.

If you encounter this error, set the following environment variables:

INSTANA_REWRITER_SUPPRESSION=System.Net.HttpWebRequest
INSTANA_TRACER_SUPPRESSION_ENABLED=1

When set, rewriting is skipped for System.Net.HttpWebRequest, and the rest of the instrumentation works as expected.

If you don't see traces or metrics in the Instana UI, complete the following general troubleshooting steps:

1. Verify prerequisites:
   • Ensure that your .NET Framework runtime version is supported (.NET Framework 4.5.2 or later)
   • Confirm that the Instana agent is running and accessible
   • Verify InstanaPCP is running (check Task Manager for InstanaPCP.exe)
   • Check network connectivity between your application and the agent
2. Check environment variables:
   • Verify that all required environment variables are set correctly
   • Ensure that paths are valid and accessible
   • Confirm that variable names are spelled correctly
3. Verify tracing configuration:
   • Check that tracing is enabled in the agent configuration.yaml file
   • Restart the agent and application after configuration changes
   • For IIS applications, run iisreset after configuration changes
4. Check for conflicting APM tools:
   • Verify that no other APM tools are using the same profiling hooks
   • Disable other APM agents if present

For detailed platform-specific troubleshooting scenarios and solutions, see the appropriate troubleshooting guide in the following section.

For an overview of all troubleshooting options, see Troubleshooting .NET Framework tracing.