How do I monitor Microsoft Azure Web Apps?

Azure Web Apps is a service provided by Microsoft Azure that gives you the option of deploying and auto-scaling applications and services. Using a predefined Azure site extension you can modify your deployment by supplying additional resources or packages. For more information, see the Azure Web Sites documentation.

Before you begin

What you'll need


Generate a PaaS token

The first step is to get your environment ID and generate a PaaS token for your Dynatrace environment. This information is required so we can map your Azure account to your Dynatrace account.

To get your Dynatrace environment ID and PaaS token

  1. Login with your Dynatrace account.

  2. Select Deploy Dynatrace from the navigation menu.

  3. Click the Set up PaaS integration button.

  4. Your environment ID appears in the Environment ID text box. You'll need this ID to link your Dynatrace account with your PaaS environment. Click Copy to copy the ID to the clipboard. You can do this at any time by revisiting this page.

  5. To generate a PaaS token, click the Generate new token button. The PaaS token is essentially an API token that's used in combination with your environment ID to download Dynatrace OneAgent. As you will notice, there is already a default InstallerDownload token available that you could alternatively use. However, for security reasons, it is recommended that you create several discrete tokens for different environments.

  6. Type in a meaningful name for your PaaS token. A meaningful token name might be the name of the PaaS platform you want to monitor (for example, azure, cloud-foundry, or openshift). To view and manage your existing PaaS tokens, go to Settings -> Integration -> Platform as a Service.

  7. Click Generate to create the PaaS token. The newly created PaaS token will appear in the list below. Click Copy to copy the generated token to the clipboard. You can do this at any time by revisiting this page and clicking Show token next to the relevant PaaS token.

Configure the Dynatrace Site Extension via the Azure portal

Now, open in a new browser window.

Navigate to the web app you want to monitor.

From Settings, select Application Settings. Then, scroll down to the App Settings area and add two new Key/Value pairs:

  • DT_TENANT: Your environment ID, as shown above.
  • DT_API_TOKEN: Copy and paste the PaaS token from the Download Dynatrace page shown above.

If you're using Dynatrace Managed, you need to configure additional settings to allow the site extension to download OneAgent from your Managed server:

  • DT_API_URL: This needs to be set to https://<YourManagedServerURL>/e/<environment-id>/api.
  • DT_SSL_MODE (optional): By default, the Dynatrace site extension validates the SSL certificate required to download the OneAgent binaries from your Dynatrace Managed server. If you use a self-signed SSL certificate on your Dynatrace Managed server, you can force the site extension to accept it by setting DT_SSL_MODE to all.

Remember to persist your changes by clicking the Save button at the top of the page.

Install the Dynatrace Azure site extension

You can do this either via the Azure Portal or through Kudo.

Via the Azure Portal

  1. Now, open in a new browser window.

  2. Navigate to the web app you want to monitor.

  3. Select Extensions from the list of options. You'll find this in the Development tools subsection (note the Search field at the top of the page in case you have trouble finding this option).

  4. Within the new pane (i.e., "blade" in Azure terminology) that appears on the right-hand side, click Add.

  5. Scroll through the list until you find Dynatrace OneAgent. Note that entries are not ordered alphabetically.

  6. Click OK to apply Dynatrace monitoring to your Azure website.

  7. Restart your website so that Dynatrace begins to receive monitoring data. Following restart, you should see the hosts and services that you've set up via your Azure service plan (see example below). Note that the PaaS type setting is set to Azure.

Via Kudo

Alternatively, you can install the Dynatrace site extension via Kudu, which is available at this URL <website-name>

Once setup is complete, your Dynatrace home dashboard shows you all server-side and browser-side metrics—all without modifying a single line of code or touching your deployment scripts.

Via ARM template

If you prefer to make the Dynatrace site extension part of your ARM templates, here's how:

"apiVersion": "2014-04-01",
      "name": "[parameters('siteName')]",
      "type": "Microsoft.Web/sites",
      "location": "[parameters('siteLocation')]",
      "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', parameters('hostingPlanName'))]"
      "properties": {
        "name": "[parameters('siteName')]",
        "webHostingPlan": "[parameters('hostingPlanName')]"
      "resources": [
          "apiVersion": "2014-04-01",
          "name": "web",
          "type": "config",
          "dependsOn": [
            "[resourceId('Microsoft.Web/Sites', parameters('siteName'))]"
          "properties": {
            "appSettings": [
              { "Name": "DT_TENANT", "Value": "<your-environment-here>" },
              { "Name": "DT_API_TOKEN", "Value": "<your-token-here>" }
          "apiVersion": "2014-04-01",
          "name": "Dynatrace",
          "type": "siteextensions",
          "dependsOn": [
            "[resourceId('Microsoft.Web/Sites', parameters('siteName'))]",
            "[resourceId('Microsoft.Web/Sites/config', parameters('siteName'), 'web')]"
          "properties": { }

Upon deployment of the ARM template, Dynatrace OneAgent will be part of the deployment automatically.

Using multiple deployment slots

As Azure App Service deployment slots are treated like full-fledged application service instances, you need to enable the Dynatrace OneAgent Site Extension for each deployment slot. For details on configuring deployment slots, see Microsoft Documentation - Staged Publishing.


Update the Azure Site Extension

If there is an available extension update, an Update button will be visible in the Azure UI. Click Update to begin.

Updates to OneAgent

Following OneAgent updates, you must re-install the Azure Site Extension and re-establish connection between the extension and your application.

  1. Update OneAgent.
  2. Uninstall the site extension.
  3. Re-install the site extension.
  4. Restart the application.

Note: If you specified the default OneAgent install version for new hosts and applications in your OneAgent updates settings, the Azure Site Extension will automatically supply the defined default version of Dynatrace OneAgent.


Just as with the installation process described above, uninstalling the Dynatrace site extension can be done either via the Azure portal or by using Kudo.


Find out how to solve problems that you may encounter when setting up a Microsoft Azure web app for monitoring with OneAgent.

503 Service Unavailable for Web App and Kudo

The Dynatrace site extension registers IIS modules at installation time. If registration is complete but the actual IIS module files aren't in place (or corrupt), the Web App may return a 503 Service Unavailable message. Also, the Kudo AppPool will no longer be available, which effectively means that you can no longer fix your app. If this occurs, please file a support case. Fortunately, there is a way to recover from such a situation by adding the following setting in Application Settings to effectively deactivate all site extensions:


This setting will give you access to Kudo once again. Please then re-install the site extension and set WEBSITE_PRIVATE_EXTENSIONS=1 (or remove the setting entirely). Following application restart, everything should work again, including Dynatrace monitoring.