启用调试日志记录

  • 项目

若要排查部署错误，可以启用调试日志记录以获取详细信息。 调试日志记录适用于使用 Bicep 文件或 Azure 资源管理器模板（ARM 模板）进行部署。 可以获取有关部署请求和响应的数据，以了解问题的原因。

警告

调试日志记录可能会公开密码等机密或 listKeys 操作。 仅当需要排查部署错误时才启用调试日志记录。 调试完成后，应删除调试部署历史记录。

设置调试日志记录

使用 Azure PowerShell 启用调试日志记录，以使用部署信息填充 request 和 response 属性来进行故障排除。 无法使用 Azure CLI 启用调试日志记录。

只能为主 ARM 模板或 Bicep 文件启用调试日志记录。 如果使用的是嵌套 ARM 模板或 Bicep 模块，请参阅调试嵌套模板。

对于资源组部署，请使用 New-AzResourceGroupDeployment 并将 DeploymentDebugLogLevel 参数设置为 All、ResponseContent 或 RequestContent。

启用调试日志记录时，会显示一条警告，指出在使用 Get-AzResourceGroupDeploymentOperation 等命令获取有关部署操作的信息时，可能会记录和显示密码等机密或 listKeys 操作。

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

部署的输出显示调试日志记录级别。

DeploymentDebugLogLevel : RequestContent, ResponseContent

DeploymentDebugLogLevel 参数可用于其他部署范围：订阅、管理组和租户。

获取调试信息

启用调试日志记录后，可以获取有关部署操作的详细信息。 针对部署操作的 Azure PowerShell cmdlet 不会输出 request 和 response 属性。 需要使用 Azure CLI 从这些属性获取信息。

如果不通过部署命令启用调试日志记录，仍可以获取部署操作信息。 使用 Azure PowerShell 或 Azure CLI 获取状态代码、状态消息和预配状态。

对于资源组部署，请使用 Get-AzResourceGroupDeploymentOperation 获取部署操作。

Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup

可以指定属性（如 StatusCode、StatusMessage 或 ProvisioningState）来筛选输出。

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

有关详细信息，请参阅部署操作范围的文档：订阅、管理组和租户。

调试嵌套模板

主 ARM 模板和嵌套模板有自己的部署名称和部署历史记录。 主 Bicep 文件和模块也使用单独的部署名称和部署历史记录。

ARM 模板

若要记录嵌套 ARM 模板的调试信息，请使用包含 debugSetting 属性的 Microsoft.Resources/deployments。

以下示例演示一个嵌套模板，其中包含用于记录部署请求和响应的 debugSetting。

"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"
      }
    }
  }
],

主 ARM 模板和嵌套模板有自己的部署名称和部署历史记录。 如果你希望 request 和 response 属性包含故障排除信息，请注意以下部署方案：

  • 未使用部署命令启用 DeploymentDebugLogLevel 时，request 和 response 属性包含主模板和嵌套模板的 null 值。
  • 当部署命令启用 DeploymentDebugLogLevel 时，request 和 response 属性仅包含主模板的信息。 嵌套模板的属性包含 null 值。
  • 当嵌套模板使用 debugSetting 且部署命令不包含 DeploymentDebugLogLevel 时，只有嵌套模板部署具有 request 和 response 属性的值。 主模板的属性包含 null 值。
  • 若要获取主模板和嵌套模板的 request 和 response，请在部署命令中指定 DeploymentDebugLogLevel，并在嵌套模板中使用 debugSetting。

Bicep 文件

对于 Bicep 文件，建议在 Microsoft.Resources/deployments 中使用模块而不是嵌套模板。 状态消息、状态代码和预配状态将包含可用于排查部署问题的主 Bicep 文件和模块的信息。

如果从部署命令启用 DeploymentDebugLogLevel，request 和 response 属性仅包含主 Bicep 文件部署的信息。

移除调试部署历史记录

完成调试后，应删除部署历史记录，以防止任何有访问权限的人员看到可能已记录的敏感信息。 有关在调试时使用的每个部署名称，请运行该命令删除部署历史记录。

若要移除资源组部署的部署历史记录，请使用 Remove-AzResourceGroupDeployment。

Remove-AzResourceGroupDeployment -ResourceGroupName examplegroup -Name exampledeployment

该命令在成功后返回 True。

有关部署历史记录的详细信息，请参阅部署范围的文档：订阅、管理组和租户。

后续步骤