Teilen über

Debugprotokollierung aktivieren

  • Artikel

Sie können die Debugprotokollierung aktivieren, um weitere Informationen für die Behandlung von Bereitstellungsfehlern zu erhalten. Die Debugprotokollierung kann für Bereitstellungen mit Bicep-Dateien oder Azure Resource Manager-Vorlagen (ARM-Vorlagen) verwendet werden. Sie können Daten zur Anforderung und Antwort einer Bereitstellung abrufen, um die Problemursache zu ermitteln.

Warnung

Die Debugprotokollierung kann Geheimnisse wie Kennwörter oder listKeys-Vorgänge offenlegen. Aktivieren Sie die Debugprotokollierung nur, wenn Sie einen Bereitstellungsfehler behandeln müssen. Wenn Sie das Debuggen abgeschlossen haben, sollten Sie den Bereitstellungsverlauf für das Debuggen entfernen.

Einrichten der Debugprotokollierung

Verwenden Sie Azure PowerShell, um die Debugprotokollierung zu aktivieren, die die Eigenschaften request und response mit Bereitstellungsinformationen für die Problembehandlung auffüllt. Die Debugprotokollierung kann nicht mithilfe der Azure CLI aktiviert werden.

Die Debugprotokollierung ist nur für die ARM-Hauptvorlage bzw. die Bicep-Hauptdatei aktiviert. Wenn Sie geschachtelte ARM-Vorlagen oder Bicep-Module verwenden, lesen Sie die Informationen unter Debuggen geschachtelter Vorlagen.

Verwenden Sie für eine Ressourcengruppenbereitstellung New-AzResourceGroupDeployment, und legen Sie den Parameter DeploymentDebugLogLevel auf All, ResponseContent oder RequestContent fest.

Wenn die Debugprotokollierung aktiviert wird, wird eine Warnung mit dem Hinweis angezeigt, dass möglicherweise Geheimnisse wie Kennwörter oder listKeys-Vorgänge protokolliert und angezeigt werden, wenn Sie Informationen zu Bereitstellungsvorgängen mit Befehlen wie Get-AzResourceGroupDeploymentOperation abrufen.

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

Die Ausgabe der Bereitstellung zeigt den Protokolliergrad der Debugprotokollierung.

DeploymentDebugLogLevel : RequestContent, ResponseContent

Der Parameter DeploymentDebugLogLevel steht für andere Bereitstellungsbereiche zur Verfügung: Abonnement, Verwaltungsgruppe und Mandant.

Abrufen von Debuginformationen

Nach Aktivierung der Debugprotokollierung können Sie weitere Informationen zu den Bereitstellungsvorgängen abrufen. Die Azure PowerShell-Cmdlets für Bereitstellungsvorgänge geben nicht die Eigenschaften request und response aus. Sie müssen die Azure CLI verwenden, um die Informationen aus diesen Eigenschaften abzurufen.

Wenn Sie die Debugprotokollierung nicht über den Bereitstellungsbefehl aktivieren, können Sie dennoch Informationen zu Bereitstellungsvorgängen abrufen. Verwenden Sie Azure PowerShell oder die Azure CLI, um den Statuscode, die Statusmeldung und den Bereitstellungsstatus abzurufen.

Verwenden Sie für eine Ressourcengruppenbereitstellung Get-AzResourceGroupDeploymentOperation, um Bereitstellungsvorgänge abzurufen.

Get-AzResourceGroupDeploymentOperation `
  -DeploymentName exampledeployment `
  -ResourceGroupName examplegroup

Sie können eine Eigenschaft wie StatusCode, StatusMessage oder ProvisioningState angeben, um die Ausgabe zu filtern.

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

Weitere Informationen finden Sie in der Dokumentation zu Bereitstellungsvorgangsbereichen: Abonnement, Verwaltungsgruppe und Mandant.

Debuggen geschachtelter Vorlagen

Die ARM-Hauptvorlage und die geschachtelten Vorlagen verfügen über einen eigenen Bereitstellungsnamen und einen eigenen Bereitstellungsverlauf. Die Bicep-Hauptdatei und das Modul verwenden ebenfalls einen separaten Bereitstellungsnamen und einen separaten Bereitstellungsverlauf.

ARM-Vorlage

Verwenden Sie zum Protokollieren von Debuginformationen für eine geschachtelte ARM-Vorlage Microsoft.Resources/deployments mit der Eigenschaft debugSetting.

Das folgende Beispiel zeigt eine geschachtelte Vorlage mit debugSetting, um die Anforderung und Antwort der Bereitstellung zu protokollieren:

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

Die ARM-Hauptvorlage und die geschachtelten Vorlagen verfügen über einen eigenen Bereitstellungsnamen und einen eigenen Bereitstellungsverlauf. Wenn die Eigenschaften request und response Informationen zur Problembehandlung enthalten sollen, beachten Sie die folgenden Bereitstellungsszenarien:

  • Die Eigenschaften request und response enthalten null-Werte für die Hauptvorlage und die geschachtelte Vorlage, wenn DeploymentDebugLogLevel nicht mit dem Bereitstellungsbefehl aktiviert wird.
  • Wenn der Bereitstellungsbefehl DeploymentDebugLogLevel aktiviert, enthalten die Eigenschaften request und response nur Informationen für die Hauptvorlage. Die Eigenschaften der geschachtelten Vorlage enthalten null-Werte.
  • Wenn eine geschachtelte Vorlage debugSetting verwendet und der Bereitstellungsbefehl nicht DeploymentDebugLogLevel enthält, enthält nur die Bereitstellung geschachtelter Vorlagen Werte für die Eigenschaften request und response. Die Eigenschaften der Hauptvorlage enthalten null-Werte.
  • Um request und response für die Hauptvorlage und die geschachtelte Vorlage abzurufen, geben Sie im Bereitstellungsbefehl DeploymentDebugLogLevel an, und verwenden Sie debugSetting in der geschachtelten Vorlage.

Bicep-Datei

Bei Bicep-Dateien empfiehlt es sich, Module anstelle geschachtelter Vorlagen mit Microsoft.Resources/deployments zu verwenden. Die Statusmeldung, der Statuscode und der Bereitstellungsstatus enthalten Informationen für die Bicep-Hauptdatei und das Modul, die Sie für die Problembehandlung bei der Bereitstellung verwenden können.

Wenn Sie DeploymentDebugLogLevel über den Bereitstellungsbefehl aktivieren, enthalten die Eigenschaften request und response nur Informationen für die Bereitstellung der Bicep-Hauptdatei.

Entfernen des Bereitstellungsverlaufs für das Debuggen

Nach Abschluss des Debuggens sollten Sie den Bereitstellungsverlauf entfernen, um dafür zu sorgen, dass andere zugriffsberechtigte Benutzer keine vertraulichen Informationen anzeigen können, die möglicherweise protokolliert wurden. Führen Sie für jeden Bereitstellungsnamen, den Sie beim Debuggen verwendet haben, den Befehl aus, um den Bereitstellungsverlauf zu entfernen.

Der Bereitstellungsverlauf für eine Ressourcengruppenbereitstellung kann mithilfe des Befehls Remove-AzResourceGroupDeployment entfernt werden.

Remove-AzResourceGroupDeployment -ResourceGroupName examplegroup -Name exampledeployment

Der Befehl gibt True zurück, wenn der Vorgang erfolgreich war.

Weitere Informationen zum Bereitstellungsverlauf finden Sie in der Dokumentation für die Bereitstellungsbereiche: Abonnement, Verwaltungsgruppe und Mandant.

Nächste Schritte