.NET Core

Supported Versions

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

ADO drivers
Redis (ServiceStack)
PostgreSQL (npgsql)
RabbitMQ (5.x)
ILogger based log-solutions

Sensor Data Collection (currently only available on Windows)

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

Health Signatures

  • Garbage Collection Activity


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

    enabled: true
    enabled: true


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, these settings will be automatically applied and thus all processes running on CoreCLR will be potentially traced (based on whether they are using technology we currently support). However, if you are running applications in containers, you will need to provide these settings to your container.

# Linux

# Windows

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. We encourage you to use the Nuget-package we offer for both Linux and Windows-Containers on Nuget.org.

IL-rewriter and Instrumentation libraries for Linux containers

You can get the bundle for automatic tracing from nuget.org: https://www.nuget.org/packages/Instana.Profiler.Linux.Bundled.Refs/

When adding this package to your project, there will be a sub-folder instana_tracing which contains all the necessary files for code-instrumentation (that is the profiler + instrumentation-advices as a json-file). It will also add references to libraries which your instrumented code will call into (Instana.Tracing.Core, Instana.Tracing-Api, Instana.Tracing.Core.Instrumentation). You do not have to change any of your code. All you have to do is to provide the discusses environment-variables to the runtime and your code will be instrumented automatically.

Setting up your container for automatic tracing

In order to make the container use the tracing capabilities included through the nuget-package, you will have to meet some prerequisites, which are displayed in the following example. These steps are:

  • Provide the environment variables for CoreCLR tracing (see above)
  • Provide an endpoint-mapping, which let’s the container communicate with the agent
  • make sure that connections from inside the container to the agent are allowed on ports 42699 (meta-data) and 16819 (traces)
  • install libc++1 inside the container for the IL-rewriter to work

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

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

# install libc++1
RUN apt-get update && apt-get install libc++1

# set CoreCLR tracing environment variables
ENV CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
ENV CORECLR_PROFILER_PATH=/app/instana_tracing/CoreProfiler.so

# provide agent-endpoint
ENV INSTANA_AGENT_MAPPING=host_or_other_container_name_or_ip: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
    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.


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 that libc++1 has been installed inside the container
  • 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_MAPPING environment-variable has been set for the application (docker-file)
  • make sure the host denoted in INSTANA_AGENT_MAPPING is reachable on ports 42699 and 16819 from inside the container
  • make sure the agent is running
  • make sure .NET Core tracing has been enabled in the agent’s configuration.yaml