Integrate OneAgent on Azure App Service

Windows only

Dynatrace provides an Azure site extension to install OneAgent on Azure App Services. Site extensions are the native extension mechanism provided via Kudu, which is the deployment management engine behind Azure App Services.

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

Azure Site-Extension

Agent updates aren't automatically provided through OneAgent. For information on how updates are applied, see Update OneAgent.


Additional configuration parameters

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

<YourDynatraceServerURL> and <YourEnvironmentID> need to be replaced. The URL pattern for the API endpoint is as follows: https://<YourDynatraceServerURL>/e/<YourEnvironmentID>/api

Install Dynatrace OneAgent site extension via Azure Portal

  1. Go to the App Service where you want to add the OneAgent extension.

  2. Select Extensions > Add.

  3. Select Dynatrace OneAgent from the list of extensions.

  4. Accept the legal terms and select OK to install the extension.

  5. Navigate to the list of extensions on Azure Portal.

  6. Select your Dynatrace OneAgent extension, select Browse to go to the dashboard, and configure the extension as required.

  7. Select Install OneAgent.

  8. After installation is complete, restart the App Service to recycle the applications worker process by selecting Stop and then Start.
    Immediately after restart, OneAgent will begin monitoring your application.

Install Dynatrace OneAgent site extension via an ARM template

Alternatively to the main installation method via Azure Portal, you can make the Dynatrace site extension part of your ARM templates.

      "apiVersion": "2016-08-01",
      "name": "[parameters('resourceName')]",
      "type": "Microsoft.Web/sites",
      "properties": {
          "name": "[parameters('resourceName')]",
          "siteConfig": {
              "alwaysOn": true,
              "appSettings": [
                { "Name": "DT_TENANT", "Value": "<Environment-ID>" },
                { "Name": "DT_API_TOKEN", "Value": "<API-Token>" },
                { "Name": "DT_API_URL", "Value": "<Server-Url>" },
                { "Name": "DT_SSL_MODE", "Value": "default" }
          "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('resourceName'))]"
      "dependsOn": [
          "[concat('Microsoft.Web/serverfarms/', parameters('resourceName'))]"
      "location": "[parameters('location')]",
      "resources": [
              "apiVersion": "2016-08-01",
              "name": "Dynatrace",
              "type": "siteextensions",
              "dependsOn": [
                  "[resourceId('Microsoft.Web/sites', parameters('resourceName'))]"
              "properties": { }
Parameter Requirement Description
DT_TENANT Required Provide the environment ID as described in the Prerequisites.
DT_API_TOKEN Required Provide the API token as described in the Prerequisites.
DT_API_URL Optional Provide this property to configure an alternative communication endpoint. See additional configuration parameters for more information.
DT_SSL_MODE Optional To automatically accept all self-signed TLS certificates, set the value to all.

Note: If AlwaysOn isn't set to true, the installation of OneAgent is triggered on the start-up/first request to Kudu.

Automate the installation and update of Dynatrace OneAgent site extension with Kudu REST API

Using Kudu REST API you can automate the installation of the site extension. Once the extension is installed, the extension provides a REST API for automating OneAgent configuration and updates.

Method Endpoint Description Response
GET /api/status Returns 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 know whether or not the OneAgent is installed and there's an upgrade available.
"state": "Installed",
"message": "OneAgent installed",
"version": "1.157",
"isAgentInstalled": true,
"isUpgradeAvailable": false,
"isFunction": false,
"functionAppSettings": null
GET /api/settings Returns the current settings, including Dynatrace credentials. {
"apiUrl": "",
"apiToken": "<your-api-token>",
"environmentId": "<your-environment-id>",
"sslMode": "Default"
PUT /api/settings Starts 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.
* 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

Access the REST API

Base-URL for the REST API

You can use either the user publishing credentials (same as you use for git), or the site level credentials.
For more details on how to access the Kudu service and its extensions, see Accessing the Kudu service.

Reference implementation
On you can find a reference implementation using the REST APIs to fully automate the installation and configuration.

Override OneAgent configuration

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

Parameter Description
DT_CONNECTION_POINT Semicolon-separated list of communication endpoints

Use 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, see Microsoft Documentation - Staged Publishing.

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

Check deployment status

OneAgent starts monitoring your virtual machine immediately after installation, but it will start monitoring your application only after the application is restarted.

You can see the deployment status in your Dynatrace environment.

OneAgent deployment status

Update OneAgent

To update OneAgent on Azure App Service, go to the Azure Portal, browse to your site extension, and, if an update is available, select Update. You can monitor the progress until the update is finished.
Then restart App Service to recycle the application worker process by selecting Stop and then Start.

Note: The extension provides its own REST API for automating OneAgent updates. See REST API for details.

Update the site extension

To update the site extension on Azure App Service, go to the Azure Portal, browse to your site extension, and, if an update is available, select Update.

Note: An update to the site extension doesn't force an update to OneAgent.

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.

Uninstall OneAgent

Removing the extension also removes OneAgent.

If the application is running at the time of removal, the extension recognizes the running application, taking care to not remove any Dynatrace artifacts to prevent issues with the application. Instead, only the extension including the configuration is removed, so that, on the next restart of the application, OneAgent is no longer active.