Monitoring .NET and .NET Core based applications

Edit online

Monitor your .NET and .NET Core applications with Instana's automatic instrumentation and distributed tracing capabilities.

For .NET Framework applications, see Monitoring .NET Framework.

Overview

Edit online
Instana provides comprehensive monitoring for .NET applications through:
  • Automatic instrumentation: Zero-code changes required with AutoTrace
  • Distributed tracing: End-to-end visibility across your services
  • Performance metrics: CPU, memory, thread locks, and more
  • AutoProfile: Continuous profiling for performance optimization
  • OpenTelemetry support: Integrate with existing OTel implementations

How .NET monitoring works

Edit online

Create any application with .NET 5.0 and later or use an existing one. Install the Instana agent in your environment. The agent detects the .NET process and loads the .NET sensor. It automatically collects performance metrics and health data from your .NET Core applications.

You must explicitly set up .NET tracing to capture detailed trace data for request that flow through your application and connected services. Tracing tracks the journey of each request through your application, showing you how long each step takes and where problems occur.

You can set up tracing through the following approaches:

  • AutoTrace: Automatic setup through agent configuration
  • Manual tracing: Explicit NuGet package installation

For more information, see Instrumentation approaches.

When tracing is enabled, Instana activates the .NET Tracer, which captures traces by using one or both of the following instrumentation methods:

  • IL rewriting: Instana attaches to the .NET process and rewrites selected Intermediate Language (IL) code at runtime to inject tracing logic.
  • Event-driven instrumentation: Instana listens to events and ActivitySource data that are emitted by supported libraries and converts those events into distributed traces without rewriting IL code. For more information, see Configuring event-driven instrumentation.

Both sensors and tracers work together to provide complete observability. For latest sensor and tracer releases, see .NET Core sensor and .NET and .NET Core Tracer.

Prerequisites

Edit online

Ensure that the following prerequisites are met:

  • System hardware requirements:

    • RAM: 8 GB or more of available memory
    • CPU: 4 or more CPU cores for optimal performance
    • Disk space: 100 MB for tracer logs and temporary files

  • Instana agent is installed: The host agent must be running on your infrastructure.

  • Network connectivity: Your .NET application must reach the Instana agent. For more information, see Network requirements.

  • Supported .NET runtime

    • .NET 5.0 or later
    • .NET Core 2.x and 3.x (deprecated)

    For details, see Support information.

Setting up .NET monitoring

Edit online

To set up .NET monitoring, complete the following tasks in order:

Step 1: Understanding instrumentation approaches

Edit online

You can configure tracing for your .NET applications automatically or manually depending on your environment.

If your environment supports AutoTrace, Instana automatically instruments your .NET application. However, if AutoTrace is not supported, you must use manual tracing.

AutoTrace

Instana AutoTrace provides automatic instrumentation with zero code changes. With this approach, no manual configuration or setup is required. Instana automatically detects, instruments, and traces your application components for you.

Important: By default, auto-tracing for .NET Core is disabled. You must explicitly enable it.

To set up .NET tracing automatically, enable tracing in the agent configuration file. The agent detects .NET processes and automatically injects tracing into .NET processes. No NuGet packages or code modifications are required.

The agent creates a global environment file instana_dotnet_global_env.sh that contains the environment variables that are required for .NET tracing.

Instana immediately begins generating spans for incoming requests, and then you can view the traces in the Instana UI.

Manual tracing

Manual tracing involves instrumentation by using NuGet packages. With this approach, you have more control over what gets traced, but it needs additional configuration and setup.

Note: Ensure that diagnostics are enabled for .NET by setting the environment variables COMPlus_EnableDiagnostics and DOTNET_EnableDiagnostics to 1. If they are disabled, the IL rewriter cannot attach to the process, and therefore calls cannot be rewritten and traces cannot be generated.

To set up .NET tracing manually, complete the following steps:

  1. Add the following Instana NuGet packages to your project. These packages add tracing logic and enable runtime instrumentation.

    • Instana.Tracing.Core
    • Instana.Tracing.Core.Rewriter
    Note: Choose the correct Rewriter package variant for your target platform (Windows, Linux, or Alpine Linux).

  2. Set the following environment variables:

    • CORECLR_ENABLE_PROFILING
    • CORECLR_PROFILER_PATH
    • CORECLR_PROFILER
    • DOTNET_STARTUP_HOOKS

  3. Deploy your application with the tracing libraries included.

Manual tracing is ideal in the following scenarios:

  • Self-contained applications
  • Environments where AutoTrace isn't available

Step 2: Selecting platform-specific setup guide

Edit online

Select the guide that matches your deployment environment:

Table 1. Platform-specific setup guide
Deployment environment Guide
AWS Lambda functions Setting up .NET tracing on AWS Lambda
Azure App Services Setting up .NET tracing on Azure App Services
Azure Container Apps Setting up .NET tracing on Azure Container Apps
Azure Functions Setting up .NET tracing on Azure Functions
Cloud Foundry platform Setting up .NET tracing on Cloud Foundry
Docker containers Setting up .NET tracing on Docker
IIS-hosted web applications Setting up .NET tracing on IIS
Kubernetes clusters Setting up .NET tracing on Kubernetes
Standard Linux or Alpine Linux Setting up .NET tracing on Linux or Alpine Linux
Windows services or stand-alone processes Setting up .NET tracing on Windows
z/OS Setting up .NET tracing on z/OS

Step 3: Configuring additional features (optional)

Edit online

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

For detailed configuration instructions, see Configuring additional features.

Viewing metrics and traces

Edit online
Note: Metrics collection on Windows is available automatically. On Linux, additional setup is required. See Enabling metrics on Linux.

After you set up monitoring, you can view the metrics and traces that are related to .NET applications in the Instana UI.

To view metrics, complete the following steps:

  1. From the navigation menu in the Instana UI, select Infrastructure.
  2. Click a specific monitored host.

You can see a host dashboard with all the collected metrics and monitored processes.

To view traces, complete the following steps:

  1. From the navigation menu in the Instana UI, click Applications.
  2. On the Applications dashboard, select a .NET application or service.
  3. On the application or services dashboard, click Analyze Calls.
  4. On the Analytics dashboard, select Calls or Traces from the Applications menu.

The following guides provide detailed instructions on how to view the data for your applications:

Enabling metrics on Linux

Edit online

On Linux, deploy your application with the Instana.Tracing.Core NuGet package 1.1.34 or later. Set the following environment variable:

DOTNET_STARTUP_HOOKS=[path-to-your-app]/Instana.Tracing.Core.dll

To confirm that the package is loaded successfully, look for the following line in your application output:

INSTANA Agent for .NET Core applications installed. Running on

You can use the same package for tracing.

Configuration data

Edit online
Table 2. Configuration data
Tracked Configuration Description
Name Name of the application
Version CLR runtime version
Arguments Arguments of the application

Performance metrics

Edit online
Table 3. Performance metrics
Metrics Description
GC Activity Shows how often and how long the .NET Garbage Collector runs
Memory Usage Reports the amount of memory the application is using
Thread-locks Indicates when threads are blocked waiting for locks
Contention Measures competition between threads for shared resources
Exceptions Displays the number and types of runtime exceptions

Health signatures

Edit online

Instana evaluates health signatures continuously against incoming metrics and raise 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, see Built-in events reference.

Disabling tracing

Edit online

To disable tracing for .NET applications, complete the following steps:

  1. Update the configuration file: Open the agent configuration.yaml file (*instanaAgentDir*/etc/instana/configuration.yaml) and set the .NET tracing flag to enabled: false.

    The following example shows the configuration.yaml file with .NET tracing disabled:

    # netcore Tracing
com.instana.plugin.netcore:
tracing:
   enabled: false

  2. Restart the Instana agent so that the updated configuration is applied.

  3. Restart the host process.

Known issues and limitations

Edit online

Review the known issues and limitations for .NET tracing:

Application Insights for ASP.NET Core and Instana .NET Core monitoring

Edit online

Due to some limitations of Application Insights for ASP.NET Core, you might see incomplete or missing data on Application Insights when Instana .NET Core monitoring runs alongside it.

If you want to use Application Insights and Instana at the same time, you must disable W3C trace context propagation by disabling injecting of W3C header by Instana.

To disable Instana from injecting W3C headers, set the following environment variable:

INSTANA_W3C_DISABLE_INJECT_HEADERS=1

Library version instrumentation limitations

Edit online

Instana with .NET Core sensor 1.0.90 and .NET Tracer 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.

Limited IIS-level metrics for .NET 5 and later applications that run in No Managed Code application pools

Edit online

When you host .NET 5 or later applications (including .NET 6, 7, 8, and later) 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.

Troubleshooting .NET monitoring

Edit online

If you encounter issues with .NET monitoring or tracing, troubleshoot as follows:

Common troubleshooting steps

Edit online

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 runtime version is supported (.NET 5.0 or later)
    • Confirm that the Instana agent is running and accessible
    • 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 IL-Rewriter initialization:

    • Check application logs for IL-Rewriter initialization messages
    • Ensure that CORECLR_ENABLE_PROFILING, CORECLR_PROFILER_PATH, and CORECLR_PROFILER are set correctly

  4. Enable diagnostics:

    • If you use tracing that relies on the Instana IL rewriter, set COMPlus_EnableDiagnostics and DOTNET_EnableDiagnostics to 1
    • Without diagnostics enabled, the IL-Rewriter cannot attach to the process

  5. Verify tracing configuration:

    • Check that tracing is enabled in the agent configuration.yaml file
    • Restart the agent and application after configuration changes

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

Platform-specific troubleshooting guides

Edit online
Table 4. Platform-specific troubleshooting guides
Deployment environment Troubleshooting guide
AWS Lambda functions Troubleshooting .NET tracing on AWS Lambda
Azure Troubleshooting .NET tracing on Azure
Docker containers Troubleshooting .NET tracing on Docker
IIS-hosted web applications Troubleshooting .NET tracing on IIS
Kubernetes clusters Troubleshooting .NET tracing on Kubernetes
Standard Linux or Alpine Linux Troubleshooting .NET tracing on Linux or Alpine Linux
Windows services or stand-alone processes Troubleshooting .NET tracing on Windows
z/OS Troubleshooting .NET tracing on z/OS