Enable debug logging

To troubleshoot a deployment error, enable debug logging to get more information. Debug logging works for deployments using Bicep files or Azure Resource Manager templates (ARM templates). You can get data about a deployment's request and response to learn the cause of a problem.

Warning

Debug logging can expose secrets like passwords or listKeys. Only enable debug logging when you need to troubleshoot a deployment error.

Set up debug logging

Use Azure PowerShell to enable debug logging and view the results with Azure PowerShell or Azure CLI.

PowerShell

For a resource group deployment, use New-AzResourceGroupDeployment to set the DeploymentDebugLogLevel parameter to All, ResponseContent, or RequestContent.

When debug logging is enabled, a warning is displayed that secrets like passwords or listKeys can be logged and displayed when you get deployment operations with commands like Get-AzResourceGroupDeploymentOperation.

New-AzResourceGroupDeployment `
  -Name exampledeployment `
  -ResourceGroupName examplegroup `
  -TemplateFile main.bicep `
  -DeploymentDebugLogLevel All

The output shows the debug logging level.

DeploymentDebugLogLevel : RequestContent, ResponseContent

The DeploymentDebugLogLevel parameter is available for other deployment scopes: subscription, management group, and tenant.

• New-AzDeployment
• New-AzManagementGroupDeployment
• New-AzTenantDeployment

Azure CLI

You can't enable debug logging with Azure CLI but you can get debug logging data using the request and response properties.

Get debug information

After debug logging is enabled, you can get more information from the deployment operations.

PowerShell

For a resource group deployment, use Get-AzResourceGroupDeploymentOperation to get deployment operations.

Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup

You can specify a property, like StatusMessage or StatusCode to filter the output.

(Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup).StatusMessage

For more information, see the documentation for deployment operation scopes: subscription, management group, and tenant.

• Get-AzDeploymentOperation
• Get-AzManagementGroupDeploymentOperation
• Get-AzTenantDeploymentOperation

Azure CLI

For a resource group deployment, use az deployment operation group list to get deployment operations.

az deployment operation group list \
  --resource-group examplegroup \
  --name exampledeployment

Use a query to get the request property's content.

az deployment operation group list \
  --name exampledeployment \
  --resource-group examplegroup \
  --query [].properties.request

Use a query to get the response property's content.

az deployment operation group list \
  --name exampledeployment \
  --resource-group examplegroup \
  --query [].properties.response

For more information, see the documentation for deployment operation scopes: subscription, management group, and tenant.

• az deployment operation sub list
• az deployment operation mg list
• az deployment operation tenant list

Remove debug deployment history

When you're finished debugging, you can remove deployment history to prevent anyone who has access from seeing sensitive information that might have been logged. If you used multiple deployment names during debugging, run the command for each deployment name.

PowerShell

To remove deployment history for a resource group deployment, use Remove-AzResourceGroupDeployment.

Remove-AzResourceGroupDeployment -ResourceGroupName examplegroup -Name exampledeployment

The command returns True when it's successful.

For more information about deployment history, see the documentation for the deployment scopes: subscription, management group, and tenant.

• Remove-AzDeployment
• Remove-AzManagementGroupDeployment
• Remove-AzTenantDeployment

Azure CLI

To remove deployment history for a resource group deployment, use az deployment group delete.

az deployment group delete --resource-group examplegroup --name exampledeployment

For more information, see the documentation for deployment scopes: subscription, management group, and tenant.

• az deployment sub delete
• az deployment mg delete
• az deployment tenant delete

Nested template

To log debug information for a nested ARM template, use the Microsoft.Resources/deployments debugSetting property.

{
  "type": "Microsoft.Resources/deployments",
  "apiVersion": "2020-10-01",
  "name": "nestedTemplate",
  "properties": {
    "mode": "Incremental",
    "templateLink": {
      "uri": "{template-uri}",
      "contentVersion": "1.0.0.0"
    },
    "debugSetting": {
       "detailLevel": "requestContent, responseContent"
    }
  }
}

Bicep uses modules rather than nested templates.

Next steps

• Common deployment errors
• Find error codes
• Create troubleshooting template