Condividi tramite


Abilitare la registrazione di debug

Per risolvere un errore di distribuzione, è possibile abilitare la registrazione di debug per ottenere altre informazioni. La registrazione del debug funziona per le distribuzioni con file Bicep o modelli di Azure Resource Manager (modelli ARM). È possibile ottenere dati sulla richiesta e sulla risposta di una distribuzione per apprendere la causa di un problema.

Avvertimento

La registrazione di debug può esporre informazioni riservate come le password o le operazioni listKeys. Abilitare la registrazione di debug solo quando è necessario risolvere un errore di distribuzione. Dopo aver completato il debug, è necessario rimuovere la cronologia di distribuzione di debug.

Configurare il log di debug

Usare Azure PowerShell per abilitare la registrazione di debug per popolare le proprietà request e response con informazioni sulla distribuzione per la risoluzione dei problemi. La registrazione di debug non può essere abilitata tramite l'interfaccia della riga di comando di Azure.

La registrazione di debug è abilitata solo per il modello arm principale o il file Bicep. Se si usano modelli arm annidati o moduli Bicep, vedere Eseguire il debug di modelli annidati.

Per una distribuzione di un gruppo di risorse, usare New-AzResourceGroupDeployment e impostare il DeploymentDebugLogLevel parametro su All, ResponseContento RequestContent.

Quando la registrazione di debug è abilitata, viene visualizzato un avviso che indica che è possibile registrare e visualizzare segreti come password o listKeys operazioni quando si usano comandi come Get-AzResourceGroupDeploymentOperation per ottenere informazioni sulle operazioni di distribuzione.

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

L'output della distribuzione mostra il livello di registrazione del debug.

DeploymentDebugLogLevel : RequestContent, ResponseContent

Il DeploymentDebugLogLevel parametro è disponibile per altri ambiti di distribuzione: sottoscrizione, gruppo di gestione e tenant.

Ottenere informazioni di debug

Dopo aver abilitato la registrazione di debug, è possibile ottenere altre informazioni sulle operazioni di distribuzione. I cmdlet di Azure PowerShell per le operazioni di distribuzione non generano output delle proprietà request e response. È necessario usare l'interfaccia della riga di comando di Azure per ottenere le informazioni da tali proprietà.

Se non si abilita la registrazione di debug dal comando di distribuzione, è comunque possibile ottenere informazioni sulle operazioni di distribuzione. Usare Azure PowerShell o l'interfaccia della riga di comando di Azure per ottenere il codice di stato, il messaggio di stato e lo stato di provisioning.

Per una distribuzione di un gruppo di risorse, usare Get-AzResourceGroupDeploymentOperation per ottenere le operazioni di distribuzione.

Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup

È possibile specificare una proprietà, ad esempio StatusCode, StatusMessageo ProvisioningState per filtrare l'output.

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

Per altre informazioni, vedere la documentazione relativa agli ambiti dell'operazione di distribuzione: sottoscrizione, gruppo di gestione e tenant.

Eseguire il debug di un modello annidato

Il modello ARM principale e i modelli annidati hanno ciascuno il proprio nome e la propria cronologia di implementazione. Il file e il modulo Bicep principali usano anche un nome di distribuzione e una cronologia di distribuzione separati.

Modello ARM

Per registrare le informazioni di debug per un modello ARM annidato, usare Microsoft.Resources/deployments con la proprietà debugSetting.

Il seguente esempio mostra un modello annidato con debugSetting per registrare la richiesta e la risposta della distribuzione.

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

Il modello ARM principale e i modelli annidati hanno ciascuno il proprio nome e la propria cronologia di implementazione. Se si desidera che le request proprietà e response contengano informazioni sulla risoluzione dei problemi, tenere presente gli scenari di distribuzione seguenti:

  • Le request proprietà e response contengono null valori per il modello principale e il modello annidato quando DeploymentDebugLogLevel non è abilitato con il comando di distribuzione.
  • Quando il comando di distribuzione abilita DeploymentDebugLogLevel le request proprietà e response contengono informazioni solo per il modello principale. Le proprietà del modello nidificato contengono null valori.
  • Quando un modello nidificato utilizza debugSetting e il comando di distribuzione non include DeploymentDebugLogLevel, soltanto la distribuzione del modello nidificato ha valori per le proprietà request e response. Le proprietà del modello principale contengono null valori.
  • Per ottenere il request e il response per il modello principale e il modello annidato, specificare DeploymentDebugLogLevel nel comando di distribuzione e usare debugSetting nel modello annidato.

File Bicep

La raccomandazione per i file Bicep consiste nell'usare moduli anziché modelli annidati con Microsoft.Resources/deployments. Il messaggio di stato, il codice di stato e lo stato di provisioning includeranno informazioni per il file e il modulo Bicep principali che è possibile usare per risolvere i problemi di distribuzione.

Se si abilita DeploymentDebugLogLevel dal comando di distribuzione, le request proprietà e response conterranno informazioni solo per la distribuzione del file Bicep principale.

Rimuovere la cronologia di distribuzione di debug

Al termine del debug, è necessario rimuovere la cronologia di distribuzione per impedire a chiunque abbia accesso di visualizzare informazioni riservate che potrebbero essere state registrate. Per ogni nome di distribuzione usato durante il debug, eseguire il comando per rimuovere la cronologia di distribuzione.

Per rimuovere la cronologia di distribuzione per una distribuzione di un gruppo di risorse, usare Remove-AzResourceGroupDeployment.

Remove-AzResourceGroupDeployment -ResourceGroupName examplegroup -Name exampledeployment

Il comando restituisce True quando ha esito positivo.

Per altre informazioni sulla cronologia di distribuzione, vedere la documentazione relativa agli ambiti di distribuzione: sottoscrizione, gruppo di gestione e tenant.

Passaggi successivi