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

• Integration for OneAgent on Windows via an extension for easy deployment
• Integration for OneAgent on Linux and containers
• Automatic distributed tracing and monitoring for .NET/.NET Core, Java, Node.js, PHP, and IIS
• Enhanced capturing of Azure App Service metadata, such as SKU or Website-Name
• Capturing of platform-level metrics and additional insights into your App-Service Plan via the Azure Monitor integration
• Capturing of logs via log forwarding

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:

• I/O monitoring requires that you enable Azure Monitor integration, which also provides additional insights into your App-Service Plan
• Capturing logs requires that you enable log forwarding
• Automatic OneAgent updates need to be triggered via the Dynatrace OneAgent site extension REST API
• Hostgroup configuration is not available

Install Dynatrace OneAgent site extension

Windows only

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

Note: For Azure App Service on Linux or containers, see Integration for OneAgent on Azure App Service on Linux and containers.

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:

• Manually, via Azure Portal
• Automatically, using an ARM template
• By automating the setup with a custom PowerShell script

See below for instructions.

Prerequisites

• Create a PaaS token.

• Determine your environment ID.

• Determine your server URL if required.

  The server URL is required only if you use either of the following:

  • a Dynatrace Managed endpoint
  • an ActiveGate for a Dynatrace Managed or Dynatrace SaaS endpoint

  (If you use Dynatrace SaaS, the URL is automatically generated from the environment ID.)

  • Dynatrace Managed server URL:
    https://{your-domain}/e/{your-environment-id}/api
  • ActiveGate server URL:
    https://<your-active-gate-IP-or-hostname>:9999/e/<your-environment-id>/api (the ActiveGate port is configurable)

Note: If you're using Dynatrace Managed, or if your cluster traffic should be routed through an ActiveGate, you need to configure the API endpoint used by the extension for downloading OneAgent.

Manual install via Azure Portal

1. In Azure Portal, go to the App Service where you want to add the OneAgent extension.
2. In the left menu, scroll down to Development Tools and select Extensions.
3. Select Add.
4. Select Choose extension.
5. From the list of extensions, select Dynatrace OneAgent.
6. Select Accept legal terms and then select OK to accept the legal terms.
7. Select OK to add the extension.
8. Select Dynatrace OneAgent.
9. Select Browse.
10. On the Start monitoring your App Service instance page, enter your environment ID, your PaaS token, and your server URL. See Prerequisites section for details.
11. optional You can select Accept all self-signed SSL certificates to automatically accept all self-signed TLS certificates.
12. Select Install OneAgent.
13. To check the deployment status, in your Dynatrace environment, go to Manage and select 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.

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:

jsoncopydownload
{
  "$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, in your Dynatrace environment, go to Manage and select 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.

Note: While you may still be able to use Application Insights in basic mode or SDK in parallel with Dynatrace OneAgent, please note that this may cause other issues or significant monitoring overhead to your applications and isn't recommended.

Update the Dynatrace OneAgent site extension

To update the Dynatrace OneAgent site extension

1. In Azure Portal, go to your Azure App Service with Dynatrace OneAgent site extension.
2. If an update is available, select Update.

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.

Note: An update to the Dynatrace OneAgent site extension doesn't force a OneAgent update. To update OneAgent, see Dynatrace OneAgent.

Update OneAgent

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

1. In Azure Portal, go to your Azure App Service with Dynatrace OneAgent site extension.
2. In the Development Tools section, choose Extensions and select Dynatrace OneAgent.
3. On the site extension page, use Browse to navigate to the extension site.
4. If an update is available, select Upgrade OneAgent.

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