Documentation forSolarWinds Observability SaaS

Install the .NET APM Library with OpenTelemetry Support

OpenTelemetry support has been expanded in the .NET APM Library version 6.2.0 release. This means when running the .NET APM Library with OpenTelemetry enabled, instrumentation supported by OpenTelemetry will produce spans. The APM library can also be configured to listen to additional ActivitySources.

Before you start

Verify your application will be able to enable OpenTelemetry support:

  • .NET Framework applications using .NET 4.6.2 and later, and .NET applications using .NET 8.0 and later are supported.

  • For versions of .NET and .NET Framework applications that are NOT supported, if OpenTelemetry has been enabled via configuration, the application will ignore the setting and the application will be instrumented the same as in previous releases.

  • For .NET 8+ self-contained applications, the SolarWindsAPM.OpenTelemetry.Agent NuGet package must be used. If the self-contained application produces a single file, then both the NuGet package and the corresponding Linux compressed package or Windows installer must be used.

  • For .NET 8+ applications, ensure that the profiler has not been disabled by the DOTNET_EnableDiagnostics environment variable. See the troubleshooting question, Did the SolarWinds Observability Profiler load successfully? for more information.

How do I enable OpenTelemetry for .NET Framework 4.6.2+ applications and .NET 8+ applications?

OpenTelemetry must be enabled in the APM Library by using one of the following configuration settings:

  1. Set OpenTelemetry to Enabled in the solarwinds_apm.config file:

    • <add key="OpenTelemetry" value="Enabled" />

  2. Set the SW_APM_OPEN_TELEMETRY environment variable to Enabled:

    • SW_APM_OPEN_TELEMETRY=Enabled

OpenTelemetry Version

The version of OpenTelemetry supported by the .NET APM Library is 1.15.0. See Release v1.15.0 · open-telemetry/opentelemetry-dotnet-instrumentation.

Manual Instrumentation

The .NET Library Instrumentation SDK is still supported with OpenTelemetry enabled. However, the recommend approach with the OpenTelemetry enabled APM library is to use an ActivitySource to add custom instrumentation to your application. The .NET OpenTelemetry repo contains instructions on how to do this, please see opentelemetry-dotnet-instrumentation/docs/manual-instrumentation.md at main · open-telemetry/opentelemetry-dotnet-instrumentation.

Code Profiling

The code profiling feature is not supported when OpenTelemetry is enabled.

Azure App Services

An Azure Site Extension has not been released yet with OpenTelemetry support enabled. To instrument an Azure App Service the SolarWindsAPM.OpenTelemetry.Agent NuGet package can be used. Please see SolarWindsAPM.OpenTelemetry.Agent NuGet package for more information.

Troubleshooting OpenTelemetry Support

What to do if OpenTelemetry support cannot be enabled?

When OpenTelemetry cannot be enabled, either your application will show a dependency error when it starts, or the log files (information where log files are located, see Where can library logs be found?) for your application may contain the message, Scope=SolarWindsApm.Instrumentation.OpenTelemetryManager Message=OpenTelemetry cannot be enabled.

If the logs contain a dependency error, then it is recommended to use the SolarWindsAPM.OpenTelemetry.Agent NuGet package or ensure your application is using version 10.0.0 or later of the required Microsoft Extensions and System.Diagnostics.DiagnosticSource NuGet packages.

Upgrading from Previous APM Library Versions to Version 6.1.0

Windows Installer and Linux Archives

The Windows Installer and Linux archives can be updated the same way as before. To enable OpenTelemetry support after upgrading, please follow the instructions above, Install the .NET APM Library with OpenTelemetry Support

If the application is a self-contained application and previously used the Windows Installer or a Linux archive, it must be updated to use the SolarWindsAPM.OpenTelemetry.Agent NuGet package instead, in order to enable OpenTelemetry support. If OpenTelemetry support is not enabled, the application will be instrumented the same as in previous versions.

SolarWindsAPM.Agent NuGet Package

The SolarWindsAPM.Agent NuGet package does not contain OpenTelemetry support, so an application must be changed to use the SolarWindsAPM.OpenTelemetry.Agent NuGet package to enable OpenTelemetry support. The SolarWindsAPM.Agent NuGet package does not require that it be added directly to the application project being instrumented. It could, for example, be added to a class library dependency of the application. However, the SolarWindsAPM.OpenTelemetry.Agent NuGet package must be added directly to the instrumented application project. Please see SolarWindsAPM.OpenTelemetry.Agent NuGet package for more information.