Documentation forAppOptics

Install on the Azure App Service

Application Insights must be disabled to use the AppOptics extension.

AppOptics provides detailed insight and distributed tracing for .NET Core 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 for .NET Core.

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

The .NET Agent site extension is currently available as a beta release.

The .NET Agent site extension currently only supports .NET Core and .NET 5.0 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:

    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  

    The .NET Agent is installed in the %HOME%\SiteExtensions\AppOptics.Agent.AzureAppServices.Extension\AppOptics directory. The 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:
    • APPOPTICS_HOME_APM_DOTNET
    • CORECLR_ENABLE_PROFILING
    • CORECLR_PROFILER
    • CORECLR_PROFILER_PATH_32
    • CORECLR_PROFILER_PATH_64
  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 AppOptics.Agent package is currently available as a beta release.

The .NET Agent Nuget package currently only supports .NET Core and .NET 5.0 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:

    Copy
    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:

    Copy
    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

    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  

    The .NET Agent is installed in the %HOME%\site\wwwroot\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 variable CORECLR_ENABLE_PROFILING to 0.

  3. Restart the webapp application.

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

Use the .NET Core 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.