Docs » .NET Core on Linux Instrumentation

.NET Core on Linux Instrumentation 🔗

Important

Before you start instrumenting your applications, review the information in APM PG Instrumentation Overview.

Generally speaking, adding tracing functionality to .NET Core 2.0+ applications can consist of incorporating a tracing system’s SDK for the creation and modification of spans to denote the state and flow of its execution. These spans are often started, annotated, and finished within the context of fielding and submitting requests. For web applications implementing domain-specific middleware that generate complex database queries, manual instrumentation can become burdensome. This is especially true for cross-team deployments where service owners and instrumentors don’t necessarily share memberships. Fortunately, there is a helpful library for auto-instrumenting your .NET Core applications: SignalFx Tracing for .NET Core.

The SignalFx Tracing library for .NET Core only supports Linux environments at this time. All instrumentations are currently in Beta.

The SignalFx Tracing library for .NET Core on Linux uses the Common Language Runtime’s (CLR) profiling API to automatically instrument the Intermediate Language (IL) of supported libraries and frameworks to trace their usage in real time. The utility can be installed via your system package manager after downloading the latest release:

# On Debian systems
$ dpkg -i signalfx-dotnet-tracing.deb

# On RPM-based systems
$ rpm -ivh signalfx-dotnet-tracing.rpm

# Directly from the release bundle:
$ tar -xf signalfx-dotnet-tracing.tar.gz -C /

Auto-instrumentation 🔗

As an implementation of a CLR profiler, the SignalFx Tracing library for .NET Core on Linux doesn’t require direct code modification or additional dependencies to enable its functionality. Instead, it provides an environment configuration that will instruct child CLR processes to slightly augment internal client and application functionality to report traced behavior to µAPM:

# After installing, configure the required environment variables:
$ source /opt/signalfx-dotnet-tracing/defaults.env

# Optionally create the default logging directory
$ mkdir /var/log/signalfx

# Then run your application as usual:
$ dotnet run

Specifically, the CLR needs the CORECLR_ENABLE_PROFILING=1 and CORECLR_PROFILER='{B4C89B0F-9908-4F73-9F59-0D77C5A06874}' environment variables to be set to connect to the desired profiler. Additional variables are also provided by the helper to specify the tracing library location and configuration preferences. All tracer-specific logs will be written to /var/log/signalfx if this directory is created beforehand.

Currently, the following libraries are provided with auto-instrumentation:

Library Supported Versions Nuget Package
ASP.NET Core MVC 2.0+ Microsoft.AspNet.Mvc.Core and built in
ADO.NET Supported .NET Core versions built in
HttpClient Supported .NET Core versions built in
MongoDb 2.1+ MongoDB.Driver.Core (dependency of MongoDb.Driver)
WebClient/WebRequest Supported .NET Core versions built in

Custom Instrumentation 🔗

While the benefits of auto-instrumentation are immediate, you are likely the best judge of the meaning and value behind the functionality of your application. In situations where more customized performance-monitoring capabilities are desired you can build upon the provided tracing functionality by modifying and adding to generated traces. The SignalFx Tracing library for .NET Core provides and registers an OpenTracing-compatible global tracer you can use to this end:

using OpenTracing;
using OpenTracing.Util;

namespace MyProject
{
    public class MyClass
    {
        public static void MyMethod()
        {
            // Obtain the automatically registered OpenTracing.Util.GlobalTracer instance
            var tracer = GlobalTracer.Instance;

            // Create an active span that will be automatically parented by any existing span in this context
            using (IScope scope = tracer.BuildSpan("MyTracedFunctionality").StartActive(finishSpanOnDispose: true))
            {
                var span = scope.Span;
                span.SetTag("MyImportantTag", "MyImportantValue");
                span.Log("My Important Log Statement");

                var ret = await MyAppFunctionality();

                span.SetTag("FunctionalityReturned", ret.ToString());
            }
        }
    }
}

In this way, the tracing insights provided by auto-instrumentation can act as the basis of any instrospective elements you add. By using both instrumentation approaches, you’ll be able to gain more of the benefits from µAPM PG and present a more detailed representation of the logic and functionality of your application, clients, and framework. OpenTracing versions 0.12.0+ are supported and the provided tracer offers a complete implementation of the OpenTracing API without additional dependencies.

For more information on our supported tracer please see the utility’s documentation.