Install the .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
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 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.

How to set the environment variables in IIS:

The environment variables can either be set for specific application pools in IIS or in the registry. Setting environment variables in the registry results in the environment variables being set for all application pools in IIS.

The command examples in this section assume the installed directory for the SolarWinds Observability .NET APM Library is C:\Program Files\SolarWinds\APM\dotnet. Ensure you update the installed directory if the library has been installed on a different system drive.

How to set the environment variables for a specific application pool:

You can use the appcmd.exe command line tool to add and remove application-pool-specific environment variables. This tool is located in the %windir%\System32\inetsrv folder.

Use the following commands to add the DOTNET_SHARED_STORE and DOTNET_ADDITIONAL_DEPS environment variables:
```
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='app_pool_name'].environmentVariables.[name='DOTNET_SHARED_STORE',value='C:\Program Files\SolarWinds\APM\dotnet\store']" /commit:apphost 
appcmd.exe set config -section:system.applicationHost/applicationPools /+"[name='app_pool_name'].environmentVariables.[name='DOTNET_ADDITIONAL_DEPS',value='C:\Program Files\SolarWinds\APM\dotnet\AdditionalDeps']" /commit:apphost
```
Replace app_pool_name with the name of your application pool.

For detailed information on how to set and remove environment variables for application pools, see SolarWinds Observability | Configure the .NET Library.

How to set the environment variables for IIS in the registry:

These are the registry entries that the DOTNET_SHARED_STORE and DOTNET_ADDITIONAL_DEPS environment variables need to be added to:

HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\WAS\Environment
HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\W3SVC\Environment

Use the following commands to update the registry entries with the additional DOTNET_SHARED_STORE and DOTNET_ADDITIONAL_DEPS environment variables when only IIS .NET Instrumentation is enabled and IIS .NET Framework Instrumentation is not enabled:

REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\WAS" /v Environment /t REG_MULTI_SZ /d "SW_APM_HOME_DOTNET=C:\Program Files\SolarWinds\APM\dotnet\\0CORECLR_ENABLE_PROFILING=1\0CORECLR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}\0DOTNET_ADDITIONAL_DEPS=C:\Program Files\SolarWinds\APM\dotnet\AdditionalDeps\0DOTNET_SHARED_STORE=C:\Program Files\SolarWinds\APM\dotnet\store" /f 
REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\W3SVC" /v Environment /t REG_MULTI_SZ /d "SW_APM_HOME_DOTNET=C:\Program Files\SolarWinds\APM\dotnet\\0CORECLR_ENABLE_PROFILING=1\0CORECLR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}\0DOTNET_ADDITIONAL_DEPS=C:\Program Files\SolarWinds\APM\dotnet\AdditionalDeps\0DOTNET_SHARED_STORE=C:\Program Files\SolarWinds\APM\dotnet\store" /f

Use the following commands to update the registry entries with the additional DOTNET_SHARED_STORE and DOTNET_ADDITIONAL_DEPS environment variables when both IIS .NET Framework and IIS .NET Instrumentation are enabled:

REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\WAS" /v Environment /t REG_MULTI_SZ /d "COR_ENABLE_PROFILING=1\0COR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}\0SW_APM_HOME_DOTNET=C:\Program Files\SolarWinds\APM\dotnet\\0CORECLR_ENABLE_PROFILING=1\0CORECLR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}\0DOTNET_ADDITIONAL_DEPS=C:\Program Files\SolarWinds\APM\dotnet\AdditionalDeps\0DOTNET_SHARED_STORE=C:\Program Files\SolarWinds\APM\dotnet\store" /f 
REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\W3SVC" /v Environment /t REG_MULTI_SZ /d "COR_ENABLE_PROFILING=1\0COR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}\0SW_APM_HOME_DOTNET=C:\Program Files\SolarWinds\APM\dotnet\\0CORECLR_ENABLE_PROFILING=1\0CORECLR_PROFILER={AAAA7777-11FE-4F94-8EDA-312C0EDF4141}\0DOTNET_ADDITIONAL_DEPS=C:\Program Files\SolarWinds\APM\dotnet\AdditionalDeps\0DOTNET_SHARED_STORE=C:\Program Files\SolarWinds\APM\dotnet\store" /f

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

This may be due to a configuration issue or a dependency issue. 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 Configure the SolarWindsAPM.OpenTelemetry.Agent NuGet package (Beta) for more information.

Search SolarWinds Support