Monitoring .NET Core

Supported Libraries & Frameworks for tracing

Instana supports monitoring of applications running on the .NET Core Framework beginning with version 2.0.

Sensor Data Collection (currently only available on Windows)

Health Signatures

For each sensor, there is a curated knowledgebase of health signatures that are evaluated continuously against the 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 Core sensor, see the Built-in events reference.

Tracing

This page describes how to setup .NET Core Tracing for your environment and how it works.

Getting metrics for .NET Core apps on Linux

Instana supports getting metrics for .NET Core apps running on Linux, but this needs some configuration. Specifically the app needs to be deployed with the Instana.Tracing.Core nuget-package, starting from version 1.1.34.

This is the same package as you would use for tracing (see below).

After having added the package and publishing your app, you can set the following environment-settings to let the application report metrics to a running agent.

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

Now you're all set and your application should report metrics. When successfully installed, you will see additional output in your application's standard-out:

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

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

How Tracing Works

Before any application will be actively instrumented and traced by the extension, you need to provide the environment-settings which .NET Core needs to load the profiling component. If sensor and tracing are enabled for your host, all you need to do is to add the nuget package for Instana-Tracing to your application and set the appropriate environment-settings.

Instana supports both non and self-contained .NET Core applications, although the latter requires the Instana.Tracing.Core nuget-package, version 1.1.34 or above, and the following environment variable to be specified:

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

For apps running in 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 Core applications with Instana, across an entire Kubernetes cluster.

If you elect to install the Instana AutoTrace WebHook on your Kubernetes clusters, you have no need to perform any manual step to trace any of your .NET Core applications running in those clusters.

If your .NET Core application and the Instana Agent are managed by Kubernetes, please check the documentation on Kubernetes network access for information about the required configuration in this setup.

For apps running on Linux (except Alpine)

Install the package Instana.Tracing.Core.Rewriter.Linux. You can either add it to your project or only add it right before publishing. Normally we suggest adding it before publishing, so that developers don't have to deal with the package at all.

You then have to provide these environment-settings to your process before starting it:

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

Additionally, if your app is running inside a container, you have to provide an environment-setting which tells your process how it can 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)

For apps running on Alpine Linux

Install the package Instana.Tracing.Core.Rewriter.Alpine. You can either add it to your project or only add it right before publishing. Normally we suggest adding it before publishing, so that developers don't have to deal with the package at all.

You then have to provide these environment-settings to your process before starting it:

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

Additionally, if your app is running inside a container, you have to provide an environment-setting which tells your process how it can 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)

For apps running on Windows

Install the package Instana.Tracing.Core.Rewriter.Windows. You can either add it to your project or only add it right before publishing. Normally we suggest adding it before publishing, so that developers don't have to deal with the package at all.

You then have to provide these environment-settings to your process before starting it:

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

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

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

For apps running on Cloud Foundry

Note: This section assumes that the Instana agent is currently running on the Diego cells of the Cloud Foundry foundation. For information on the setup of Instana agents and the related Cloud Foundry or Pivotal Platform functionality, see our Cloud Foundry and Pivotal Platform documentation.

On Cloud Foundry, to monitor non self-contained .NET Core 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 DotNet Core application for publication, run this command:

dotnet publish -c Release

(You may want to use a different configuration, rather than Release, in which case you need to adjust the manifest below accordingly.)

• 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"

Note: Depending on the .NET Core SDK being used and the configuration name passed to the dotnet publish -c Release via the -c flag (Release in the above example), the value for the path variable may change.

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

cf push

Note: 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 the Deploying with App Manifests documentation.

Tracing in containers

If you choose to run your applications and services inside containers, you will have to provide the environment-settings above as discussed. But there is more to be done in order to make tracing work.

IL-rewriter and Instrumentation libraries for Linux containers

You have to add the nuget-package as described above, making sure your add the environment-settings for the connection to the agent.

Setting up your container for automatic tracing

Here is an example of a docker-file which displays these steps:

### 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"]

Disabling Tracing for .NET Core

When you want to stop tracing of .NET applications for whatever reason, you can simply do so by changing the configuration file back to its initial state, or by just setting the corresponding flag to "false."

configuration.yaml with .NET-Tracing disabled

# CLR Tracing
com.instana.plugin.clr:
  tracing:
    enabled: false

After changing the config back, you will have to restart the agent for the changes to take effect.

Due to the nature of how the Profiling API works, disabling tracing in the agent will not remove / detach the profiler from processes that have been started with tracing enabled (i.e., your worker-processes). To make sure the profiler is not loaded into the application, you have to restart the host-process.

Troubleshooting

There might be cases where your setup does not work at first. If this troubleshooting section does not answer the questions you have, contact our support team and let us know, so that we can help you and update our documentation accordingly.

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 Core tracing, are not set on the .NET Core process. Please refer to the How Tracing Works section for a list of environment variables and the respective values you need to set for tracing your .NET Core applications with Instana.

Environment variable has an invalid value

Monitoring issue type: netcore_env_var_invalid_value

At least one environment variable that is necessary to activate the Instana .NET Core tracing, does not have the right value. (Depending on which environment variables are missing, you may still see metrics in the Instana dashboards for your .NET Core application, but definitely not traces.) Please refer to the How Tracing Works section for a list of environment variables and the respective values you need to set for tracing your .NET Core applications with Instana.

Also, it might be the case that the reason for the environment variable to have the wrong value is the presence of another APM tool. (In terms of hooking into the .NET Core runtime, the mechanisms the various APM use are pretty similar.) If we recognize this situation, you will see it in the message in the Instana user interface. Before Instana can trace your .NET Core application, you will have turn off the other APM agent, at least insofar .NET Core monitoring is concerned; for how to do that, refer to the other APM tool's documentation.

Sensor not Connected

Monitoring issue type: netcore_sensor_not_connected

The Instana host agent does not receive the acknowledgment from the .NET Core process that it is instrumented with Instana. The setup looks right, or you should have recevied either an Environment variable has an invalid value or an Environment variable not defined, and the host agent does not detect any obvious reason for it.

The steps to troubleshoot this issue are the following:

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

Verify the tracer is installed

Check in 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 means that the tracer is installed and running, and you will also see several entries with the following text:

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

If you do not see these entries, check that:

1. the .NET Core tracing has been enabled in the host agent's configuration.yaml
2. you followed all the required steps in the Tracing documentation

Alternatively, if your .NET Core application runs in Kubernetes, you should try out the Instana AutoTrace WebHook, which automatically and transparently adds the .NET Core instrumentation to your pods.

Otherwise, it is extremely likely a networking issues, described in the following section.

Verify the tracer can connect to the host agent

If the .NET Core tracer is installed (refer to he previous section), verify that the .NET Core process can connect to the host agent on the same host on port 42699. For more information on the required network visibility, refer to the Network requirements documentation for the Instana host agent.

What we see increasingly often, is that in containerized platforms either there are network visibility issues between the container with the application to be traced and the container of the Instana host agent; another issue of the same kind, due to some overlay network setup, the container of the application to be traced does not connect to the Instana agent container on the same host.

Often the problem is that the .NET Core tracer is using the wrong ip address or DNS name to talk to the Instana agent. You can instruct the .NET Core tracer to user a specific network address via the INSTANA_AGENT_HOST environment-variable.

In very few cases, we have seen customers that set up their networking so that the problem was not the network address, but the port the tracer uses. In case you need a port remapping, because the host agent does not listen on port 42699 but something else, you can instruct the tracer to use a different port via the INSTANA_AGENT_PORT environment variable.

In case none of the above helps you troubleshoot the issue, please open a Support Ticket.

Prolog of the IL-Rewriter

When the IL-Rewriter gets loaded into your application, it will write three characteristic lines to the standard-ouput of your application. If you have the feeling something is not working, make sure at first, that you find these lines in your appliction's log:

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