Monitoring .NET and .NET Core based applications

Supported operating systems

Instana supports monitoring .NET and .NET Core based applications on the following operating systems:

• Linux®
• Windows®

For more information about the supported versions of Windows and Linux operating systems, see Windows agent requirements and Linux agent requirements.

Supported runtimes

Instana supports monitoring applications that run on .Net 5.0 and later.

.NET 9 instrumentation is supported. However, profiling is currently unsupported due to tech limitations.

Support for .NET Core 2.0 and later is deprecated.

.NET refers to the implementation of .NET that is recommended for all new development: .NET 5 (and .NET Core) and later versions. .NET and .NET Core naming conventions are not used in this document. Instead, the new .NET naming convention is used for consistency.

Supported libraries and frameworks for tracing

To prevent creating spans for logs with lower level than the configured level, set the environment variable INSTANA_LOG_LEVEL_CAPTURE to WARN*, ERROR, or OFF (to disable). The default value is WARN.

Health signatures

For every sensor, health signatures are evaluated continuously against incoming metrics and are used to raise issues or incidents depending 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 given entity.

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

Retrieving metrics for .NET applications on Linux

Instana supports retrieving metrics for .NET applications that run on Linux. To enable Instana to retrieve metrics for a .Net application running on Linux, deploy the application with Instana.Tracing.Core nuget-package 1.1.34 or later versions.

You can use the same package for tracing.

Ensure that the package is added, and the application is published.

When the packages are distributed through NuGet.org, you don't need to compile the project that is to be instrumented. You can restore the project by using the nuget.exe file, if available. Alternatively, you can download the necessary NuGet packages from Instana.Tracing.Core and Instana.Tracing.Core.Rewriter.Linux or Instana.Tracing.Core.Rewriter.Alpine, and then extract them.

After extraction, point the environment variables to the extracted files as shown in the following steps.

For the application to report metrics to a running agent, set the following environment variable:

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

After you set the DOTNET_STARTUP_HOOKS environment variable, look for the following output in your application:

INSTANA Agent for .NET Core applications installed. Running on 3.1.1

The version string varies depending on the .NET version that you are running.

Enabling Instana AutoTrace on .NET

On .NET Core sensor 1.0.56 and later, .NET tracer supports host autotracing on Windows and Linux systems except containers. After you start the agent, start the application. During the discovery startup, the sensor automatically enables the tracing. You don't need to manually inject the NuGet package and compile the application. During the discovery process, the instana_dotnet_global_env.sh file is created. This file contains the environment variables that are required for for .NET Core tracing.

See the following example for the contents of the instana_dotnet_global_env.sh file:

export CORECLR_ENABLE_PROFILING="1"
export CORECLR_PROFILER_PATH="/opt/instana/agent/data/repo/com/instana/core-clr-extension/1.286.3/core-clr-extension-1.286.3/{glibc/muslc}/CoreProfiler.so"
export CORECLR_PROFILER="{cf0d821e-299b-5307-a3d8-b283c03916dd}"
export DOTNET_STARTUP_HOOKS="/opt/instana/agent/data/repo/com/instana/core-clr-extension/1.286.3/core-clr-extension-1.286.3/{glibc/muslc}/Instana.Tracing.Core.dll"

To enable Instana AutoTrace on .NET applications, modify the agent configuration file configuration.yaml as shown in the following example:

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

Restart the agent to apply the configuration changes.

Enabling .NET tracing manually

Before any application is actively instrumented and traced by the extension, provide the environment settings that .NET needs to load the profiling component. If sensor and tracing are enabled for your host, add the NuGet package for Instana tracing to your application, and set up the appropriate environment variables.

Ensure that diagnostics are enabled for .NET. The environment variables COMPlus_EnableDiagnostics and DOTNET_EnableDiagnostics must be set to 1. If these environment variables are disabled, the rewriter cannot attach to the process. Therefore, calls cannot be rewritten and traces cannot be generated.

Instana supports non and self-contained .NET applications. The self-contained applications require Instana.Tracing.Core NuGet-package 1.1.34 or later versions. Specify the following environment variable:

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

To enable .Net tracing on different platforms, see Enabling .NET tracing on different platforms.

Configuring Kafka trace correlation headers

You can configure the format for Kafka trace correlation headers that are used by the .NET tracer with the INSTANA_KAFKA_HEADER_FORMAT environment variable. Valid values are binary, string, or both. Do not disable Kafka trace correlation entirely with INSTANA_KAFKA_TRACE_CORRELATION=false.

Another alternative is to configure the Kafka trace correlation options at the level of the Instana host agent.

For more information, see Kafka Header Migration.

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 manual tracing for .NET

To disable tracing for .NET applications, change the configuration file back to its initial state or set the corresponding flag to false.

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

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

Restart the agent for the configuration changes to take effect.

Due to the nature of how the Profiling API works, disabling tracing in the agent does not remove or detach the profiler from processes that are started when tracing was enabled (for example, worker-processes). To make sure the profiler is not loaded into the application, restart the host-process.

Enabling AutoProfile™ on Linux

To enable AutoProfile™, add the following settings to your agent's configuration.yml file:

com.instana.plugin.netcore:
  profiling:
    enabled: true

You can also enable AutoProfile™ by setting the environment variable INSTANA_AUTO_PROFILE to true.

Enabling AutoProfile™ on Windows

To enable AutoProfile™, complete the following steps:

1. Add the following settings to your agent's configuration.yml file:

   com.instana.plugin.netcore:
     profiling:
       enabled: true
   

2. Set the environment variable INSTANA_AUTO_PROFILE to true.

For more information, see Analyze Profiles.

Environment variable contains an invalid value

Monitoring issue type: netcore_env_var_invalid_value

Incorrect values are set for one or more environment variables that are required for activating Instana .NET tracing. Depending on the missing environment variables, you can see only some metrics but not traces in the Instana dashboards for your .NET application. For the environment variables and values that are required for tracing your .NET applications with Instana, see Enabling .NET tracing manually.

The environment variables might contain wrong values if another APM tool is present. In terms of hooking into the .NET runtime, various APM tools use a similar mechanism. If Instana detects another APM tool, an error message is displayed in the Instana UI.

For Instana to trace your .NET application, turn off the other APM agent. To turn off an APM tool, refer to the documentation of the APM tool.

Sensor not connected

Monitoring issue type: netcore_sensor_not_connected

If the Instana host agent does not receive the acknowledgment from the .NET process that it is instrumented with Instana, check whether the following errors occurred:

• Environment variable has an invalid value

The host agent might not detect any reason.

To troubleshoot the issue, complete the following steps:

1. Verify whether the tracer is installed.
2. Verify whether the tracer can connect to the host agent.

Error getting agent-info, make sure the agent is running and reachable:One or more errors occurred. (Connection refused)

Process Announcement:One or more errors occurred. (Connection refused)

Check IL-Rewriter

When IL-Rewriter is loaded into your application, it writes three characteristic lines to the output of your application. If you encounter issues, check whether you can see the following lines in the application logs:

Initializing Instana IL-Rewriter for .NET Core
Logging path is not set
Loading configuration-file /app/instana_tracing/instrumentation.json

The paths may differ depending on your setup, but these lines should be at the very beginning of the output of your app (since the Rewriter will be loaded before your actual app by the runtime)

If these lines do not appear:

*make sure all of the CORECLR environment-variables are available to your application

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

Due to some limitations of Application Insights for ASP.NET Core, you can face insufficient data on Application Insights when Instana .NET Core monitoring is running in parallel. If you want to use Application Insights and Instana in parallel, you must disable W3C trace context propagation by disabling injecting of W3C header by Instana. To disable injecting W3C header, set the environment variable INSTANA_W3C_DISABLE_INJECT_HEADERS=1.