Monitoring .NET and .NET Core based applications

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.

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

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.

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.

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.

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.

By default, auto-tracing for .NET Core is disabled. You must explicitly enable it in the Instana agent configuration file.

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

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

Restart the agent to apply the configuration changes.

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"
 

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

To collect .NET logs for various components, click dedicated buttons on the .NET Process Dashboard as outlined in the steps:

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.