Integrate OneAgent on Azure App Service for Windows

Azure App Service provides many different hosting options for Windows, Linux, and containers with shared infrastructure (App Service plan), or fully isolated and dedicated infrastructure (Azure App Service Environment).

Capabilities

The App Service integration with Dynatrace provides the following capabilities:

Limitations
Since Azure App Service is a fully managed hosting platform, applications are deployed into a sandboxed environment that doesn't allow direct access to the underlying operating system. The OneAgent integration for Azure App Service uses the application-only or universal injection approach, which results in some differences from the Full-Stack OneAgent installation:

Install Dynatrace OneAgent site extension

Windows only

Dynatrace provides a site extension to install OneAgent on Azure App Services on Windows.

Site extension is the native extension mechanism provided via Kudu, which is the deployment management engine behind Azure App Services.

The Dynatrace OneAgent site extension doesn't include the OneAgent installer. Instead, the extension uses the Dynatrace REST API to download the latest installer from the Dynatrace Cluster, unless a OneAgent default version is configured.

There are multiple ways to install the Dynatrace OneAgent site extension:

See below for instructions.

Prerequisites

Manual install via Azure Portal

Automatic install using an ARM template

As an alternative to installing via Azure Portal, you can make the Dynatrace site extension part of your ARM templates.

Example configuration:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    // WebApp Settings
    "siteName": {
      "type": "string",
      "metadata": {
        "description": "Web app name where you would like to install extension."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "Region of your web app."
      }
    },
    "skuCapacity": {
      "type": "int",
      "defaultValue": 1,
      "minValue": 1,
      "metadata": {
        "description": "Describes plan's instance count."
      }
    },
    "skuName": {
      "type": "string",
      "defaultValue": "B1",
      "allowedValues": [
        "B1",
        "B2",
        "B3",
        "D1",
        "F1",
        "I1",
        "I1v2",
        "I2",
        "I2v2",
        "I3",
        "I3v2",
        "P1V2",
        "P1V3",
        "P2V2",
        "P2V3",
        "P3V2",
        "P3V3",
        "PC2",
        "PC3",
        "PC4",
        "S1",
        "S2",
        "S3"
      ],
      "metadata": {
        "description": "Describes plan's pricing tier and instance size. Check details at https://azure.microsoft.com/en-us/pricing/details/app-service/."
      }
    },
    "webAppAlwaysOn": {
      "type": "bool",
      "metadata": {
        "description": "If AlwaysOn isn't set to true, installation of OneAgent is triggered on the start-up/first request to Kudu."
      },
      "defaultValue": true
    },
    // Dynatrace OneAgent site extension settings
    "environmentID": {
      "type": "string",
      "metadata": {
        "description": "The environment ID."
      }
    },
    "APIToken": {
      "type": "string",
      "metadata": {
        "description": "The PaaS token."
      }
    },
    "APIUrl": {
      "type": "string",
      "metadata": {
        "description": "The server URL, if you want to configure an alternative communication endpoint."
      }
    },
    "SSLMode": {
      "type": "string",
      "metadata": {
        "description": "To automatically accept all self-signed TLS certificates, set the value to all."
      },
      "allowedValues": ["default", "all"],
      "defaultValue": "default"
    },
    "monitoredCLR": {
      "type": "string",
      "metadata": {
        "description": "Your .NET application runtime"
      },
      "allowedValues": ["both", "coreclr", "clr"],
      "defaultValue": "both"
    },
    "networkZone": {
      "type": "string",
      "metadata": {
        "description": "Your network zone. Set the value you want for your App Service instance. See network zones for more information."
      },
      "defaultValue": ""
    }
  },
  "resources": [
    {
      "apiVersion": "2020-12-01",
      "name": "[parameters('siteName')]",
      "type": "Microsoft.Web/serverfarms",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('skuName')]",
        "capacity": "[parameters('skuCapacity')]"
      },
      "properties": {
        "name": "[parameters('siteName')]"
      }
    },
    {
      "apiVersion": "2020-12-01",
      "name": "[parameters('siteName')]",
      "type": "Microsoft.Web/sites",
      "properties": {
        "name": "[parameters('siteName')]",
        "siteConfig": {
          "alwaysOn": "[parameters('webAppAlwaysOn')]",
          "appSettings": [
            { "Name": "DT_TENANT", "Value": "[parameters('environmentID')]" },
            { "Name": "DT_API_TOKEN", "Value": "[parameters('APIToken')]" },
            { "Name": "DT_API_URL", "Value": "[parameters('APIUrl')]" },
            { "Name": "DT_SSL_MODE", "Value": "[parameters('SSLMode')]" },
            { "Name": "DT_MONITORED_CLR", "Value": "[parameters('monitoredCLR')]" },
            { "Name": "DT_NETWORK_ZONE", "Value": "[parameters('networkZone')]" }
          ]
        },
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('siteName'))]"
      },
      "dependsOn": ["[concat('Microsoft.Web/serverfarms/', parameters('siteName'))]"],
      "location": "[parameters('location')]",
      "resources": [
        {
          "apiVersion": "2020-12-01",
          "name": "Dynatrace",
          "type": "siteextensions",
          "dependsOn": ["[resourceId('Microsoft.Web/sites/', parameters('siteName'))]"]
        }
      ]
    }
  ],
  "outputs": {}
}

To check the deployment status, go to Deployment Status.

After installation is complete, restart the App Service application to recycle the application's worker process. After restart, OneAgent starts monitoring your application automatically.

Automate the installation using a PowerShell script

You can automate the installation with a PowerShell script that uses the Kudu REST API, OneAgent site extension REST API, as well as the Azure CLI. A sample implementation is available in the Dynatrace GitHub repository.

Dynatrace OneAgent site extension REST API

The Dynatrace OneAgent site extension provides a REST API to automate OneAgent installation, configuration, and update.

The root URL to access the REST API is https://<Your-AppService-Subdomain>.scm.azurewebsites.net/dynatrace/, where you need to replace <Your-AppService-Subdomain> with your own value. To authenticate, you can use either the user publishing credentials or the site-level credentials. For details, see Accessing the Kudu service.

Using multiple deployment slots

Because Azure App Service deployment slots are treated like full-fledged application service instances, you need to enable the site extension for OneAgent on each deployment slot you want to monitor with Dynatrace.

For details on configuring deployment slots, consult the Microsoft documentation.

If you're using application settings to additionally configure certain OneAgent options, make sure the additional settings are also applied to the deployment slots.

Using App Service built-in authentication and authorization

If you use App Service built-in authentication and authorization capabilties (also referred to as "Easy Auth"), App Service starts an additional .NET CLR instance, which makes OneAgent instrument the Easy Auth module instead of your application's instance as the leading instance.

In this case, if your application process isn't instrumented, you need to set the DT_MONITORED_CLR environment variable to instance that your application is running on: clr or coreclr. You can set this variable in Azure Portal (Settings > Configuration > Application Settings).

Override OneAgent configuration

To override the default configuration, you can use the following parameters.

Using Application Insights

OneAgent may not be able to instrument your .NET/.NET Core application if you use Application Insights with runtime instrumentation enabled. This is because OneAgent and Application Insights try to use the same interface to inject at runtime.

Please review your Application Insights configuration for Asp.Net, where you can turn off runtime instrumentation or Asp.Net Core auto-instrumentation.

Update the Dynatrace OneAgent site extension

To update the Dynatrace OneAgent site extension

When upgrading the extension from version 1.x to version 2.x, if you have Always On selected on your App Service, the upgrade of OneAgent is either triggered automatically or on the first request to the UI extension. If you don't have Always On selected, you must restart App Service, so that the extension process starts.

Update OneAgent

The Dynatrace OneAgent site extension doesn't provide Dynatrace OneAgent updates automatically. To update Dynatrace OneAgent on Azure App Service

You can monitor the progress until the update is complete, and then restart App Service to recycle the application worker process.

Automate OneAgent updates

To automate OneAgent update, the Dynatrace OneAgent site extension provides a REST API that can be used to trigger updates. See REST API for details.

Uninstall Dynatrace OneAgent site extension

Removing the Dynatrace OneAgent site extension also removes Dynatrace OneAgent. If the application is running at the time of removal, the site extension recognizes the running application and, to prevent issues with the application, does not remove any Dynatrace artifacts. Instead, only the site extension, including the configuration, is removed, so that Dynatrace OneAgent is no longer active the next time the application restarts.

Monitoring consumption

For Azure App Service, monitoring consumption is based on host units. See Application and Infrastructure Monitoring (Host Units) for details.

Troubleshoot