Integrate OneAgent on Azure App Service

Windows only

For Azure App Service, monitoring consumption is based on host units. See Serverless monitoring for details.

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.

API integration

For additional insights, besides installing the OneAgent site extension, you can also activate API integration on Azure App Service that can occur in Azure App Service, and that the application-only OneAgent deployed with the site extension can't detect on its own because the required metrics are only issued by the Azure Metrics API.

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.

Install Dynatrace OneAgent site extension

There are two ways to install the Dynatrace OneAgent site extension: via Azure Portal or using an ARM template. Follow the steps below for instructions.

Install Dynatrace OneAgent site extension 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 API token, and your server URL. See Prerequisites 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, go to Azure Portal and restart the App Service application to recycle the application's worker process. Immediately after restart, OneAgent will begin monitoring your application.

Install Dynatrace OneAgent site extension using an ARM template

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

Web App Parameter Requirement Description
siteName required Web app name where you would like to install extension.
location required Region of your web app. For available regions, see Azure documentation.
skuCapacity optional How many instances you can run under your plan.
skuName optional The plan's pricing tier and instance size. For pricing details, see Azure documentation.
webAppAlwaysOn optional If AlwaysOn isn't set to true, installation of OneAgent is triggered on the start-up/first request to Kudu.
Dynatrace Parameter Requirement Description
environmentID required The environment ID as described in Prerequisites.
APIToken required The PaaS token as described in Prerequisites.
APIUrl optional The server URL, if you want to configure an alternative communication endpoint as described in Prerequisites.
SSLMode optional To automatically accept all self-signed TLS certificates, set the value to all.
networkZone optional Your network zone. Set the value you want for your App Service instance. See network zones for more information.

To check the deployment status, in your Dynatrace environment, go to Manage and select Deployment status.

After installation is complete, go to Azure Portal and restart the App Service application to recycle the application's worker process. Immediately after restart, OneAgent will begin monitoring your application.

Automate the installation and update of Dynatrace OneAgent

You can use the Kudu REST API to automate installation and update of the Dynatrace OneAgent site extension. See the automation setup page on GitHub for details.

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. See Accessing the Kudu service for details.

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.
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
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.

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

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.

Update the Dynatrace OneAgent site extension

To update the Dynatrace OneAgent site extension on Azure App Service

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

Note: An update to the Dynatrace OneAgent site extension doesn't force an update to Dynatrace 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.

Update Dynatrace 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, browse 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.

Note: The extension provides its own REST API for automating OneAgent 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, taking care to not remove any Dynatrace artifacts to prevent issues with the application. Instead, only the site extension including the configuration is removed, so that, on the next restart of the application, Dynatrace OneAgent is no longer active.

Troubleshooting