.NET APM Library with OpenTelemetry Support (Beta)

SolarWinds Observability SaaS beta features - The following content includes descriptions of features that are currently in beta and may change based on user feedback. All feature functionality is subject to change when the feature reaches maturity.

OpenTelemetry support has been added to the .NET APM Library version 6.0.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 applications using .NET 8.0 and later are supported.
.NET Framework applications are currently NOT supported. If OpenTelemetry has been enabled via configuration, .NET Framework applications will ignore the setting and the application will be instrumented the same as in previous releases.
For 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.
If your application or the dependencies of it use a version that is earlier than 9.0.0 of Microsoft .NET Extensions NuGet packages such as Microsoft.Extensions.Logging.Abstraction or Microsoft.Extensions.DependencyInjection.Abstractions, or the NuGet package System.Diagnostics.DiagnosticSource, then either those packages need to be updated to version 9.0.0 or later by adding them directly to your application. Otherwise, the SolarWindsAPM.OpenTelemetry.Agent NuGet package needs to be used.
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?

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:
  1. <add key="OpenTelemetry" value="Enabled" />
2. Set the SW_APM_OPEN_TELEMETRY environment variable to Enabled:
  1. SW_APM_OPEN_TELEMETRY=Enabled
When using the Linux compressed archive or the Windows installer with NON-IIS .NET Applications, the following .NET environment variables need to be set in addition to the other documented environment variables:
1. DOTNET_SHARED_STORE
2. DOTNET_ADDITIONAL_DEPS
  
  Files deployed by the Windows Installer:
  
  DOTNET_SHARED_STORE=C:\Program Files\SolarWinds\APM\dotnet\store
  
  DOTNET_ADDITIONAL_DEPS=C:\Program Files\SolarWinds\APM\dotnet\AdditionalDeps
  
  Linux Archive example:
  
  export DOTNET_SHARED_STORE=${HOME}/solarwinds/store
  
  export DOTNET_ADDITIONAL_DEPS=${HOME}/solarwinds/AdditionalDep
  
  This example assumes the Linux archive has been extracted to the ${HOME}/solarwinds directory.
  
  These environment variables are set by the Windows installer (SolarWindsAPM_DotNetAgent_Setup.exe) for IIS Instrumentation but need to be set if using NON-IIS Instrumentation or a Linux compressed archive. These environment variables should NOT be set at a system level, and should only be set for instrumented processes as they are .NET-defined environment variables. These environment variables do NOT need to be set when using the SolarWindsAPM.OpenTelemetry.Agent NuGet package.

OpenTelemetry Version

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

OpenTelemetry Environment Variables

OpenTelemetry instrumentations can be disabled using environment variables. The format of the environment variable is below and the value is set to false to disable the instrumentation.

OTEL_DOTNET_AUTO_TRACES_<instrumentation

ID>_INSTRUMENTATION_ENABLED=false

The OpenTelemetry documentation lists the different instrumentations that are supported. The .NET APM library supports the .NET 8+ instrumentations except for MONGODB. All of the instrumentations are enabled by default when OpenTelemetry is enabled except for KAFKA instrumentation, which must be enabled using the environment variable, OTEL_DOTNET_AUTO_TRACES_KAFKA_INSTRUMENTATION_ENABLED=true. See opentelemetry-dotnet-instrumentation/docs/config.md at main · open-telemetry/opentelemetry-dotnet-instrumentation for more information.

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.

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=Open Telemetry cannot be enabled.

These issues may either be due to a configuration issue or a dependency issue. If you are trying to instrument a NON-IIS application using the Windows Installer, or attempting to instrument an application with a Linux archive package, ensure that you have set the required environment variables DOTNET_SHARED_STORE and DOTNET_ADDITIONAL_DEPS, see above for setting these variables.

If setting the environment variables does not resolve the issue then it is recommended to use the SolarWindsAPM.OpenTelemetry.Agent NuGet package or ensure your application is using version 9.0.0 or later of the required Microsoft Extensions and System.Diagnostics.DiagnosticSource NuGet packages.

Upgrading from Previous APM Library Versions to Version 6.0.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, How do I Enable OpenTelemetry?

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 (Beta) for more information.

Search SolarWinds Support