• Home
  • Deploy Dynatrace
  • Set up Dynatrace on cloud platforms
  • Microsoft Azure
  • Integrations
  • Monitor Azure App Service
  • Integrate on Azure App Service for Windows

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:

dynatrace-oneagent-site-extension.json
json
{ "$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": {} }
WebApp parameterRequirementDescription
siteNamerequiredWebApp name where you would like to install extension.
locationrequiredRegion of your WebApp. For available regions, see Azure documentation.
skuCapacityoptionalHow many instances you can run under your plan.
skuNameoptionalThe plan's pricing tier and instance size. For pricing details, see Azure documentation.
webAppAlwaysOnoptionalIf AlwaysOn isn't set to true, OneAgent installation is triggered at startup (on the first request to Kudu).
Dynatrace parameterRequirementDescription
environmentIDrequiredThe environment ID as described in Prerequisites.
APITokenrequiredThe PaaS token as described in Prerequisites.
APIUrloptionalThe server URL, if you want to configure an alternative communication endpoint as described in Prerequisites.
SSLModeoptionalTo automatically accept all self-signed TLS certificates, set the value to all.
networkZoneoptionalYour network zone. Set the value you want for your App Service instance. See network zones for more information.
monitoredCLRoptionalSet the value to clr if your application is running on .NET, or coreclr if your application is running on .NET Core, default value is both

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.

MethodEndpointDescriptionResponse
GET/api/statusReturns the current status of the OneAgent installation.

The returned state field can be:
- NotInstalled
- Downloading
- Installing
- Installed
- Failed

For automation purposes, use the isAgentInstalled and isUpgradeAvailable fields to check whether the OneAgent is installed and whether an upgrade is available.
{
"state": "Installed",
"message": "OneAgent installed",
"version": "1.157",
"isAgentInstalled": true,
"isUpgradeAvailable": false,
"isFunction": false,
"functionAppSettings": null
}
GET/api/settingsReturns the current settings, including Dynatrace credentials.{
"apiUrl": "",
"apiToken": "<your-api-token>",
"environmentId": "<your-environment-id>",
"sslMode": "Default"
}
PUT/api/settingsStarts OneAgent installation with the given settings. These settings are stored only if the installation finishes successfully.

In the payload, you need to send the data in the same format as received by the GET /dynatrace/api/settings request.

If there's an update available in the status request, this PUT request can be used to start the upgrade.
Notes:
* The value for apiUrl can be left empty for a SaaS environment.
* For sslMode, if you want to validate the HTTPS connection, leave it as Default. If you don't want to validate the HTTPS connection, set it to AcceptAll.
Empty response

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.

ParameterDescription
DT_CONNECTION_POINTSemicolon-separated list of communication endpoints
DT_MONITORED_CLRVariable to instrument a specific .NET/.NET Core CLR instance
How to add the `DT_CONNECTION_POINT` parameter in Azure Portal
  1. In Azure Portal, select the web application you want to monitor.

  2. Select Settings > Configuration > Application Settings.

  3. Select New application setting.

  4. Enter the configuration key/value pair like this.

    • Name: DT_CONNECTION_POINT
    • Value: https://<YOUR_ACTIVEGATE_ADDRESS>:9999/communication, making sure to replace <YOUR_ACTIVEGATE_ADDRESS> with your own value.

    DT connection

  5. Select OK to save the configuration.

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

No route registered for /dynatrace/ when accessing the site extension

This error message appears if Kudu hasn't been restarted after the site extension was installed. You must restart the application.
There are three options for restarting the application:

  • Through Azure Portal
  • By selecting Restart website on the Kudu console
  • By killing the SCM worker process in Kudu Process Explorer

Note: If you've enabled the extension on multiple deployment slots, you have to do this for each deployment slot.

503 Service Unavailable for Web App and Kudu

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 App Service might return a 503 Service Unavailable message. Also, the Kudu 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's a way to recover from such a situation by adding the following setting in Application Settings to effectively deactivate all site extensions:

WEBSITE_PRIVATE_EXTENSIONS=0

This setting will give you access to Kudu once again. After that, reinstall the site extension and set WEBSITE_PRIVATE_EXTENSIONS=1 (or remove the setting entirely). Following application restart, everything should work again, including Dynatrace monitoring.

Node.js app does not get instrumented

Please check the Platform configuration within General settings of your App Service: 32-bit Node.js is not supported by Dynatrace.

Site extension overrides JAVA_OPTS

You need to reinstall OneAgent if the JAVA_OPTS variable is either added to or removed from the Azure Application settings. If you have the site extension installed and you're adding or removing JAVA_OPTS, the extension must be removed and the application must be restarted before the site extension is reinstalled.
The value of the JAVA_OPTS variable in Application settings can be modified without reinstalling the site extension.

Failed to install: Could not find file

If you get this error during OneAgent installation, you need to update the extension to the latest version.

Location of log files
  • The log files for the extension are in the extensions folder: D:\home\SiteExtensions\Dynatrace\
  • OneAgent log files are located in D:\home\SiteExtensions\Dynatrace.Agent\x.xxx.xxx.xxxxxxxx-xxxxxx\log. You might have multiple D:\home\SiteExtensions\Dynatrace.Agent\ subdirectories caused by agent updates.
Related topics
  • Set up Dynatrace on Microsoft Azure

    Set up and configure monitoring for Microsoft Azure.

  • OneAgent platform and capability support matrix

    Learn which capabilities are supported by OneAgent on different operating systems and platforms.