The SignalFx Tracing Library for .NET provides an OpenTracing-compatible tracer and automatically configured instrumentations for popular .NET libraries and frameworks. It supports .NET Core 2.0+ on Linux and Windows and .NET Framework 4.5+ on Windows.

Where applicable, context propagation uses B3 headers.

The SignalFx-Tracing Library for .NET implements the Profiling API and should only require basic configuration of your application environment.

You can link individual log entries with trace IDs and span IDs associated with corresponding events. If your application uses a supported logger, enable trace injection to automatically include trace context in your application's logs. For more information, see Inject traces in logs.

There are known .NET Core runtime issues for version 2.1.0 and 2.1.2.

Use these environment variables to configure the tracing library:

After downloading the library, install the CLR Profiler and its components via your system's package manager.

1. Download the latest release of the library.
2. Install the CLR Profiler and its components with your system's package manager:

   # Use dpkg:
   $ dpkg -i signalfx-dotnet-tracing.deb
   
   # Use rpm:
   $ rpm -ivh signalfx-dotnet-tracing.rpm
   
   # Install directly from the release bundle:
   $ tar -xf signalfx-dotnet-tracing.tar.gz -C /
   
   # Install directly from the release bundle for musl-using systems (Alpine Linux):
   $ tar -xf signalfx-dotnet-tracing-musl.tar.gz -C /

3. Configure the required environment variables:

   $ source /opt/signalfx-dotnet-tracing/defaults.env

4. Set the service name:

   $ export SIGNALFX_SERVICE_NAME='MyCoreService'

5. Set the endpoint of a Smart Agent or OpenTelemetry Collector:

   $ export SIGNALFX_ENDPOINT_URL='http://<YourSmartAgentOrCollector>:9080/v1/trace'

6. Optionally, enable trace injection in logs:

   $ export SIGNALFX_LOGS_INJECTION=true

7. Optionally, create the default logging directory:

   $ source /opt/signalfx-dotnet-tracing/createLogPath.sh

8. Run your application:

   $ dotnet run

The CLR Profiler can be added to Docker images using any of the provided packages, below an example of adding it to an Azure Function image:

# These first lines are from the example but in principle could be
# build outside of docker, but they make the example clear showing
# what should be copied to the Azure VM machine.
FROM mcr.microsoft.com/dotnet/core/sdk:3.1 AS installer-env

COPY . /src/dotnet-function-app
RUN cd /src/dotnet-function-app && \
    mkdir -p /home/site/wwwroot && \
    dotnet publish *.csproj --output /home/site/wwwroot

FROM mcr.microsoft.com/azure-functions/dotnet:3.0
ENV AzureWebJobsScriptRoot=/home/site/wwwroot \
    AzureFunctionsJobHost__Logging__Console__IsEnabled=true

# Custom lines Adding the SignalFx Auto-Instrumentation to the image:

# First install the package. This example downloads the latest version
# alternatively download a specific version or use a local copy.
ADD https://github.com/signalfx/signalfx-dotnet-tracing/releases/latest/download/signalfx-dotnet-tracing.deb  /signalfx-package/signalfx-dotnet-tracing.deb
RUN dpkg -i /signalfx-package/signalfx-dotnet-tracing.deb
RUN rm -rf /signalfx-package

# Prepare the log directory (useful for local tests).
RUN mkdir -p /var/log/signalfx/dotnet && \
    chmod a+rwx /var/log/signalfx/dotnet

# Set the required environment variables. In the case of Azure Functions more
# can be set either here or on the application settings. 
ENV CORECLR_ENABLE_PROFILING=1 \
    CORECLR_PROFILER='{B4C89B0F-9908-4F73-9F59-0D77C5A06874}' \
    CORECLR_PROFILER_PATH=/opt/signalfx-dotnet-tracing/SignalFx.Tracing.ClrProfiler.Native.so \
    SIGNALFX_INTEGRATIONS=/opt/signalfx-dotnet-tracing/integrations.json \
    SIGNALFX_DOTNET_TRACER_HOME=/opt/signalfx-dotnet-tracing
# End of SignalFx customization.

COPY --from=installer-env ["/home/site/wwwroot", "/home/site/wwwroot"]

For more information on how to configure a custom Linux Azure Function image refer to the Azure documentation.

1. Install the CLR Profiler using an installer file (.msi file) from the latest release. Choose the installer (x64 or x86) according to the architecture of the application you're instrumenting.
2. Configure the required environment variables to enable the CLR Profiler:
   • For .NET Framework applications:

   set COR_ENABLE_PROFILING=1
   set COR_PROFILER={B4C89B0F-9908-4F73-9F59-0D77C5A06874} 

   • For .NET Core applications:

   set CORECLR_ENABLE_PROFILING=1
   set CORECLR_PROFILER={B4C89B0F-9908-4F73-9F59-0D77C5A06874}

3. Set the "service name" that better describes your application:

   set SIGNALFX_SERVICE_NAME=MyServiceName

4. Set the endpoint of a Smart Agent or OpenTelemetry Collector that will forward the trace data:

   set SIGNALFX_ENDPOINT_URL='http://<YourSmartAgentOrCollector>:9080/v1/trace'

5. Optionally, enable trace injection in logs:

   $ export SIGNALFX_LOGS_INJECTION=true

6. Restart your application ensuring that all environment variables above are properly configured. If you need to check the environment variables for a process use a tool like Process Explorer.

You can build upon the provided tracing functionality by modifying and adding to automatically generated traces. The SignalFx Tracing library for .NET provides and registers an OpenTracing-compatible global tracer you can use.

OpenTracing versions 0.11.0+ are supported and the provided tracer offers a complete implementation of the OpenTracing API.

The auto-instrumentation provides a base you can build on by adding your own custom instrumentation. By using both instrumentation approaches, you'll be able to present a more detailed representation of the logic and functionality of your application, clients, and framework.

1. Add the OpenTracing dependency to your project:

   <PackageReference Include="OpenTracing" Version="0.12.1" />

2. Obtain the OpenTracing.Util.GlobalTracer instance and create spans that automatically become child spans of any existing spans in the same context:

   using OpenTracing;
   using OpenTracing.Util;
   
   namespace MyProject
   {
       public class MyClass
       {
           public static async 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());
               }
           }
       }
   }

When using manual instrumentation it is possible to set different service names under the same process. This is disabled by default but can be enabled by configuring the environment variable SIGNALFX_SERVICE_NAME_PER_SPAN_ENABLED to true and following the OpenTracing semantic conventions by setting the tag service.name to the desired service name.

For more examples and information on how to do manual instrumentation see:

• https://github.com/signalfx/tracing-examples/tree/master/dotnet-manual-instrumentation
• https://github.com/signalfx/tracing-examples/tree/master/signalfx-tracing/signalfx-dotnet-tracing

The SignalFx-Tracing Library for .NET is a fork of the .NET Tracer for Datadog APM that has been modified to provide Zipkin v2 JSON formatting, a complete OpenTracing API implementation, B3 propagation, and properly annotated trace data for handling by SignalFx Microservices APM.