.NET Core

Supported Versions

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

HTTP-Server
ASP.NET Core
HTTP-Client
HttpClient
HttpWebRequest
Databases
ADO drivers
Cassandra
Redis (ServiceStack)
PostgreSQL (npgsql)
Azure Cosmos Client (3.1.1, 3.3.1)
Azure DocumentDB Core (2.5.1)
Messaging
RabbitMQ (5.x)
Logging
ILogger based log-solutions
Serilog

Sensor Data Collection (currently only available on Windows)

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

Health Signatures

  • Garbage Collection Activity

Tracing

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

Agent Configuration

The sensor for .NET Core applications and the corresponding tracing extensions need to be enabled by applying the following changes to your agent’s configuration-file.

configuration.yaml with .NET-Tracing enabled

com.instana.plugin.netcore:
  sensor:
    enabled: true
  tracing:
    enabled: true

Dependencies

To use tracing on Linux, our profiler requires libc++1 to be installed. On Ubuntu you can use something simple as:

apt-get install libc++1

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.

For apps running on Linux (except Alpine)

Install the package Instana.Profiler.Linux.Bundled.Refs. 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={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:

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

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 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. Here are some advices that we want to give you, to make sure everything is working correctly - or why it isn’t. 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.

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

Agent is not running or not reachable

In case the tracing libraries have been loaded and your application has been executing code that should lead to traces, it will try to contact the agent. The first action it wil take is to announce itself to the agent. If t his fails, you will find this message in the applications-log:

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

You will also find several entries with the following text:

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

In this case please take the following actions

*make sure that INSTANA_AGENT_PORT and INSTANA_AGENT_HOST environment-variable has been set for the application (docker-file) *make sure the host denoted in INSTANA_AGENT_HOST is reachable on the port configured in INSTANA_AGENT_PORT inside the container *make sure the agent is running *make sure .NET Core tracing has been enabled in the agent’s configuration.yaml