ℹ️  SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.

The SignalFx Instrumentation for .NET provides automatic instrumentations for popular .NET libraries and frameworks.

The SignalFx Instrumentation for .NET is a .NET Profiler which instruments supported libraries and frameworks with bytecode manipulation to capture and send telemetry data (metrics, traces, and logs).

By default:

• all spans are sampled and reported,
• B3 headers and W3C headers are used for context propagation,
• Zipkin trace exporter is used to send spans as JSON in the Zipkin v2 format.

The SignalFx Instrumentation for .NET registers an OpenTracing GlobalTracer so you can support existing custom instrumentation or add custom instrumentation to your application later.

The conventions used by SignalFx Instrumentation for .NET are inspired by the OpenTelemetry Trace Semantic Conventions. OpenTelemetry Collector Contrib with its Zipkin Receiver can be used to receive, process and export telemetry data. However, until OpenTelemetry .NET Auto-Instrumentation is not useable, SignalFx Instrumentation for .NET is not able to correlate the spans created with OpenTelemetry .NET and ActivitySource.

• .NET Core 3.1, .NET 5.0 and higher on Windows and Linux
• .NET Framework 4.6.1 and higher on Windows

See instrumented-libraries.md to know for which libraries and frameworks are instrumented.

Make sure you set up the Splunk OpenTelemtry Collector to receive telemetry data.

Run in PowerShell as administrator:

# signalfx-dotnet-tracing github repository API
$api = "https://api.github.com/repos/signalfx/signalfx-dotnet-tracing/releases/latest"

# determine OS architecture
$os_bits = (Get-CimInstance Win32_OperatingSystem).OSArchitecture
$os_arch = (&{If($os_bits -eq "64-bit") {"x64"} Else {"x86"}})

# File pattern to search for
$pattern = "signalfx-dotnet-tracing-*-$os_arch.msi"

# Find latest MSI to download
$download = (Invoke-WebRequest $api | ConvertFrom-Json).assets | Where-Object { $_.name -like $pattern } | Select-Object -Property browser_download_url,name

# Download installer MSI to Temp
$msi = Join-Path $env:temp $download.name
Invoke-WebRequest -Uri $download.browser_download_url -OutFile $msi

# Install downloaded MSI
Start-Process msiexec.exe -Wait -ArgumentList "/I $msi /quiet"

# Cleanup
Remove-Item $msi

You can find the latest installation packages on the Releases page.

On Linux, after the installation, you can optionally create the log directory:

/opt/signalfx/createLogPath.sh

Before running the application, set the following environment variables:

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

Example in PowerShell:

$Env:COR_ENABLE_PROFILING = "1"                                   # Enable the .NET Framework Profiler
$Env:COR_PROFILER = "{B4C89B0F-9908-4F73-9F59-0D77C5A06874}"      # Select the .NET Framework Profiler
$Env:CORECLR_ENABLE_PROFILING = "1"                               # Enable the .NET (Core) Profiler
$Env:CORECLR_PROFILER = "{B4C89B0F-9908-4F73-9F59-0D77C5A06874}"  # Select the .NET (Core) Profiler
# Now the auto-instrumentation is configured in this shell session.
# You can set additional settings and run your application, for example:
$Env:SIGNALFX_SERVICE_NAME = "my-service-name"                    # Set the service name
$Env:SIGNALFX_ENV = "production"                                  # Set the environment name
dotnet run                                                        # Run your application                                                     

Before running the application, set the following environment variables:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={B4C89B0F-9908-4F73-9F59-0D77C5A06874}
CORECLR_PROFILER_PATH=/opt/signalfx/SignalFx.Tracing.ClrProfiler.Native.so
SIGNALFX_DOTNET_TRACER_HOME=/opt/signalfx

Example in Bash:

export CORECLR_ENABLE_PROFILING="1"                                                 # Enable the .NET (Core) Profiler
export CORECLR_PROFILER="{B4C89B0F-9908-4F73-9F59-0D77C5A06874}"                    # Select the .NET (Core) Profiler
export CORECLR_PROFILER_PATH="/opt/signalfx/SignalFx.Tracing.ClrProfiler.Native.so" # Select the .NET (Core) Profiler file path
export SIGNALFX_DOTNET_TRACER_HOME="/opt/signalfx"                                  # Select the SignalFx Instrumentation for .NET home folder
# Now the auto-instrumentation is configured in this shell session.
# You can set additional settings and run your application, for example:
export SIGNALFX_SERVICE_NAME="my-service-name"  # Set the service name
export SIGNALFX_ENV="production"                # Set the environment name
dotnet run                                      # Run your application 

See windows-service-instrumentation.md.

See iis-instrumentation.md.

See azure-instrumentation.md.

See advanced-config.md.

See manual-instrumentation.md.

See correlating-traces-with-logs.md.

See metrics.md

See always-on-profiling.md

See troubleshooting.md.

Please read CONTRIBUTING.md before creating an issue or a pull request.

The SignalFx Instrumentation for .NET is a redistribution of the .NET Tracer for Datadog APM. It is licensed under the terms of the Apache Software License version 2.0. For more details, see the license file.

The third-party dependencies list can be found here.