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

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

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

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

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.Profiler.Linux.Bundled.Refs
  • 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
DOTNET_STARTUP_HOOKS=/app/instana_tracing/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. 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