Try it free

Create an Azure connection via CLI

  • Latest Dynatrace
  • How-to guide

Prerequisites

1. Tools

The following CLI tools are required to run the commands on this page:

ToolMinimum versionNotes

dtctl

Latest

See the installation guide. Verify with dtctl version.

Azure CLI (az)

2.40

Required for service principal and role assignment commands. Verify with az version.

2. Azure

Actions in this section must be performed by an Azure administrator with appropriate permissions.

Before running Azure CLI commands, ensure:

  • You have Azure CLI installed and authenticated (az login)

  • Your Azure account has one of the following:

    • Application Administrator role in Microsoft Entra ID

    • Cloud Application Administrator role in Microsoft Entra ID

    • microsoft.directory/servicePrincipals/create permission.

      And one of the following:

    • Owner role at the target scope (subscription or management group)

    • User Access Administrator role at the target scope

    • A custom role with Microsoft.Authorization/roleAssignments/write permission

For Management Group monitoring scope, you need role assignment permissions at the management group level, not just individual subscriptions.

Identify your Azure monitoring scope

Decide which monitoring scope you'll use and gather the required IDs:

Monitoring scopeRequired information

Management Group

Management Group ID (found in Azure portal under Management groups)

Subscription

Subscription ID (found in Azure portal under Subscriptions)

Register the Microsoft.Insights resource provider

Dynatrace can poll Azure Monitor metrics only from subscriptions where the Microsoft.Insights resource provider is registered. Azure often registers it automatically—for example, when you create an alert rule or configure diagnostic settings—but not in every subscription. If it isn't registered, Dynatrace still discovers your topology but doesn't ingest metrics.

Check every subscription in your monitoring scope. For a Management Group scope, check every subscription beneath it. To register a resource provider, you need the Contributor or Owner role on the subscription. The Dynatrace service principal can't register it.

To check and register it in the Azure portal:

  1. Go to Subscriptions and select the subscription.
  2. Under Settings, select Resource providers.
  3. Search for Microsoft.Insights. If the status is NotRegistered, select it and then select Register. If the status is Registering, wait until it shows Registered.

To check it with Azure CLI:

az provider show --namespace Microsoft.Insights --subscription <SUBSCRIPTION_ID> --query registrationState --output tsv

If the output isn't Registered, run the following command. With --wait, the command returns once registration is complete.

az provider register --namespace Microsoft.Insights --subscription <SUBSCRIPTION_ID> --wait

For details, see Azure resource providers and types.

3. Dynatrace

  1. Configure dtctl with your Dynatrace environment:

  1. Ensure your Dynatrace user has the correct permissions by completing the Create the Dynatrace IAM baseline steps.

    dtctl auth login --context my-env --environment "https://<YOUR_ENVIRONMENT_ID>.apps.dynatrace.com"

  2. Replace <YOUR_ENVIRONMENT_ID> with your Dynatrace environment ID (for example, abc12345).

  3. Verify your configuration:

    dtctl doctor

  4. If this is the first time an Azure connection is created in this Dynatrace environment, install the Azure extension:

    dtctl create extension --hub-extension com.dynatrace.extension.da-azure

  1. Create a programmatic access permission policy with the following permissions:

    ALLOW
      settings:objects:read,
      settings:objects:write,
      settings:schemas:read
      WHERE settings:schemaId = "builtin:hyperscaler-authentication.connections.azure";
    

    ALLOW
      extensions:configurations:read,
      extensions:configurations:write,
      extensions:definitions:read,
      extensions:definitions:write
      WHERE extensions:extension-name = "com.dynatrace.extension.da-azure";

  2. Create a service user and assign the policy created in the previous step to it.

  3. Create a platform token for the service user created in the previous step with the following scopes:

    extensions:configurations:read
    extensions:configurations:write
    extensions:definitions:read
    extensions:definitions:write
    settings:schemas:read
    settings:objects:read
    settings:objects:write

  4. Configure dtctl:

    dtctl config set-context my-env --environment "https://<YOUR_ENVIRONMENT_ID>.apps.dynatrace.com" --token-ref my-token
    

    dtctl config set-credentials my-token --token "<YOUR_PLATFORM_TOKEN>"

  5. Replace the following placeholders with your values:

    • <YOUR_ENVIRONMENT_ID>: Your Dynatrace environment ID (for example, abc12345).
    • <YOUR_PLATFORM_TOKEN>: The platform token created in step 4.

  6. Verify your configuration:

    dtctl config view

  7. If this is the first time an Azure connection is created in this Dynatrace environment, install the Azure extension:

    dtctl create extension --hub-extension com.dynatrace.extension.da-azure

Get started

A complete Azure monitoring setup requires two resources:

  • Azure connection
  • Monitoring configuration

The shell commands on this page use \ for line continuation (bash/zsh). On Windows, replace \ with a backtick (`) in PowerShell, or ^ in command prompt.

Create a new Azure connection with CLI

The monitoring configuration requires an Azure connection to access your Azure environment. Dynatrace supports two authentication methods:

Authentication methodDescriptionNotes

Federated identity Recommended

Uses federated identity credentials.

More secure, passwordless authentication

Client secret

Uses a service principal with client secret.

Password-based authentication

Federated identity credentials provide passwordless authentication and are more secure than client secrets.

This is the recommended approach for production environments.

1. Create an empty Azure connection

Create the Azure connection in Dynatrace.

dtctl automatically generates and displays the exact issuer, subject, and audience values you will need in step 2.

dtctl create azure connection --name "<CONNECTION_NAME>" --type federatedIdentityCredential

Save the connection object ID from the command output. You'll need it when configuring the federated credential in Azure.

2. Configure federated credentials in Azure

Configure the federated identity credential in Microsoft Entra ID using the values displayed in step 1.

  1. Prepare for registering a new application in your Microsoft Entra ID tenant. For details, see How to register an app in Microsoft Entra ID

    az ad sp create-for-rbac \
    --name "<CONNECTION_NAME>" \
    --create-password false \
    --query "{CLIENT_ID:appId, TENANT_ID:tenant}" \
    --output table

    Replace the <CONNECTION_NAME> placeholder with a descriptive name for the connection (used in Dynatrace) and register a new application.

  2. Prepare for creating a federated credential for the Microsoft Entra ID app using the issuer, subject, and audience displayed in step 1. Dynatrace uses this for OIDC token exchange. For details, see az ad app federated-credential.

    az ad app federated-credential create \
    --id "<CLIENT_ID>" \
    --parameters '{"name": "<CONNECTION_NAME>-Federated-Credential", \
    "issuer": "https://token.dynatrace.com", \
    "subject": "dt:connection-id/<OBJECT_ID_FROM_STEP_1>", \
    "audiences": ["<DYNATRACE_ENVIRONMENT_ID>.apps.dynatrace.com/svc-id/com.dynatrace.da"]}'

    Replace the following placeholders with your values and create a federated credential:

    • <CLIENT_ID>: Application (client) ID from the previous step
    • <CONNECTION_NAME>: Descriptive name for the federated credential
    • <OBJECT_ID_FROM_STEP_1>: The Azure connection ID (in objectId field) returned in step 1
    • <DYNATRACE_ENVIRONMENT_ID>: Your Dynatrace environment ID (for example, abc12345)

  3. Get the object ID of the service principal.

    az ad sp show --id "<CLIENT_ID>" --query "{OBJECT_ID:id}" --output table

  4. Assign the Monitoring Reader Azure RBAC built-in role to the service principal at the appropriate monitoring scope.

    For Management Group scope:

    The --scope requires the management group resource ID, not its display name. To find it:

    az account management-group list --query "[].{name:name, displayName:displayName}" --output table

    Use the value in the Name column as <MANAGEMENT_GROUP_ID>.

    az role assignment create \
    --assignee-object-id "<OBJECT_ID>" \
    --role "Monitoring Reader" \
    --scope "/providers/Microsoft.Management/managementGroups/<MANAGEMENT_GROUP_ID>" \
    --assignee-principal-type ServicePrincipal \
    --description "Dynatrace Monitoring"

    For Subscription scope:

    az role assignment create \
    --assignee-object-id "<OBJECT_ID>" \
    --role "Monitoring Reader" \
    --scope "/subscriptions/<SUBSCRIPTION_ID>" \
    --assignee-principal-type ServicePrincipal \
    --description "Dynatrace Monitoring"

  5. Verify the role assignment was successful. You should see the Monitoring Reader role listed at your specified scope.

    az role assignment list \
    --assignee-object-id "<OBJECT_ID>" \
    --output table
3. Update the Azure connection with service principal details

Update the connection with the tenant ID and application ID returned in step 2.

dtctl update azure connection --name "<CONNECTION_NAME>" --directoryId "<TENANT_ID>" --applicationId "<CLIENT_ID>"

Replace the following placeholders with your values:

  • <CONNECTION_NAME>: The connection name used in step 1
  • <TENANT_ID>: Microsoft Entra ID tenant (directory) ID
  • <CLIENT_ID>: Application (client) ID of the service principal

If the command returns an AADSTS70025 error, the federated credential is still propagating in Microsoft Entra ID. Wait a few seconds and retry.

Alternative: Apply via YAML

For GitOps or infrastructure-as-code workflows, you can apply the same update using a YAML file instead of CLI flags. Populate the placeholders and run dtctl apply:

schemaId: builtin:hyperscaler-authentication.connections.azure
scope: environment
objectid: <CONNECTION_OBJECT_ID>
value:
  name: "<CONNECTION_NAME>"
  type: federatedIdentityCredential
  federatedIdentityCredential:
    directoryId: "<TENANT_ID>"
    applicationId: "<CLIENT_ID>"
    consumers:
      - SVC:com.dynatrace.da

Replace the following placeholders with your values:

  • <CONNECTION_OBJECT_ID>: The connection object ID returned in step 1
  • <CONNECTION_NAME>: The connection name used in step 1
  • <TENANT_ID>: Microsoft Entra ID tenant (directory) ID
  • <CLIENT_ID>: Application (client) ID of the service principal
dtctl apply -f azure-connection-federated.yaml

After successful completion, proceed to Create a new Azure monitoring configuration using the CLI.

Client secret authentication uses a password-based credential. Consider using federated identity credentials for improved security in production environments.

When generating a client secret, Microsoft recommends using an expiration duration of less than 12 months for enhanced security.

Ensure client secrets are updated in Dynatrace before they expire.

  1. Register a new application in your Microsoft Entra ID tenant. This creates a service principal with a client secret.

    For details, see How to register an app in Microsoft Entra ID.

    az ad sp create-for-rbac \
    --name "<CONNECTION_NAME>" \
    --query "{CLIENT_ID:appId, TENANT_ID:tenant, CLIENT_SECRET:password}" \
    --output table

    Replace the <CONNECTION_NAME> placeholder with a descriptive name for the connection (used in Dynatrace).

  2. Get the object ID of the service principal.

    az ad sp show --id "<CLIENT_ID>" --query "{OBJECT_ID:id}" --output table

  3. Assign the Monitoring Reader Azure RBAC built-in role to the service principal at the appropriate monitoring scope.

  • For Management Group scope:

The --scope requires the management group resource ID, not its display name. To find it:

az account management-group list --query "[].{name:name, displayName:displayName}" --output table

Use the value in the Name column as <MANAGEMENT_GROUP_ID>.

az role assignment create \
--assignee-object-id "<OBJECT_ID>" \
--role "Monitoring Reader" \
--scope "/providers/Microsoft.Management/managementGroups/<MANAGEMENT_GROUP_ID>" \
--assignee-principal-type ServicePrincipal \
--description "Dynatrace Monitoring"
  • For Subscription scope:
az role assignment create \
--assignee-object-id "<OBJECT_ID>" \
--role "Monitoring Reader" \
--scope "/subscriptions/<SUBSCRIPTION_ID>" \
--assignee-principal-type ServicePrincipal \
--description "Dynatrace Monitoring"

  1. Verify the role assignment was successful. You should see the Monitoring Reader role listed at your specified scope.

    az role assignment list \
    --assignee-object-id "<OBJECT_ID>" \
    --output table

  2. Create the Azure connection.

    Populate the placeholders in the YAML file:

    schemaId: builtin:hyperscaler-authentication.connections.azure
    scope: environment
    value:
      name: "<CONNECTION_NAME>"
      type: clientSecret
      clientSecret:
        directoryId: "<TENANT_ID>"
        applicationId: "<CLIENT_ID>"
        clientSecret: "<CLIENT_SECRET>"
        consumers:
          - SVC:com.dynatrace.da

    Then apply it:

    dtctl apply -f azure-connection-secret.yaml

    The command confirms successful creation and displays the connection object ID. Save this ID. You'll need it if creating the monitoring configuration via YAML.

Create a new Azure monitoring configuration with CLI

The monitoring configuration defines which Azure services to monitor, which regions to poll, and how to filter and enrich telemetry data.

Get API schema version

Run the following command to get the active schema version of the Azure monitoring extension:

dtctl describe extension com.dynatrace.extension.da-azure

The output includes the active schema version:

...
Active Version: 1.0.0
...
Available Versions:
* 1.0.0
  1.0.5

Use the Active Version value as <API_SCHEMA_VERSION> in the monitoring configuration YAML.

If you omit version from your YAML, dtctl apply automatically uses the latest available version and prints it to stderr. Run this command to see what version is used.

Basic monitoring configuration

Create a monitoring configuration with defaults. By default, dtctl enables all *_essential feature sets and all Azure regions.

dtctl create azure monitoring --name "<CONFIGURATION_NAME>" --credentials "<CONNECTION_NAME>"

Replace the following placeholders with your values:

  • <CONFIGURATION_NAME>: Name of the monitoring configuration (letters, numbers, hyphens only; must start with a letter)
  • <CONNECTION_NAME>: Name of the Azure connection created in the previous step

To restrict the monitored regions or feature sets, use the optional flags:

FlagDescription

--locationFiltering

Comma-separated Azure region names to monitor (for example, eastus,westeurope,northeurope)

--featureSets

Comma-separated feature set names to enable

Run these commands to discover valid values for each flag:

dtctl get azure monitoring-locations     # Lists all valid Azure region names
dtctl get azure monitoring-feature-sets  # Lists all valid feature set names
Required

To allow telemetry signals-in-context and inventory on all relevant regions, the topology service must poll for topology signals on all regions where any signal is ingested.

Advanced configuration via YAML

For more granular control—including subscription filtering, tag filtering, tag enrichment, and Dynatrace label mapping—create a YAML file and use dtctl apply.

The monitoring configuration supports additional filtering and enrichment options to customize what resources are monitored and how data is enriched in Dynatrace.

Subscription filtering

Control which Azure subscriptions to monitor using subscriptionfilteringmode and subscriptionFiltering.

  • Include mode: Monitor only specified subscriptions:

    subscriptionfilteringmode: INCLUDE
    subscriptionFiltering:
      - 00000000-0000-0000-0000-000000000001
      - 00000000-0000-0000-0000-000000000002

  • Exclude mode: Monitor all subscriptions except specified ones:

    subscriptionfilteringmode: EXCLUDE
    subscriptionFiltering:
      - 00000000-0000-0000-0000-000000000001
Tag filtering

Filter which Azure resources to monitor based on their tags using tagfiltering.

  • Include mode: Monitor only resources with matching tags:

    tagfiltering:
      - key: environment
        value: production
        condition: INCLUDE
      - key: monitoring
        value: enabled
        condition: INCLUDE

    If you ingest Azure logs or events, also add the following entry to your include filters. For details, see Event Hubs requirements.

    - key: managed-by
      value: dynatrace
      condition: INCLUDE

  • Exclude mode: Monitor all resources except those with matching tags:

    tagfiltering:
      - key: monitoring
        value: disabled
        condition: EXCLUDE

Azure tag-based filters instruct the Dynatrace poll services to include or exclude signals for ingest based on Azure tag key-value pairs.

  • Filters apply to both metric ingest and topology ingest.
  • You can configure a maximum of five include and five exclude tag key-value pairs per connection.
  • Filters evaluate only the tags that Azure reports for the resource itself. Dynatrace doesn't add, derive, or inherit tags before filtering.

If resources that don't match your filter are still monitored, see Troubleshooting.

Tag enrichment

Enrich Dynatrace signals with Azure resource tags by specifying tag keys in tagenrichment. The specified Azure tag keys are added as attributes to signals in Dynatrace.

tagenrichment:
  - environment
  - cost-center
  - application
  - team
Label mapping for cost allocation and security context

Map Azure tags or literal values to Dynatrace labels using dtlabelsenrichment. This is particularly useful for cost allocation (dt.cost.costcenter, dt.cost.product) and security context (dt.security_context).

  • Using literal values

    dtlabelsenrichment:
      dt.security_context:
        literal: production
        tagkey: ""
      dt.cost.costcenter:
        literal: CC-12345
        tagkey: ""
      dt.cost.product:
        literal: MyProduct
        tagkey: ""

  • Using Azure tags

    dtlabelsenrichment:
      dt.security_context:
        literal: ""
        tagkey: environment      # Azure tag key whose value is used
      dt.cost.costcenter:
        literal: ""
        tagkey: cost-center
      dt.cost.product:
        literal: ""
        tagkey: product-name

When using tagkey, the value of the specified Azure tag is used as the label value in Dynatrace. Leave literal empty when using tagkey, and vice versa.

Complete example with advanced options
# objectid: <EXISTING_CONFIG_ID_IF_UPDATING>
scope: integration-azure
value:
  enabled: true
  description: <CONFIGURATION_NAME>
  azure:
    subscriptionfilteringmode: INCLUDE
    subscriptionFiltering:
      - 00000000-0000-0000-0000-000000000001
      - 00000000-0000-0000-0000-000000000002
    credentials:
      - enabled: true
        description: <CONNECTION_NAME>
        connectionid: <AZURE_CONNECTION_OBJECT_ID>
        serviceprincipalid: <CLIENT_ID>
        type: FEDERATED    # Use SECRET for clientSecret connections
    locationfiltering:
      - eastus
      - westeurope
      - northeurope
      # Run 'dtctl get azure monitoring-locations' for the complete list
    tagfiltering:
      - key: environment
        value: production
        condition: INCLUDE
      - key: monitoring
        value: disabled
        condition: EXCLUDE
    tagenrichment:
      - environment
      - cost-center
    dtlabelsenrichment:
      dt.cost.costcenter:
        literal: ""
        tagkey: cost-center
      dt.cost.product:
        literal: MyProduct
        tagkey: ""
      dt.security_context:
        literal: ""
        tagkey: environment
  featuresets:
    - microsoft_compute.virtualmachines_essential
    - microsoft_storage.storageaccounts_essential
    - microsoft_web.sites_functionapp_essential
    # Run 'dtctl get azure monitoring-feature-sets' for the complete list
dtctl apply -f azure-monitoring-config.yaml

If you encounter errors, validate that:

  • The platform token has the required permissions
  • The connection object ID is correct, and all required fields are populated.

After successful completion, go to Settings > Cloud and virtualization > Azure. The newly created connection should be visible and in healthy state within a few minutes.

Manage an existing Azure connection

To inspect, update, or delete an existing connection or monitoring configuration, or to roll over the client secret of a service principal, see Manage your Azure connections via CLI.

What's next?

  • To enable Azure log and event ingestion, deploy the ARM template for your connection. For details, see Azure logs and events.
  • Go to Clouds Clouds. Azure resources with telemetry should start to appear shortly.

Supported Azure services

For a full list of supported Azure services, including topology relationships and available metric collection sets, see Supported Azure services.

Troubleshooting

Error: "Authorization_RequestDenied" when creating the service principal

This error occurs when your Azure identity lacks permission to create applications in Microsoft Entra ID.

Solution: Ask your Azure administrator to grant you the Application Administrator role or create the service principal on your behalf.

Error: "AuthorizationFailed" when assigning the Monitoring Reader role

This error occurs when your Azure identity lacks permission to assign roles at the specified scope.

Solution:

  • Ensure you have Owner or User Access Administrator role at the target subscription or management group.
  • For Management Group scope, confirm you have permissions at the management group level, not just individual subscriptions.
  • If using Management Group scope, verify you use the resource ID in --scope, not the display name. Run az account management-group list and use the Name column value. Display names differ from IDs and produce the same error.
Error: "AADSTS70025" when updating the Azure connection

This error indicates that Microsoft Entra ID has not yet propagated the federated credential configured in step 2.

Solution: Wait a few seconds for propagation to complete, then retry the dtctl update azure connection command.

dtctl fails with authentication errors

This error occurs when the Dynatrace platform token is invalid or lacks required permissions.

Solution:

  • Run dtctl config view to verify your environment URL and token reference are configured correctly.
  • Verify your platform token is valid and has not expired.
  • Ensure the token has the required scopes: settings:schemas:read, settings:objects:read, settings:objects:write.
  • Confirm you are using the correct Dynatrace environment URL.
Resources that don't match my tag-based filter are still monitored

An include filter can only match a resource that Azure reports the tag for. A resource remains monitored when:

  • Its Azure resource type doesn't support tags. Many types, especially child types, have no tags property. For example, Microsoft.DBforPostgreSQL/flexibleServers supports tags, but Microsoft.DBforPostgreSQL/flexibleServers/configurations doesn't. To check a type, see Tag support for Azure resources.

  • The tag is set on the resource group or the parent resource, not on the resource. Azure resources don't inherit tags from a resource group or subscription, and Dynatrace doesn't propagate tags from a parent resource to its children. The same applies to resources in Azure-managed resource groups, such as the MC_<cluster-name>_<region> group that Azure Kubernetes Service creates. Dynatrace collects these resources together with their parent, but Azure doesn't inherit the parent's tags to them. Configure tag inheritance in Azure instead. For details, see Configure tag inheritance in Azure.

Solution: To find the resources your include filter can't match, run the query in Verify which entities your tag filter matches.

Topology is visible but Azure Monitor metrics are missing for a subscription

This issue occurs when resources from a subscription appear in Clouds Clouds but have no metrics, while metrics arrive for other subscriptions on the same connection. The connection reports as healthy, and Dynatrace might log DATA_ACQUISITION_EVENT warnings that report the identity isn't authorized to query metric data.

Two causes produce this symptom:

  • The service principal doesn't have the Monitoring Reader role at subscription scope or higher. Dynatrace polls metrics with the Azure Monitor metrics:getBatch API, which is a subscription-level API. The request fails unless the service principal has Monitoring Reader on the subscription itself, either assigned directly or inherited from a management group. A role assigned only on resource groups or individual resources isn't enough, even if it covers every resource in the subscription. For details, see 401 authorization errors.
  • The Microsoft.Insights resource provider isn't registered in the affected subscription. Azure Monitor doesn't return metrics for a subscription without it, even when the service principal has the Monitoring Reader role. For details, see 403 authorization failures.

Solution:

  1. Verify that the service principal has the Monitoring Reader role at subscription scope or higher:

    az role assignment list --assignee <CLIENT_ID> --subscription <SUBSCRIPTION_ID> --include-inherited --query "[?roleDefinitionName=='Monitoring Reader'].scope" --output tsv

    If the output is empty, assign the role at subscription or management group scope. For details, see Assign Azure roles using Azure CLI.

  2. Check and register Microsoft.Insights in the affected subscription.

  3. Wait for the next polling cycles. The metric poller runs every five minutes.

To find the warning events for your connection, run this query. Replace <CONFIGURATION_ID> with the Monitoring Configuration ID shown on the Overview tab of your connection. For details, see Connection properties.

fetch dt.system.events
| filter event.kind == "DATA_ACQUISITION_EVENT"
| filter da.clouds.configurationId == "<CONFIGURATION_ID>"
| sort timestamp desc
Related tags
Infrastructure Observability