Monitoring .NET and .NET Core based applications

The .NET sensor is automatically deployed and installed after you install the Instana agent. After you set up .Net and .NET Core tracing for your environment, you can view metrics that are related to .NET and .Net Core based applications in the Instana UI.

If you are looking for information about how to monitor .Net Framework by using the .NET sensor, see Monitoring .NET Framework.

Supported information

Supported operating systems

Linux® and Windows® are supported for monitoring .NET and .NET Core based applications.

The supported Windows and Linux operating systems are the same as the Windows agent requirements and Linux agent requirements.

Supported runtimes

Instana supports monitoring applications that run on the following .Net runtimes:

  • .NET Core 2.0 and later
  • .Net 5.0 and later

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

Runtime Availability
.NET Core Runtime >= 2.0, >= 3.0 GA
.NET Core Runtime >= 5.0 GA

Supported libraries and frameworks for tracing

HTTP-Server Version
ASP.NET Core 1.0.4, 1.1.7, 2.0.1, 2.2.0, and all .NET or .NET Core versions as system library
ServiceStack 5.11.0 and 6.10.0
HTTP-Client Version
HttpClient All .NET or .NET Core versions as system library and 4.3.4
HttpWebRequest All .Net or .NET Core versions as system library
Databases Version
ADO drivers
Aerospike 3.8.0, 3.9.4–3.9.16.2, and 4.0.0–4.1.0
Cassandra 3.4.0 and 3.7.0
Couchbase 3.2.4, 3.4.8, and 3.4.10
ElasticSearch 7.13.1
Redis Service Stack 5.0.0
Redis Stack Exchange 1.2.6, 2.0.519, and 2.1.28
PostgreSQL (NpgSql) 5.0.4, 5.0.5–5.0.16, 6.0.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 7.0.0, 7.0.1, 7.0.2, and 7.0.4
Azure Cosmos Client 3.1.1, 3.3.1, 3.4.1, 3.5.1, 3.6.0, 3.7.0–3.13.0, 3.15.0, 3.15.1, 3.16.0, 3.17.0, 3.17.1, 3.18.0, 3.19.0, 3.20.0, 3.20.1, 3.21.0, 3.22.0, 3.22.1, 3.23.0, 3.24.0, 3.25.0, 3.26.0, 3.26.1, 3.26.2, 3.27.0, 3.27.1, 3.27.2, 3.28.0, 3.29.0, 3.30.0, 3.30.1, 3.31.0, 3.31.1, 3.31.2, 3.32.3, 3.33.0, 3.35.0, 3.35.0, 3.35.1, 3.35.2, and 3.35.3
Azure DocumentDB Core 2.5.1 and 2.9.0
MongoDB 2.4.4, 2.10.3, 2.11.3, 2.12.5, 2.13.3, 2.14.1, 2.15.1, 2.16.1, 2.17.1, 2.18.0, and 2.19.2–2.21.0
Google Cloud Storage 3.3.0 and 4.6.0
AWSSDK.DynamoDBv2 3.7.0, 3.7.0.20, and 3.7.201.7
IBM DB2 (Windows) 3.1.0.400, 3.1.0.500, and 3.1.0.600
IBM DB2 (Linux) 3.1.0.500
AWS S3 3.7.0.28 and 3.7.203.11
Memcached 2.16.0
Messaging Version
Azure Queue Storage 12.8.0, 12.9.0, 12.10.0, 12.11.0, 12.11.1, 12.12.0, 12.13.0, 12.13.1, 12.14.0, 12.15.0, 12.16.0, 12.17.0, and 12.17.1
RabbitMQ 5.2.0, 6.2.2, 6.2.3, 6.2.4, 6.3.0, 6.3.1, 6.4.0, and 6.5.0
gRPC 2.31.0 and 2.57.0
Google Cloud PubSub 2.1.0
Confluent Kafka 1.5.3, 1.6.2, 1.6.3, 1.7.0, 1.8.0, 1.8.1, 1.8.2, 1.9.0, 1.9.2, 1.9.3, 2.0.2, 2.1.0, 2.1.1, and 2.2.0
AWSSDK.SQS 3.7.0 and 3.7.200.37
AWSSDK.SimpleNotificationService 3.7.1.10 and 3.7.200.36
Logging Version
ILogger based log-solutions 2.0.0, 3.0.0, 3.1.0, 5.0.0, 6.0.0, and 7.0.0
NLog 4.5.11, 4.7.10, 5.0.1, 5.1.1, and 5.2.4
Serilog 2.8.0, 2.9.0, 2.10.0, 2.11.0, 2.12.0, 3.0.0, and 3.0.1
Serverless Version
Azure Functions for .NET Core 3.1 5.0.1
Azure Functions for .NET 6, 7, and 8 1.20.0
Amazon.Lambda.Core 2.1.0 and 2.2.0

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.

ORM Version
Entity Framework 2.0.0, 3.0.0, and 5.0.0
Schedulers / Task-Management Version
Hangfire 1.7.19 and 1.8.5

Collecting metrics

Metrics collection is supported only on Windows.

Tracked Configuration Metrics
Name GC Activity
Version Memory Usage
Arguments Thread-locks
Contention
Exceptions

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.

Setting up .NET tracing

Setting up .NET tracing for your environment is covered in the following sections.

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

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

Enabling tracing for applications running on Kubernetes

The Instana AutoTrace WebHook is an implementation of a Kubernetes Mutating WebHook Admission Controller that automatically sets up everything that is required to monitor .NET applications with Instana, across an entire Kubernetes cluster.

If Instana AutoTrace WebHook is installed on the Kubernetes clusters, tracing is automatically enabled for the .NET applications that run in those clusters.

If the .NET application and the Instana Agent are managed by Kubernetes, refer to Kubernetes network access for information about the required configuration.

Enabling tracing for applications running on Linux

For applications that run on Linux except on Alpine Linux, install the Instana.Tracing.Core.Rewriter.Linux package. You can add the package to your project or add it before publishing. Provide the environment variables to your process before starting the process as shown in the following example:

DOTNET_STARTUP_HOOKS=[path-to-your-app]/Instana.Tracing.Core.dll
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATH=[Path_to_your_app]/instana_tracing/CoreProfiler.so

If your application is running inside a container, define the environment for the process to contact the Instana agent at runtime:

INSTANA_AGENT_HOST=[address_where_the_agents_listens_and_is_reachable_from_inside_the_container]
INSTANA_AGENT_PORT=42699 (or any other port of configured differently)

Enabling tracing for applications running on Alpine Linux

Install the Instana.Tracing.Core.Rewriter.Alpine package. You can add the package to your project or add it before publishing. Then provide the environment variables to your process before starting the process as shown in the following example:

DOTNET_STARTUP_HOOKS=[path-to-your-app]/Instana.Tracing.Core.dll
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATH=[Path_to_your_app]/instana_tracing/CoreProfiler.so

If your application is running in a container, define the environment for the process to contact the Instana agent at runtime:

INSTANA_AGENT_HOST=[address_where_the_agents_listens_and_is_reachable_from_inside_the_container]
INSTANA_AGENT_PORT=42699 (or any other port of configured differently)

Enabling tracing for applications running on Windows

Install the Instana.Tracing.Core.Rewriter.Windows package. You can add the package to your project or add it before publishing.

Enabling tracing for Windows processes

After you install the package, provide the environment variables to your process before starting the process as shown in the following example:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}
CORECLR_PROFILER_PATH_64=[Path_to_your_app]/instana_tracing/CoreRewriter_x64.dll
CORECLR_PROFILER_PATH_32=[Path_to_your_app]/instana_tracing/CoreRewriter_x86.dll

Enabling tracing for Windows services

If you are running Windows services, you can also put these settings into the registry, on a per-service basis, which gives you better control to choose the services to trace.

Go to the Registry Editor in the HKLM\System\CurrentControlSet\Services\<ServiceName> directory, and add a MULTI_SZ as the value for Environment. If Environment does not exist, then copy the variables CORECLR_ENABLE_PROFILING=1 and CORECLR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3} into the file.

To set the contents of a MULTI_SZ value, enter one key-value-pair per line as shown in the following example:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}
CORECLR_PROFILER_PATH_64=[Path_to_your_app]/instana_tracing/CoreRewriter_x64.dll 
CORECLR_PROFILER_PATH_32=[Path_to_your_app]/instana_tracing/CoreRewriter_x86.dll

Press Enter after you enter the last line.

Enabling tracing for IIS hosted applications

When the application is hosted through IIS, the best practice is to set the environment variables in the web.config file of the application in the following format:

<aspNetCore ...>
  <environmentVariables>
    <environmentVariable name="CORECLR_ENABLE_PROFILING" value="1" />
    <environmentVariable name="CORECLR_PROFILER" value="{FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}" />
    <environmentVariable name="CORECLR_PROFILER_PATH_64" value="[Path_to_your_app]/instana_tracing/CoreRewriter_x64.dll" />
    <environmentVariable name="CORECLR_PROFILER_PATH_32" value="[Path_to_your_app]/instana_tracing/CoreRewriter_x32.dll" />
    <environmentVariable name="DOTNET_STARTUP_HOOKS" value="[Path_to_your_app]/Instana.Tracing.Core.dll" />
  </environmentVariables>
</aspNetCore>

Enabling tracing for applications on Cloud Foundry

This section is applicable only if the Instana agent is running on the Diego cells of the Cloud Foundry foundation. For information on setting up Instana agents and the related Cloud Foundry or Pivotal Platform functionality, see Cloud Foundry and Pivotal Platform documentation.

On Cloud Foundry, to monitor non self-contained .NET applications follow these steps:

  • To add the Instana NuGet package to the Cloud Foundry application, run this command:

    dotnet add myproject.csproj package Instana.Tracing.Core.Rewriter.Linux
    
  • To prepare the .NET application for publication, run this command:

    dotnet publish -c Release
    
  • To use a configuration other than Release, add the following environment variables to the application manifest:

    ---
    applications:
    - name: <application_name>
      path: bin/Release/netcoreapp2.1/publish/
      env:
        DOTNET_STARTUP_HOOKS:[path-to-your-app]/Instana.Tracing.Core.dll
        CORECLR_ENABLE_PROFILING: 1
        CORECLR_PROFILER: "{cf0d821e-299b-5307-a3d8-b283c03916dd}"
        CORECLR_PROFILER_PATH: "/home/vcap/app/instana_tracing/CoreProfiler.so"
        LD_LIBRARY_PATH: "/home/vcap/app/instana_tracing"
    

    Depending on the .NET SDK that is used and the configuration name that is passed to the dotnet publish -c Release command through the -c flag (Release in the example), the value for the path variable might change.

  • To push the Cloud Foundry application, run this command:

    cf push
    

    The command above assumes that the application's manifest.mf file is located in the same folder from which you run the cf push command.

For more information on how to use the cf push command together with a manifest file, see Deploying with App Manifests.

Enabling tracing on containers

For applications and services that run on the containers, apart from environment settings, additional steps are required for tracing to work.

IL-rewriter and Instrumentation libraries for Linux containers

Add the nuget-package, and ensure that the environment variables are added for connection to the agent.

Setting up your container for automatic tracing

The following example shows a Docker file:

### your docker-image and application-build/-publish here

# set CoreCLR tracing environment variables
ENV DOTNET_STARTUP_HOOKS=/app/Instana.Tracing.Core.dll
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
ENV CORECLR_PROFILER_PATH=/app/instana_tracing/CoreProfiler.so

# provide agent-endpoint
ENV INSTANA_AGENT_HOST=host_or_other_container_name_or_ip
ENV INSTANA_AGENT_PORT=42699
ENTRYPOINT ["dotnet", "YourApp.dll","some","parameters"]

Enabling AutoProfile™

For .NET users, AutoProfile™ is available only for .NET applications that run on Linux. To enable AutoProfile™, add the following settings to your agent's configuration.yml file:

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

For more information, see Analyze Profiles.

Disabling 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 theconfiguration.yaml file with .NET tracing disabled.: configuration.yaml 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.

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.

Open Telemetry Integration

Instana provides additional .NET components for integrating with OpenTelemetry.

Troubleshooting

Sometimes your setup might not work at first. If this troubleshooting section does not answer your questions, contact support.

Environment variable not defined

Monitoring issue type: netcore_env_var_not_defined

One or more environment variables, which are necessary to activate the Instana .NET tracing, are not set on the .NET process. For a list of environment variables and values for tracing your .NET applications with Instana, see Enabling .NET tracing.

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.

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:

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.

Verify the tracer is installed

Check your application logs for the following entry:

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

This line indicates that the tracer is installed and running. You can see several entries with the following text:

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

If you do not see entries with the text in the example, ensure that the following prerequisites are met:

  • .NET tracing is enabled in the configuration.yaml file of the host agent.
  • All the required steps in the Tracing documentation are followed.

If your .NET application is running on Kubernetes, try Instana AutoTrace WebHook, which automatically and transparently adds .NET instrumentation to your pods.

If you are unable to fix the issue with other troubleshooting steps listed, try the following tips to resolve networking issues:

Verify the tracer can connect to the host agent

If .NET tracer is installed, verify that .NET process can connect to the host agent on the same host on port 42699. For more information on network visibility, see Network requirements for the Instana host agent.

In containerized platforms, network visibility issues between the containers of the application and Instana host agent might occur. Due to some overlay network setup, the container of the application might not connect to the Instana agent container on the same host.

.NET tracer might be using the wrong IP address or DNS name to communicate with the Instana agent. You can set .NET tracer to use a specific network address by using the INSTANA_AGENT_HOST environment variable.

In some instances, if you have set up your networking, the issue might not be with the network address, but the issue might be related to the port that is used by the tracer.

If the host agent listen on a different port other than 42699, remap the port for the tracer by using the INSTANA_AGENT_PORT environment variable.

If you are unable to troubleshoot the issues, open a support case.

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

Known issues

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.