Documentation forSolarWinds Observability SaaS

Install the .NET Library on Azure App Service

Application Insights must be disabled to use the SolarWinds Observability SaaS extension.

The .NET Library provides detailed insight and distributed tracing for .NET Framework and .NET 6+ applications running in Azure App Service. The .NET Library can be installed using the SolarWinds Observability SaaS Azure Site Extension or using the SolarWindsAPM.Agent NuGet package.

Before you start

Verify the following to ensure the library can collect and transmit data:

  • The platform where your APM library will be installed is supported.

  • Your application components are supported by the library.

  • Your firewall configuration permits TCP/HTTPS/TLS outbound connections to apm.collector.xx-yy.cloud.solarwinds.com (where xx-yy is determined by the URL you use to access SolarWinds Observability SaaS, described in Data centers and endpoint URIs) using port 443. See Firewall or access control requirements.

    If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Do not run other APM libraries alongside the SolarWinds Observability .NET Library. See Do you have another profiler installed?.

Install the .NET Library using the SolarWindsAPM Azure AppServices Site Extension (Windows only)

The .NET Library site extension supports .NET Framework aspnet|v4.8 runtime and .NET 6+ Azure App Services.

To install the SolarWinds Observability .NET Library SolarWindsAPM Azure AppServices Site Extension Package in your Azure Web App:

  1. Ensure that Application Insights is disabled. This can be checked under the Settings > Application Insights section for the App Service.

  2. In the Development Tools section of the Azure Web App, click Extensions.

  3. Click the Add button and select SolarWindsAPM Azure AppServices Site Extension from the list.

  4. To configure the .NET Library, navigate to the Application Settings in the configuration settings. Add the following application global environment variables:

    For each path provided in these tables, replace <system_drive> with your the system drive of your App Service (for example, C). To determine the drive of your App Service, open the App Service Console window or open CMD or PowerShell from the Debug console.

    .NET 6+

    Environment variable Environment variable value
    SW_APM_SERVICE_KEY  

    (Optional) This overrides what is set in the solarwinds_apm.config file. 

    The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

    It should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

    The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.
    SW_APM_HOME_DOTNET <system_drive>:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM  
    SW_APM_COLLECTOR

    This overrides what is set for the ApmCollector key in the solarwinds_apm.config file.

    The SW_APM_COLLECTOR setting is optional and ensures the correct endpoint URI is used when sending data to the SolarWinds APM collector. To determine the correct endpoint for your SolarWinds APM collector, see Data centers and endpoint URIs.
    CORECLR_ENABLE_PROFILING 1
    CORECLR_PROFILER {AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
    CORECLR_PROFILER_PATH_32 <system_drive>:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM\x86\solarwinds_apm_profiler.dll
    CORECLR_PROFILER_PATH_64 <system_drive>:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM\x64\solarwinds_apm_profiler.dll

    .NET Framework

    Environment variable  Environment variable value 
    SW_APM_SERVICE_KEY  

    (Optional) This overrides what is set in the solarwinds_apm.config file. 

    The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

    It should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

    The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.
    SW_APM_HOME_DOTNET   <system_drive>:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM
    SW_APM_COLLECTOR

    This overrides what is set for the ApmCollector key in the solarwinds_apm.config file.

    The SW_APM_COLLECTOR setting is optional and ensures the correct endpoint URI is used when sending data to the SolarWinds APM collector. To determine the correct endpoint for your SolarWinds APM collector, see Data centers and endpoint URIs.
    COR_ENABLE_PROFILING   1
    COR_PROFILER   {AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
    COR_PROFILER_PATH_32   <system_drive>:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM\x86\solarwinds_apm_profiler.dll
    COR_PROFILER_PATH_64   <system_drive>:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM\x64\solarwinds_apm_profiler.dll
    COMPLUS_LoaderOptimization 1

    The .NET Library is installed in the <system_drive>:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM directory, where <system_drive> is the system drive of your App Service (for example, C).

    For both .NET 6+ and .NET Framework applications, log files can be found in <system_drive>:\home\LogFiles\SolarWinds.

  5. Set the Service key in the <system_drive>:\home\SiteExtensions\SolarWindsAPM.Agent.AzureAppServices.Extension\SolarWindsAPM\solarwinds_apm.config file. Alternatively, the Service key can be set using the environment variable SW_APM_SERVICE_KEY.

    Replace <system_drive> with your the system drive of your App Service (for example, C).

    During an extension upgrade, the solarwinds_apm.config file is replaced with a new file and any changes made to the solarwinds_apm.config file are lost. Before upgrading the extension, back up the solarwinds_apm.config file to another location. After upgrading, the solarwinds_apm.config file can be restored by replacing the new solarwinds_apm.config file with the backed up copy.

  6. Restart the Web App application.

Uninstall the .NET Library from Azure AppServices

To disable the .NET Library instead of uninstalling the library, see Disable the .NET Library.

To uninstall the .NET Library from the Azure AppServices:

  1. From the Azure Web App, remove the .NET Library environment variables that were previously added. Navigate to the Application Settings in the configuration settings and remove the following environment variables:
    • .NET 6+
      • SW_APM_HOME_DOTNET
      • CORECLR_ENABLE_PROFILING
      • CORECLR_PROFILER
      • CORECLR_PROFILER_PATH_32
      • CORECLR_PROFILER_PATH_64
    • .NET Framework
      • SW_APM_HOME_DOTNET
      • COR_ENABLE_PROFILING
      • COR_PROFILER
      • COR_PROFILER_PATH_32
      • COR_PROFILER_PATH_64
      • COMPLUS_LoaderOptimization
  2. Restart the Web App application.
  3. In the Azure Web App, in the Development Tools section, click Extensions.
  4. Select the SolarWindsAPM Azure AppServices Site Extension, and click the Delete button.

Install the .NET Library using the SolarWindsAPM.Agent NuGet package (Windows and Linux)

The .NET Library NuGet package supports .NET Framework aspnet|v4.8 runtime and .NET 6+ Azure App Services.

  1. Ensure that Application Insights is disabled. This can be checked under the Settings > Application Insights section for the App Service.

  2. Open the official SolarWindsAPM.Agent NuGet package page to view details about the latest release of the library, and add the library using your preferred package installation method.

    To add the library to your package using the .NET command line, enter the following at the command line:

    dotnet add ProjectName.csproj package SolarWindsAPM.Agent --version VersionNumber

    Replace ProjectName with your project's file name and VersionNumber with the latest available version number found on the official SolarWindsAPM.Agent Nuget package page.

  3. Publish the Web App to Azure. The following is an example of a publish command:

    dotnet publish ProjectName.csproj /p:PublishProfile='ProfileName'

    Where ProjectName is your project's file name and ProfileName is a unique name to represent the publish profile.

  4. To configure the SolarWinds Observability .NET Library, navigate to the Application Settings in the configuration settings. Add the following application global environment variables:

    For Windows

    For each path provided in these tables, replace <system_drive> with the system drive of your App Service (for example, C). To determine the drive of your App Service, either open the App Service Console window, or go to the Advanced tools and locate the Debug console to open CMD or PowerShell.

    .NET 6+

    Environment variable  Environment variable value 
    SW_APM_SERVICE_KEY  

    (Optional) This overrides what is set in the solarwinds_apm.config file. 

    The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

    It should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

    The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.
    SW_APM_HOME_DOTNET  

    <system_drive>:\home\site\wwwroot\SolarWindsAPM

    CORECLR_ENABLE_PROFILING   1
    CORECLR_PROFILER   {AAAA7777-11FE-4F94-8EDA-312C0EDF4141} 
    CORECLR_PROFILER_PATH_32   <system_drive>:\home\site\wwwroot\SolarWindsAPM\x86\solarwinds_apm_profiler.dll
    CORECLR_PROFILER_PATH_64   <system_drive>:\home\site\wwwroot\SolarWindsAPM\x64\solarwinds_apm_profiler.dll

    For .NET 6+ applications, the .NET Library is installed in the following location: <system_drive>:\home\site\wwwroot\SolarWindsAPM.

    For both .NET 6+ and .NET Framework applications, log files can be found in <system_drive>:\home\LogFiles\SolarWinds.

    .NET Framework

    Environment variable  Environment variable value 
    SW_APM_SERVICE_KEY  

    (Optional) This overrides what is set in the solarwinds_apm.config file. 

    The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

    It should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

    The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.
    SW_APM_HOME_DOTNET   <system_drive>:\home\site\wwwroot\bin\SolarWindsAPM 
    COR_ENABLE_PROFILING   1 
    COR_PROFILER   {AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
    COR_PROFILER_PATH_32   <system_drive>:\home\site\wwwroot\bin\SolarWindsAPM\x86\solarwinds_apm_profiler.dll
    COR_PROFILER_PATH_64   <system_drive>:\home\site\wwwroot\bin\SolarWindsAPM\x64\solarwinds_apm_profiler.dll
    COMPLUS_LoaderOptimization 1

    For .NET Framework applications, the .NET Library is installed in the %HOME% directory (typically D:\home\) in the following location: <system_drive>:\home\site\wwwroot\bin\SolarWindsAPM. Log files can be found in <system_drive>:\home\LogFiles\SolarWinds.

    For Linux and Alpine

    Environment variable  Environment variable value 
    SW_APM_SERVICE_KEY  

    (Optional) This overrides what is set in the solarwinds_apm.config file. 

    The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

    It should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

    The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.
    SW_APM_HOME_DOTNET   /home/site/wwwroot/SolarWindsAPM 
    CORECLR_ENABLE_PROFILING   1  
    CORECLR_PROFILER   {AAAA7777-11FE-4F94-8EDA-312C0EDF4141} 
    Linux x64
    CORECLR_PROFILER_PATH          		 /home/site/wwwroot/SolarWindsAPM/linux-x64/solarwinds_apm_profiler.so  
    Alpine x64
    CORECLR_PROFILER_PATH          		 /home/site/wwwroot/SolarWindsAPM/linux-musl-x64/solarwinds_apm_profiler.so
    Linux arm64
    CORECLR_PROFILER_PATH          		 /home/site/wwwroot/SolarWindsAPM/linux-arm64/solarwinds_apm_profiler.so  
    Alpine arm64
    CORECLR_PROFILER_PATH          		 /home/site/wwwroot/SolarWindsAPM/linux-musl-arm64/solarwinds_apm_profiler.so

    The .NET Library is installed in the following location: /home/site/wwwroot/SolarWindsAPM. Log files are in /home/LogFiles/SolarWinds.

  5. Set the Service key in one of the following locations or using the environment variable SW_APM_SERVICE_KEY:

    • Linux: /home/site/wwwroot/SolarWindsAPM/solarwinds_apm.config
    • Windows .NET Framework: <system_drive>:\home\site\wwwroot\bin\SolarWindsAPM\solarwinds_apm.config, where <system_drive> is the system drive of your App Service (for example, C).
    • Windows .NET 6+: <system_drive>:\home\site\wwwroot\SolarWindsAPM\solarwinds_apm.config, where <system_drive> is the system drive of your App Service (for example, C).

  6. Restart the Web App application.

Disable the .NET Library

To disable the .NET Library:

  1. In the Azure Web App, navigate to the Application Settings in the configuration settings.

  2. Set the application global environment variables:

    • For .NET 6+, set CORECLR_ENABLE_PROFILING to 0.

    • For .NET Framework, set COR_ENABLE_PROFILING to 0.

  3. Restart the Web App application.

To re-enable the .NET 6+ library, set the application global environment variable CORECLR_ENABLE_PROFILING to 1 and restart the Web App application.

To re-enable the .NET Framework library, set the application global environment variable COR_ENABLE_PROFILING to 1 and restart the Web App application.

Use the .NET SDK

The SolarWindsAPM.Agent NuGet package includes the custom instrumentation SDK, which can be used to get extra insight into components currently not covered by auto-instrumentation. To use the SDK, add the SolarWindsAPM.Agent NuGet Package to your project and follow the previous instructions to use the package with the Azure App Service. The package makes the custom SDK methods available to create additional trace spans. If the SolarWindsAPM.Agent package is deployed with your service, the SolarWindsAPM.Agent.AzureAppServices.Extension package does not need to be used.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.