Skip to content

Commit d8df8dd

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #222679 from davidsmatlak/ds-ghi-102047
Updates ARM debug logging article
2 parents e5b6fde + 8cce719 commit d8df8dd

File tree

1 file changed

+81
-40
lines changed

1 file changed

+81
-40
lines changed

‎articles/azure-resource-manager/troubleshooting/enable-debug-logging.md

Lines changed: 81 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -3,27 +3,28 @@ title: Enable debug logging
33
description: Describes how to enable debug logging to troubleshoot Azure resources deployed with Bicep files or Azure Resource Manager templates (ARM templates).
44
tags: top-support-issue
55
ms.topic: troubleshooting
6-
ms.date: 09/14/2022
6+
ms.date: 12/30/2022
77
ms.custom: devx-track-azurepowershell
88
---
99

1010
# Enable debug logging
1111

12-
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.
12+
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.
1313

1414
> [!WARNING]
15-
> Debug logging can expose secrets like passwords or `listKeys`. Only enable debug logging when you need to troubleshoot a deployment error.
15+
> 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](#remove-debug-deployment-history).
1616
1717
## Set up debug logging
1818

19-
Use Azure PowerShell to enable debug logging and view the results with Azure PowerShell or Azure CLI.
19+
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.
2020

21-
# [PowerShell](#tab/azure-powershell)
21+
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](#debug-nested-template).
2222

23-
For a resource group deployment, use [New-AzResourceGroupDeployment](/powershell/module/az.resources/new-azresourcegroupdeployment) to set the `DeploymentDebugLogLevel` parameter to `All`, `ResponseContent`, or `RequestContent`.
23+
# [PowerShell](#tab/azure-powershell)
2424

25-
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`.
25+
For a resource group deployment, use [New-AzResourceGroupDeployment](/powershell/module/az.resources/new-azresourcegroupdeployment) and set the `DeploymentDebugLogLevel` parameter to `All`, `ResponseContent`, or `RequestContent`.
2626

27+
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.
2728

2829
```azurepowershell
2930
New-AzResourceGroupDeployment `
@@ -33,7 +34,7 @@ New-AzResourceGroupDeployment `
3334
-DeploymentDebugLogLevel All
3435
```
3536

36-
The output shows the debug logging level.
37+
The deployment's output shows the debug logging level.
3738

3839
```Output
3940
DeploymentDebugLogLevel : RequestContent, ResponseContent
@@ -49,13 +50,13 @@ The `DeploymentDebugLogLevel` parameter is available for other deployment scopes
4950

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

52-
5353
---
5454

55-
5655
## Get debug information
5756

58-
After debug logging is enabled, you can get more information from the deployment operations.
57+
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.
58+
59+
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.
5960

6061
# [PowerShell](#tab/azure-powershell)
6162

@@ -67,12 +68,12 @@ Get-AzResourceGroupDeploymentOperation `
6768
-ResourceGroupName examplegroup
6869
```
6970

70-
You can specify a property, like `StatusMessage` or `StatusCode` to filter the output.
71+
You can specify a property, like `StatusCode`, `StatusMessage`, or `ProvisioningState` to filter the output.
7172

7273
```azurepowershell
7374
(Get-AzResourceGroupDeploymentOperation `
7475
-DeploymentName exampledeployment `
75-
-ResourceGroupName examplegroup).StatusMessage
76+
-ResourceGroupName examplegroup).StatusCode
7677
```
7778

7879
For more information, see the documentation for deployment operation scopes: subscription, management group, and tenant.
@@ -110,18 +111,81 @@ az deployment operation group list \
110111
--query [].properties.response
111112
```
112113

114+
You can use a query to get the properties `statusCode`, `statusMessage`, or `provisioningState` for a deployment.
115+
116+
```azurecli
117+
az deployment operation group list \
118+
--name exampledeployment \
119+
--resource-group examplegroup \
120+
--query [].properties.statusCode
121+
```
122+
113123
For more information, see the documentation for deployment operation scopes: subscription, management group, and tenant.
114124

115125
- [az deployment operation sub list](/cli/azure/deployment/operation/sub#az-deployment-operation-sub-list)
116126
- [az deployment operation mg list](/cli/azure/deployment/operation/mg#az-deployment-operation-mg-list)
117127
- [az deployment operation tenant list](/cli/azure/deployment/operation/tenant#az-deployment-operation-tenant-list)
118128

119-
120129
---
121130

131+
## Debug nested template
132+
133+
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.
134+
135+
### ARM template
136+
137+
To log debug information for a [nested](../templates/linked-templates.md#nested-template) ARM template, use the [Microsoft.Resources/deployments](/azure/templates/microsoft.resources/deployments) with the `debugSetting` property.
138+
139+
The following sample shows a nested template with the `debugSetting` to log the deployment's request and response.
140+
141+
```json
142+
"resources": [
143+
{
144+
"type": "Microsoft.Resources/deployments",
145+
"apiVersion": "2021-04-01",
146+
"name": "nestedTemplateDebug",
147+
"properties": {
148+
"mode": "Incremental",
149+
"template": {
150+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
151+
"contentVersion": "1.0.0.0",
152+
"resources": [
153+
{
154+
"type": "Microsoft.Storage/storageAccounts",
155+
"apiVersion": "2022-05-01",
156+
"name": "[variables('storageAccountName')]",
157+
"location": "[parameters('location')]",
158+
"sku": {
159+
"name": "[parameters('storageAccountType')]"
160+
},
161+
"kind": "StorageV2"
162+
}
163+
]
164+
},
165+
"debugSetting": {
166+
"detailLevel": "requestContent, responseContent"
167+
}
168+
}
169+
}
170+
],
171+
```
172+
173+
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:
174+
175+
- The `request` and `response` properties contain `null` values for the main template and nested template when `DeploymentDebugLogLevel` isn't enabled with deployment command.
176+
- 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.
177+
- 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.
178+
- 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.
179+
180+
### Bicep file
181+
182+
The recommendation for Bicep files is to use [modules](../bicep/modules.md) 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.
183+
184+
If you enable `DeploymentDebugLogLevel` from the deployment command, the `request` and `response` properties will contain information only for the main Bicep file's deployment.
185+
122186
## Remove debug deployment history
123187

124-
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.
188+
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.
125189

126190
# [PowerShell](#tab/azure-powershell)
127191

@@ -148,39 +212,16 @@ To remove deployment history for a resource group deployment, use [az deployment
148212
az deployment group delete --resource-group examplegroup --name exampledeployment
149213
```
150214

215+
The command returns to the command prompt when it's completed.
216+
151217
For more information, see the documentation for deployment scopes: subscription, management group, and tenant.
152218

153219
- [az deployment sub delete](/cli/azure/deployment/sub#az-deployment-sub-delete)
154220
- [az deployment mg delete](/cli/azure/deployment/mg#az-deployment-mg-delete)
155221
- [az deployment tenant delete](/cli/azure/deployment/tenant#az-deployment-tenant-delete)
156222

157-
158223
---
159224

160-
## Nested template
161-
162-
To log debug information for a [nested](../templates/linked-templates.md#nested-template) ARM template, use the [Microsoft.Resources/deployments](/azure/templates/microsoft.resources/deployments) `debugSetting` property.
163-
164-
```json
165-
{
166-
"type": "Microsoft.Resources/deployments",
167-
"apiVersion": "2020-10-01",
168-
"name": "nestedTemplate",
169-
"properties": {
170-
"mode": "Incremental",
171-
"templateLink": {
172-
"uri": "{template-uri}",
173-
"contentVersion": "1.0.0.0"
174-
},
175-
"debugSetting": {
176-
"detailLevel": "requestContent, responseContent"
177-
}
178-
}
179-
}
180-
```
181-
182-
Bicep uses [modules](../bicep/modules.md) rather than nested templates.
183-
184225
## Next steps
185226

186227
- [Common deployment errors](common-deployment-errors.md)

0 commit comments

Comments
 (0)