Documentation forAppOptics

Installation on Azure App Service (legacy agent)

The following content pertains to installation on the Azure App Service for the legacy AppOptics NET Agent.

AppOptics agents are no long receiving updates. The new SolarWinds Observability libraries are regularly updated with new features and improvements. If you are still relying on the AppOptics agents and your components are supported by the new libraries, consider migrating to SolarWinds Observability.

If you have already transitioned to the new SolarWinds Observability NET Library, see the SolarWinds NET Library documentation for installation on the Azure App Service information.

SolarWinds Observability libraries are not compatible with AppOptics agents. Do not use a mix of SolarWinds Observability libraries and AppOptics agents to instrument applications that are part of a distributed trace.

Application Insights must be disabled to use the AppOptics extension.

AppOptics provides detailed insight and distributed tracing for .NET Framework and .NET Core/5+ applications running in Azure App Service. The .NET agent can be installed using the AppOptics Azure Site Extension or using the AppOptics.Agent NuGet package.

Install the .NET agent using the AppOptics Azure Site Extension (Windows only)

The .NET Agent site extension supports .NET Framework aspnet|v4.8 runtime and .NET Core/5+ Azure App Services.

To install the AppOptics .NET Agent Azure AppServices Extension Package in your Azure webapp:

  1. In the Development Tools section of the Azure webapp, click Extensions.

  2. Click the Add button and select AppOptics .NET Agent Azure AppServices Extension from the list.

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

    .NET Core/5+

    Environment Variable  Environment Variable Value 
    APPOPTICS_SERVICE_KEY   (Optional) The service key which should be in the <appoptics-api-token:service-name> format. This overrides what is set in the agent.config file.  
    APPOPTICS_HOME_APM_DOTNET   D:\home\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics  
    CORECLR_ENABLE_PROFILING   1  
    CORECLR_PROFILER   {824293AD-22E2-4DAA-BC28-166C140543BE}  
    CORECLR_PROFILER_PATH_32   D:\home\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics\x86\AppOpticsProfiler.dll  
    CORECLR_PROFILER_PATH_64   D:\home\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics\x64\AppOpticsProfiler.dll  

    .NET Framework

    Environment Variable  Environment Variable Value 
    APPOPTICS_SERVICE_KEY   (Optional) The service key which should be in the <appoptics-api-token:service-name> format. This overrides what is set in the agent.config file.  
    APPOPTICS_HOME_APM_DOTNET   D:\home\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics  
    COR_ENABLE_PROFILING   1  
    COR_PROFILER   {824293AD-22E2-4DAA-BC28-166C140543BE}  
    COR_PROFILER_PATH_32   D:\home\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics\x86\AppOpticsProfiler.dll  
    COR_PROFILER_PATH_64   D:\home\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics\x64\AppOpticsProfiler.dll  
    COMPLUS_LoaderOptimization 1

    The .NET Agent is installed in the %HOME%\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics directory. For both .NET Core/5+ and .NET Framework applications, log files can be found in %HOME%\LogFiles\AppOptics.

  4. Set the service key in the %HOME%\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics\agent.config file. Alternatively, the service key can be set using the environment variable APPOPTICS_SERVICE_KEY.

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

  5. Restart the webapp application.

Uninstall the .NET Agent from Azure AppServices

To disable the .NET agent instead of uninstalling the agent, see Disable the .NET Agent.

To uninstall the .NET agent from the Azure AppServices:

  1. From the Azure webapp, remove the .NET agent environment variables that were previously added. Navigate to the Application Settings in the configuration settings and remove the following environment variables:
    • .NET Core/5+
      • APPOPTICS_HOME_APM_DOTNET
      • CORECLR_ENABLE_PROFILING
      • CORECLR_PROFILER
      • CORECLR_PROFILER_PATH_32
      • CORECLR_PROFILER_PATH_64
    • .NET Framework
      • APPOPTICS_HOME_APM_DOTNET
      • COR_ENABLE_PROFILING
      • COR_PROFILER
      • COR_PROFILER_PATH_32
      • COR_PROFILER_PATH_64
      • COMPLUS_LoaderOptimization
  2. Restart the webapp application.
  3. In the Azure webapp, in the Development Tools section, click Extensions.
  4. Select the AppOptics .NET Agent Azure AppServices Extension, and click the Delete button.

Install the .NET agent using the AppOptics.Agent NuGet package (Windows + Linux)

The .NET Agent Nuget package supports .NET Framework aspnet|v4.8 runtime and .NET Core/5+ Azure App Services.

  1. Open the official AppOptics.Agent Nuget package page to to view details about the latest release of the agent and add the agent using your preferred package installation method.

    To add the agent to your package using the .NET CLI, enter the following command in the command prompt:

    dotnet add <project-name>.csproj package AppOptics.Agent --version <version-number>

    Where <version-number> is the latest available version number found on the the official AppOptics.Agent Nuget package page.

  2. Publish the webapp to Azure. Example publish command:

    dotnet publish <project-name>.csproj /p:PublishProfile='<profile-name>'

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

    For Windows

    .NET Core/5+

    Environment Variable  Environment Variable Value 
    APPOPTICS_SERVICE_KEY   (Optional) The service key which should be in the <appoptics-api-token:service-name> format. This overrides what is set in the agent.config file.  
    APPOPTICS_HOME_APM_DOTNET   D:\home\site\wwwroot\AppOptics  
    CORECLR_ENABLE_PROFILING   1  
    CORECLR_PROFILER   {824293AD-22E2-4DAA-BC28-166C140543BE}  
    CORECLR_PROFILER_PATH_32   D:\home\site\wwwroot\AppOptics\x86\AppOpticsProfiler.dll  
    CORECLR_PROFILER_PATH_64   D:\home\site\wwwroot\AppOptics\x64\AppOpticsProfiler.dll  

    For .NET Core/5+ applications, the .NET Agent is installed in the %HOME%\site\wwwroot\AppOptics directory. Log files are in %HOME%\LogFiles\AppOptics.

    .NET Framework

    Environment Variable  Environment Variable Value 
    APPOPTICS_SERVICE_KEY   (Optional) The service key which should be in the <appoptics-api-token:service-name> format. This overrides what is set in the agent.config file.  
    APPOPTICS_HOME_APM_DOTNET   D:\home\site\wwwroot\bin\AppOptics  
    COR_ENABLE_PROFILING   1  
    COR_PROFILER   {824293AD-22E2-4DAA-BC28-166C140543BE}  
    COR_PROFILER_PATH_32   D:\home\site\wwwroot\bin\AppOptics\x86\AppOpticsProfiler.dll  
    COR_PROFILER_PATH_64   D:\home\site\wwwroot\bin\AppOptics\x64\AppOpticsProfiler.dll  
    COMPLUS_LoaderOptimization 1

    For .NET Framework applications, the .NET Agent is installed in the %HOME%\site\wwwroot\bin\AppOptics directory. Log files are in %HOME%\LogFiles\AppOptics.

    For Linux

    Environment Variable  Environment Variable Value 
    APPOPTICS_SERVICE_KEY   (Optional) The service key which should be in the <appoptics-api-token:service-name> format. This overrides what is set in the agent.config file.  
    APPOPTICS_HOME_APM_DOTNET   /home/site/wwwroot/AppOptics  
    CORECLR_ENABLE_PROFILING   1  
    CORECLR_PROFILER   {824293AD-22E2-4DAA-BC28-166C140543BE}  
    CORECLR_PROFILER_PATH   /home/site/wwwroot/AppOptics/AppOpticsProfiler.so  

    The .NET Agent is installed in the ${HOME}/site/wwwroot/AppOptics directory. Log files are in ${HOME}/LogFiles/AppOptics.

  4. Set the service key in the %HOME%\site\wwwroot\AppOptics\agent.config file for Windows or ${HOME}/site/wwwroot/AppOptics/agent.config file for Linux. Alternatively, the service key can be set using the environment variable APPOPTICS_SERVICE_KEY.

  5. Restart the webapp application.

Disable the .NET Agent

To disable the .NET agent:

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

  2. Set the application global environment variables:

    • For .NET Core/5+: CORECLR_ENABLE_PROFILING to 0.

    • For .NET Framework:  COR_ENABLE_PROFILING to 0.

  3. Restart the webapp application.

To re-enable the .NET Core/5+ Agent, set the application global environment variable CORECLR_ENABLE_PROFILING to 1 and restart the webapp application.

To re-enable the .NET Framework Agent, set the application global environment variable COR_ENABLE_PROFILING to 1 and restart the webapp application.

Use the .NET SDK

The AppOptics.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 AppOptics.Agent NuGet Package to your project and follow the above 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 AppOptics.Agent package is deployed with your service, the AppOptics.Agent.AzureAppServices.Extension package does not need to be used.