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:

Tool	Minimum version	Notes
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 scope	Required information
`Management Group`	Management Group ID (found in Azure portal under Management groups)
`Subscription`	Subscription ID (found in Azure portal under Subscriptions)

3. Dynatrace

Configure dtctl with your Dynatrace environment:

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"
```
Replace <YOUR_ENVIRONMENT_ID> with your Dynatrace environment ID (for example, abc12345).
Verify your configuration:
```
dtctl doctor
```
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 method	Description	Notes
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.

Register a new application in your Microsoft Entra ID tenant. Learn more: 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).
Create 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. Learn more: 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/<CONNECTION_ID_FROM_STEP_1>", \
"audiences": ["<DYNATRACE_ENVIRONMENT_ID>.apps.dynatrace.com/svc-id/com.dynatrace.da"]}'
```
Replace the following placeholders with your values:
- <CLIENT_ID>: Application (client) ID from the previous step
- <CONNECTION_NAME>: Descriptive name for the federated credential
- <CONNECTION_ID_FROM_STEP_1>: The connection object ID returned in step 1
- <DYNATRACE_ENVIRONMENT_ID>: Your Dynatrace environment ID (for example, abc12345)

Get the object ID of the service principal.

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

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"

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

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 will be 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:

Flag	Description
`--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

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

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

Tag enrichment

Enrich Dynatrace signals with Azure resource tags by specifying tag keys in tagenrichment. The specified Azure tag keys will be 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 will be 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.

Additional CLI capabilities

Inspect and update existing connections and configurations

# List all Azure connections and monitoring configurations
dtctl get azure connections
dtctl get azure monitoring

# Show details of a specific connection or configuration
dtctl describe azure connection <AZURE_CONNECTION_ID>
dtctl describe azure monitoring <CONFIGURATION_NAME>

# Update service principal credentials for an existing connection
dtctl update azure connection --name "<CONNECTION_NAME>" --directoryId "<TENANT_ID>" --applicationId "<CLIENT_ID>"

# Update monitored regions for an existing configuration
dtctl update azure monitoring --name "<CONFIGURATION_NAME>" --locationFiltering "eastus,westeurope"

# Update monitored feature sets for an existing configuration
dtctl update azure monitoring \
  --name "<CONFIGURATION_NAME>" \
  --featureSets "microsoft_compute.virtualmachines_essential,microsoft_web.sites_functionapp_essential"

# Delete a connection or configuration
dtctl delete azure connection <CONNECTION_NAME>
dtctl delete azure monitoring <CONFIGURATION_NAME>

Get help

dtctl --help
dtctl create azure connection --help
dtctl create azure monitoring --help

Add --dry-run to any command to preview what would be executed without making any changes.

Roll over a client secret

This procedure applies to connections that use client secret authentication. If you want to eliminate ongoing secret rotation, consider migrating to federated identity credentials instead.

Update the connection in Dynatrace before the existing secret expires to avoid a monitoring gap.

Replace the following placeholders with your values:
- <APPLICATION_ID>: Application (client) ID of the Azure service principal
- <CONNECTION_NAME>: Name of the existing Dynatrace Azure connection
- <NEW_CLIENT_SECRET>: New client secret generated in step 3—save it immediately, it cannot be retrieved later
- <OLD_KEY_ID>: The keyId of the old credential captured in step 2
- <AZURE_CONNECTION_ID>: The objectId of the existing Azure connection—run dtctl get azure connections to retrieve it
List the current credentials for your service principal to capture the keyId of the existing secret.
```
az ad app credential list --id "<APPLICATION_ID>" --output table
```
Note the keyId value. You'll need it in step 6 to remove the old secret.
Generate a new client secret. The --append flag adds the new credential without invalidating the existing one, so Dynatrace monitoring continues uninterrupted during the rollover.
```
az ad app credential reset \
--id "<APPLICATION_ID>" \
--append \
--display-name "Dynatrace rollover $(date +%Y-%m-%d)" \
--query password \
--output tsv
```
The command outputs the new secret. Save this value as <NEW_CLIENT_SECRET>—it cannot be retrieved again after this point.

Update your connection YAML with the new secret value and apply it.

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

dtctl apply -f azure-connection-secret.yaml

dtctl update azure connection only updates --directoryId and --applicationId. To update the secret value itself, you must use dtctl apply -f.

Verify that the connection is healthy.

dtctl describe azure connection "<AZURE_CONNECTION_ID>"

Once the connection is Healthy in Dynatrace, remove the old secret from Azure.

az ad app credential delete \
--id "<APPLICATION_ID>" \
--key-id "<OLD_KEY_ID>"

What's next?

To enable Azure log and event ingestion, deploy the ARM template for your connection. See Azure logs and events.
Go to 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 are using 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.

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:

Tool	Minimum version	Notes
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 scope	Required information
`Management Group`	Management Group ID (found in Azure portal under Management groups)
`Subscription`	Subscription ID (found in Azure portal under Subscriptions)

3. Dynatrace

Configure dtctl with your Dynatrace environment:

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"
```
Replace <YOUR_ENVIRONMENT_ID> with your Dynatrace environment ID (for example, abc12345).
Verify your configuration:
```
dtctl doctor
```
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 method	Description	Notes
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.

Register a new application in your Microsoft Entra ID tenant. Learn more: 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).
Create 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. Learn more: 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/<CONNECTION_ID_FROM_STEP_1>", \
"audiences": ["<DYNATRACE_ENVIRONMENT_ID>.apps.dynatrace.com/svc-id/com.dynatrace.da"]}'
```
Replace the following placeholders with your values:
- <CLIENT_ID>: Application (client) ID from the previous step
- <CONNECTION_NAME>: Descriptive name for the federated credential
- <CONNECTION_ID_FROM_STEP_1>: The connection object ID returned in step 1
- <DYNATRACE_ENVIRONMENT_ID>: Your Dynatrace environment ID (for example, abc12345)

Get the object ID of the service principal.

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

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"

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

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 will be 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:

Flag	Description
`--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

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

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

Tag enrichment

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

tagenrichment:
  - environment
  - cost-center
  - application
  - team

Label mapping for cost allocation and 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 will be 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.

Additional CLI capabilities

Inspect and update existing connections and configurations

# List all Azure connections and monitoring configurations
dtctl get azure connections
dtctl get azure monitoring

# Show details of a specific connection or configuration
dtctl describe azure connection <AZURE_CONNECTION_ID>
dtctl describe azure monitoring <CONFIGURATION_NAME>

# Update service principal credentials for an existing connection
dtctl update azure connection --name "<CONNECTION_NAME>" --directoryId "<TENANT_ID>" --applicationId "<CLIENT_ID>"

# Update monitored regions for an existing configuration
dtctl update azure monitoring --name "<CONFIGURATION_NAME>" --locationFiltering "eastus,westeurope"

# Update monitored feature sets for an existing configuration
dtctl update azure monitoring \
  --name "<CONFIGURATION_NAME>" \
  --featureSets "microsoft_compute.virtualmachines_essential,microsoft_web.sites_functionapp_essential"

# Delete a connection or configuration
dtctl delete azure connection <CONNECTION_NAME>
dtctl delete azure monitoring <CONFIGURATION_NAME>

Get help

dtctl --help
dtctl create azure connection --help
dtctl create azure monitoring --help

Add --dry-run to any command to preview what would be executed without making any changes.

Roll over a client secret

This procedure applies to connections that use client secret authentication. If you want to eliminate ongoing secret rotation, consider migrating to federated identity credentials instead.

Update the connection in Dynatrace before the existing secret expires to avoid a monitoring gap.

Replace the following placeholders with your values:
- <APPLICATION_ID>: Application (client) ID of the Azure service principal
- <CONNECTION_NAME>: Name of the existing Dynatrace Azure connection
- <NEW_CLIENT_SECRET>: New client secret generated in step 3—save it immediately, it cannot be retrieved later
- <OLD_KEY_ID>: The keyId of the old credential captured in step 2
- <AZURE_CONNECTION_ID>: The objectId of the existing Azure connection—run dtctl get azure connections to retrieve it
List the current credentials for your service principal to capture the keyId of the existing secret.
```
az ad app credential list --id "<APPLICATION_ID>" --output table
```
Note the keyId value. You'll need it in step 6 to remove the old secret.
Generate a new client secret. The --append flag adds the new credential without invalidating the existing one, so Dynatrace monitoring continues uninterrupted during the rollover.
```
az ad app credential reset \
--id "<APPLICATION_ID>" \
--append \
--display-name "Dynatrace rollover $(date +%Y-%m-%d)" \
--query password \
--output tsv
```
The command outputs the new secret. Save this value as <NEW_CLIENT_SECRET>—it cannot be retrieved again after this point.

Update your connection YAML with the new secret value and apply it.

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

dtctl apply -f azure-connection-secret.yaml

dtctl update azure connection only updates --directoryId and --applicationId. To update the secret value itself, you must use dtctl apply -f.

Verify that the connection is healthy.

dtctl describe azure connection "<AZURE_CONNECTION_ID>"

Once the connection is Healthy in Dynatrace, remove the old secret from Azure.

az ad app credential delete \
--id "<APPLICATION_ID>" \
--key-id "<OLD_KEY_ID>"

What's next?

To enable Azure log and event ingestion, deploy the ARM template for your connection. See Azure logs and events.
Go to 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 are using 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.