Habilitar o log de depuração

  • Artigo

Para solucionar um erro de implantação, você poderá habilitar o registro em log de depuração para obter mais informações. O registro em log de depuração funciona para implantações com arquivos Bicep ou modelos do ARM (Azure Resource Manager). Você pode obter dados sobre a solicitação e a resposta de uma implantação para saber a causa de um problema.

Aviso

O registro em log de depuração poderá expor segredos, como senhas ou operações listKeys. Habilite o log de depuração somente quando você precisar solucionar um erro de implantação. Ao concluir a depuração, remova o histórico da implantação de depuração.

Configurar o log de depuração

Use o Azure PowerShell para habilitar o registro em log de depuração que preenche as propriedades request e response com as informações de implantação para a solução de problemas. Não é possível habilitar o registro em log de depuração usando a CLI do Azure.

O registro em log de depuração é habilitado apenas para o arquivo Bicep ou modelo do ARM principal. Se estiver usando módulos Bicep ou modelos do ARM aninhados, consulte Depurar modelo aninhado.

Para uma implantação de grupo de recursos, use New-AzResourceGroupDeployment e defina o parâmetro DeploymentDebugLogLevel como All, ResponseContent ou RequestContent.

Quando o registro em log de depuração estiver habilitado aparecerá um aviso informando que segredos, como senhas ou operações listKeys, poderão ser registrados e exibidos quando você usar comandos como Get-AzResourceGroupDeploymentOperation para obter informações sobre as operações de implantação.

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

A saída da implantação mostra o nível de registros em log de depuração.

DeploymentDebugLogLevel : RequestContent, ResponseContent

O parâmetro DeploymentDebugLogLevel está disponível para outros escopos de implantação: assinatura, grupo de gerenciamento e locatário.

Informações de depuração do log

Após habilitar o log de depuração, você poderá obter mais informações sobre as operações de implantação. Os cmdlets do Azure PowerShell para operações de implantação não geram as propriedades request e response. Para obter as informações dessas propriedades será necessário usar a CLI do Azure.

Se você não habilitar os registros em log de depuração no comando de implantação, ainda assim poderá obter as informações de operações de implantação. Use o Azure PowerShell ou a CLI do Azure para obter o código de status, a mensagem de status e o estado de provisionamento.

Para uma implantação de grupo de recursos, use Get-AzResourceGroupDeploymentOperation para obter operações de implantação.

Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup

Você pode especificar uma propriedade como StatusCode, StatusMessage ou ProvisioningState para filtrar a saída.

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

Para obter mais informações, confira a documentação para escopos de operação de implantação: assinatura, grupo de gerenciamento e locatário.

Depurar modelo aninhado

O modelo do ARM principal e os modelos aninhados possuem seus próprios nomes de implantação e o histórico de implantação. O módulo e arquivo Bicep principal também usam um nome de implantação e um histórico de implantação separados.

Modelo de ARM

Para registrar as informações de depuração para um modelo do ARM aninhado, use Microsoft.Resources/deployments com a propriedade debugSetting.

O seguinte exemplo mostra um modelo aninhado com o debugSetting para registrar a solicitação e a resposta da implantação.

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

O modelo do ARM principal e os modelos aninhados possuem seus próprios nomes de implantação e o histórico de implantação. Se você quiser que as propriedades request e response contenham as informações da solução de problemas, esteja ciente dos seguintes cenários de implantação:

  • As propriedades request e response conterão valores null para o modelo principal e o modelo aninhado quando DeploymentDebugLogLevel não estiver ativado com o comando de implantação.
  • Quando o comando de implantação habilitar DeploymentDebugLogLevel, as propriedades request e response conterão as informações apenas do modelo principal. As propriedades do modelo aninhado contêm valores null.
  • Quando um modelo aninhado usar o debugSetting e o comando de implantação não incluir DeploymentDebugLogLevel, somente a implantação do modelo aninhado terá valores para as propriedades request e response. As propriedades do modelo principal contêm valores null.
  • Para obter request e response para o modelo principal e o modelo aninhado, especifique DeploymentDebugLogLevel no comando de implantação e use debugSetting no modelo aninhado.

Arquivo Bicep

A recomendação para arquivos Bicep é usar módulos em vez de modelos aninhados com Microsoft.Resources/deployments. A mensagem de status, o código de status e o estado de provisionamento incluirão as informações para o módulo e o arquivo Bicep principal que você poderá usar para solucionar problemas de implantação.

Se você habilitar DeploymentDebugLogLevel pelo comando de implantação, as propriedades request e response conterão as informações somente para a implantação do arquivo Bicep principal.

Remover o histórico de implantações de depuração

Ao concluir a depuração, será necessário remover o histórico de implantação para impedir que pessoas que tenham acesso vejam as informações confidenciais que possam ter sido registradas. Para cada nome de implantação utilizado durante a depuração, execute o comando para remover o histórico de implantação.

Para remover o histórico de implantações de uma implantação de grupo de recursos, use Remove-AzResourceGroupDeployment.

Remove-AzResourceGroupDeployment -ResourceGroupName examplegroup -Name exampledeployment

O comando retorna True quando é bem-sucedido.

Para obter mais informações sobre o histórico de implantações, consulte a documentação dos escopos de implantação: assinatura, grupo de gerenciamento e locatário.

Próximas etapas