Condividi tramite

Abilitazione della registrazione di debug

  • Articolo

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

Avviso

La registrazione di debug potrebbe esporre segreti quali password od operazionilistKeys. Abilitare la registrazione di debug soltanto quando si deve risolvere un errore di distribuzione. Al termine del debug, è necessario rimuovere la cronologia di distribuzione di debug.

Configurare la registrazione di debug

Usare Azure PowerShell per abilitare la registrazione di debug che popola 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 di ARM o il file Bicep principale. Se si usano modelli di ARM o moduli Bicep annidati, vedere Eseguire il debug di un modello annidato.

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

Se la registrazione di debug è abilitata, viene visualizzato un avviso che indica che segreti come password od operazioni listKeys possono essere registrati o visualizzati 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 di debug.

DeploymentDebugLogLevel : RequestContent, ResponseContent

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

Ottenere le 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 l’output delle proprietà request e response. Per ottenere le informazioni da tali proprietà, è necessario usare l'interfaccia della riga di comando di Azure.

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 provisioning.

Per la 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, StatusMessage o 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 di ARM principale e i modelli annidati hanno un proprio nome di distribuzione e una propria cronologia di distribuzione. Il file e il modulo Bicep principali usano anche un nome distribuzione e una cronologia di distribuzione separati.

Modello ARM

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

L'esempio seguente illustra un modello annidato con debugSetting per registrare la richiesta e la risposta di 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 di ARM principale e i modelli annidati hanno un proprio nome di distribuzione e una propria cronologia di distribuzione. Se si desidera che le proprietà request e response contengano informazioni sulla risoluzione dei problemi, tenere presenti gli scenari di distribuzione riportati di seguito:

  • Le proprietà request e response contengono valori null per il modello principale e il modello annidato se DeploymentDebugLogLevel non viene abilitato con il comando di distribuzione.
  • Quando il comando di distribuzione abilita le proprietà DeploymentDebugLogLevel, le proprietà request e response contengono informazioni solo per il modello principale. Le proprietà del modello annidato contengono valori null.
  • Quando un modello annidato usa debugSetting e il comando di distribuzione non include DeploymentDebugLogLevel, solo la distribuzione del modello annidato possiede valori per le proprietà request e response. Le proprietà del modello principale contengono valori null.
  • Per ottenere request e response per il modello principale e il modello annidato, specificare DeploymentDebugLogLevel nel comando di distribuzione e usare debugSetting nel modello annidato.

distribuibile

Per i file Bicep si è consigliabile usare i moduli anziché modelli annidati con Microsoft.Resources/deployments. Il messaggio di stato, il codice di stato e lo stato provisioning includeranno informazioni per il file e il modulo Bicep principali che si possono utilizzare per risolvere i problemi di distribuzione.

Se si abilita DeploymentDebugLogLevel dal comando di distribuzione, le proprietà request e response contengono 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 chi accede di visualizzare informazioni riservate che potrebbero essere state registrate. Per ogni nome di distribuzione usato durante il debug, eseguire il comando per eliminare la cronologia di distribuzione.

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

Remove-AzResourceGroupDeployment -ResourceGroupName examplegroup -Name exampledeployment

Il comando restituisce True se l'operazione è stata completata.

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

Passaggi successivi