Enable debug logging

  • Article

To troubleshoot a deployment error, you can enable debug logging to get more information. Debug logging works for deployments with 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 operations. Only enable debug logging when you need to troubleshoot a deployment error. When you're finished debugging, you should remove the debug deployment history.

Set up debug logging

Use Azure PowerShell to enable debug logging that populates the request and response properties with deployment information for troubleshooting. Debug logging can't be enabled using Azure CLI.

Debug logging is only enabled for the main ARM template or Bicep file. If you're using nested ARM templates or Bicep modules, see Debug nested template.

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

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

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

The deployment's output shows the debug logging level.

DeploymentDebugLogLevel : RequestContent, ResponseContent

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

Get debug information

After debug logging is enabled, you can get more information about the deployment operations. The Azure PowerShell cmdlets for deployment operations don't output the request and response properties. You need to use Azure CLI to get the information from those properties.

If you don't enable debug logging from the deployment command, you can still get deployment operations information. Use Azure PowerShell or Azure CLI to get the status code, status message, and provisioning state.

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

Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup

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

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

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

Debug nested template

The main ARM template and nested templates have their own deployment name and deployment history. The main Bicep file and module also use a separate deployment name and deployment history.

ARM template

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

The following sample shows a nested template with the debugSetting to log the deployment's request and response.

"resources": [
  {
    "type": "Microsoft.Resources/deployments",
    "apiVersion": "2021-04-01",
    "name": "nestedTemplateDebug",
    "properties": {
      "mode": "Incremental",
      "template": {
        "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "resources": [
          {
            "type": "Microsoft.Storage/storageAccounts",
            "apiVersion": "2022-05-01",
            "name": "[variables('storageAccountName')]",
            "location": "[parameters('location')]",
            "sku": {
              "name": "[parameters('storageAccountType')]"
            },
            "kind": "StorageV2"
          }
        ]
      },
      "debugSetting": {
        "detailLevel": "requestContent, responseContent"
      }
    }
  }
],

The main ARM template and nested templates have their own deployment name and deployment history. If you want the request and response properties to contain troubleshooting information, be aware of the following deployment scenarios:

  • The request and response properties contain null values for the main template and nested template when DeploymentDebugLogLevel isn't enabled with deployment command.
  • When the deployment command enables DeploymentDebugLogLevel the request and response properties contain information only for the main template. The nested template's properties contain null values.
  • When a nested template uses the debugSetting and the deployment command doesn't include DeploymentDebugLogLevel only the nested template deployment has values for the request and response properties. The main template's properties contain null values.
  • To get the request and response for the main template and nested template, specify DeploymentDebugLogLevel in the deployment command and use debugSetting in the nested template.

Bicep file

The recommendation for Bicep files is to use modules rather than nested templates with Microsoft.Resources/deployments. The status message, status code, and provisioning state will include information for the main Bicep file and module that you can use to troubleshoot the deployment.

If you enable DeploymentDebugLogLevel from the deployment command, the request and response properties will contain information only for the main Bicep file's deployment.

Remove debug deployment history

When you're finished debugging, you should remove the deployment history to prevent anyone who has access from seeing sensitive information that might have been logged. For each deployment name that you used while debugging, run the command to remove the deployment history.

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.

Next steps