Freigeben über

Konfigurieren von Protokollierung in den Azure-Bibliotheken für Python

  • Artikel

Azure-Bibliotheken für Python, die auf azure.core basieren, bieten Protokollierungsausgaben unter Verwendung der Python-Standardbibliothek logging.

Der allgemeine Prozess zum Arbeiten mit der Protokollierung ist wie folgt:

  1. Rufen Sie das Protokollierungsobjekt für die gewünschte Bibliothek ab, und legen Sie den Protokolliergrad fest.
  2. Registrieren Sie einen Handler für den Protokollierungsdatenstrom.
  3. Um HTTP-Informationen aufzunehmen, übergeben Sie einen logging_enable=True-Parameter an einen Clientobjektkonstruktor, einen Anmeldeinformations-Objektkonstruktor oder an eine bestimmte Methode übergeben.

Detaillierte Informationen finden Sie in den restlichen Abschnitten dieses Artikels.

Als allgemeine Regel gilt: Die beste Ressource zum Verständnis der Protokollierungsverwendung innerhalb der Bibliotheken ist das Durchsuchen des SDK-Quellcodes unter github.com/Azure/azure-sdk-for-python. Es wird empfohlen, dieses Repository lokal zu klonen, damit Sie bei Bedarf problemlos nach Details suchen können, wie in den folgenden Abschnitten vorgeschlagen.

Festlegen der Protokolliergrade

import logging

# ...

# Acquire the logger for a library (azure.mgmt.resource in this example)
logger = logging.getLogger('azure.mgmt.resource')

# Set the desired logging level
logger.setLevel(logging.DEBUG)
  • In diesem Beispiel wird die Protokollierung für die azure.mgmt.resource-Bibliothek abgerufen und dann der Protokolliergrad auf logging.DEBUGfestgelegt.
  • Sie können logger.setLevel jederzeit aufrufen, um den Protokolliergrad für verschiedene Codesegmente zu ändern.

Um einen Protokolliergrad für eine andere Bibliothek festzulegen, verwenden Sie den Namen der betreffenden Bibliothek im logging.getLogger-Aufruf. Die azure-eventhubs-Bibliothek stellt z. B. eine Protokollierung namens azure.eventhubs bereit, die azure-storage-queue-Bibliothek eine Protokollierung mit dem Namen azure.storage.queue usw. (Der SDK-Quellcode verwendet häufig die Anweisung logging.getLogger(__name__), die eine Protokollierung mit dem Namen des enthaltenden Moduls abruft.)

Sie können auch allgemeinere Namespaces verwenden. Beispiel: 

import logging

# Set the logging level for all azure-storage-* libraries
logger = logging.getLogger('azure.storage')
logger.setLevel(logging.INFO)

# Set the logging level for all azure-* libraries
logger = logging.getLogger('azure')
logger.setLevel(logging.ERROR)

Der Logger „azure“ wird von einigen Bibliotheken anstelle eines spezifischen Loggers verwendet. Für die Bibliothek „azure-storage-blob“ wird beispielsweise die Protokollierung azure verwendet.

Sie können die logger.isEnabledFor-Methode verwenden, um zu überprüfen, ob ein bestimmter Protokolliergrad aktiviert ist:

print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

Protokolliergrade sind identisch mit den Standardprotokolliergraden der Bibliothek. In der folgenden Tabelle wird die allgemeine Verwendung dieser Protokolliergrade in den Azure-Bibliotheken für Python beschrieben:

Protokolliergrad Typische Nutzung
logging.ERROR Fehler, bei denen die Anwendung wahrscheinlich nicht wiederhergestellt werden kann (z. B. nicht genügend Arbeitsspeicher).
logging.WARNING (Standard) Eine Funktion kann die beabsichtigte Aufgabe nicht ausführen (wird jedoch nicht protokolliert, wenn die Funktion wiederhergestellt werden kann, z. B. durch Wiederholen eines REST-API-Aufrufs). Funktionen protokollieren in der Regel eine Warnung, wenn Ausnahmen ausgelöst werden. Die Warnstufe aktiviert automatisch die Fehlerstufe.
logging.INFO Die Funktion funktioniert ordnungsgemäß, oder ein Dienstaufruf wird abgebrochen. Informationsereignisse enthalten in der Regel Anforderungen, Antworten und Header. Die Informationsstufe aktiviert automatisch die Fehler- und Warnstufen.
logging.DEBUG Ausführliche Informationen, die häufig für die Problembehandlung verwendet werden und eine Stapelüberwachung für Ausnahmen enthalten. Die Debugstufe aktiviert automatisch die Informations-, Warnungs- und Fehlerstufen. ACHTUNG: Wenn Sie außerdem „logging_enable=True“ festlegen, umfasst die Debug-Ebene sensible Informationen wie Kontoschlüssel in Headern und andere Anmeldeinformationen. Stellen Sie sicher, dass diese Protokolle geschützt sind, um eine Beeinträchtigung der Sicherheit zu vermeiden.
logging.NOTSET Deaktiviert die gesamte Protokollierung.

Bibliotheksspezifisches Verhalten des Protokolliergrads

Das genaue Protokollierungsverhalten auf jeder Stufe hängt von der betreffenden Bibliothek ab. Einige Bibliotheken, wie z. B. „azure.eventhub“, führen umfangreiche Protokollierungen durch, während andere Bibliotheken nur wenig tun.

Der beste Weg, die genaue Protokollierung für eine Bibliothek zu untersuchen, ist die Suche nach den Protokollierungsstufen im Azure SDK für Python Quellcode:

  1. Navigieren Sie im Repositoryordner zum Ordner sdk, und navigieren Sie dann zu dem Ordner für den betreffenden Dienst.

  2. Suchen Sie in diesem Ordner nach einer der folgenden Zeichenfolgen:

    • _LOGGER.error
    • _LOGGER.warning
    • _LOGGER.info
    • _LOGGER.debug

Registrieren eines Protokolldatenstrom-Handlers

Um die Protokollierungsausgabe zu erfassen, müssen Sie mindestens einen Protokolldatenstrom-Handler in Ihrem Code registrieren:

import logging
# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

In diesem Beispiel wird ein Handler registriert, der die Protokollausgabe an stdout weiterleitet. Sie können andere Arten von Handlern verwenden, wie unter logging.handlers in der Python-Dokumentation beschrieben, oder Sie verwenden die Standardmethode logging.basicConfig.

Aktivieren der HTTP-Protokollierung für ein Clientobjekt oder einen Vorgang

Standardmäßig enthält die Protokollierung innerhalb der Azure-Bibliotheken keine HTTP-Informationen. Um HTTP-Informationen in die Protokollausgabe aufzunehmen (als DEBUG-Level), müssen Sie logging_enable=True explizit an einen Client- oder Anmeldeinformations-Objektkonstruktor oder an eine bestimmte Methode übergeben.

Achtung

Die HTTP-Protokollierung kann sensible Informationen wie Kontoschlüssel in Headern und andere Anmeldeinformationen enthalten. Stellen Sie sicher, dass diese Protokolle geschützt sind, um eine Beeinträchtigung der Sicherheit zu vermeiden.

Aktivieren der HTTP-Protokollierung für ein Clientobjekt (DEBUG-Ebene)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# Enable HTTP logging on the client object when using DEBUG level
# endpoint is the Blob storage URL.
client = BlobClient(endpoint, DefaultAzureCredential(), logging_enable=True)

Durch die Aktivierung der HTTP-Protokollierung für ein Clientobjekt wird die Protokollierung aller Vorgänge, die über dieses Objekt aufgerufen werden, ermöglicht.

Aktivieren der HTTP-Protokollierung für ein Anmeldeinformationsobjekt (DEBUG-Ebene)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# Enable HTTP logging on the credential object when using DEBUG level
credential = DefaultAzureCredential(logging_enable=True)

# endpoint is the Blob storage URL.
client = BlobClient(endpoint, credential)

Wenn Sie die HTTP-Protokollierung für ein Anmeldeinformations-Objekt aktivieren, wird die Protokollierung für alle Operationen aktiviert, die über dieses Objekt aufgerufen werden, jedoch nicht für Operationen in einem Client-Objekt, die keine Authentifizierung beinhalten.

Aktivieren der Protokollierung für eine einzelne Methode (DEBUG-Ebene)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# endpoint is the Blob storage URL.
client = BlobClient(endpoint, DefaultAzureCredential())

# Enable HTTP logging for only this operation when using DEBUG level
client.create_container("container01", logging_enable=True)

Beispiel für eine Protokollierungsausgabe

Der folgende Code stammt aus Beispiel: Verwenden eines Speicherkontos. Zusätzlich wurde DEBUG- und HTTP-Protokollierung aktiviert:

import logging
import os
import sys
import uuid

from azure.core import exceptions
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobClient

logger = logging.getLogger("azure")
logger.setLevel(logging.DEBUG)

# Set the logging level for the azure.storage.blob library
logger = logging.getLogger("azure.storage.blob")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

try:
    credential = DefaultAzureCredential()
    storage_url = os.environ["AZURE_STORAGE_BLOB_URL"]
    unique_str = str(uuid.uuid4())[0:5]

    # Enable logging on the client object
    blob_client = BlobClient(
        storage_url,
        container_name="blob-container-01",
        blob_name=f"sample-blob-{unique_str}.txt",
        credential=credential,
    )

    with open("./sample-source.txt", "rb") as data:
        blob_client.upload_blob(data, logging_body=True, logging_enable=True)

except (
    exceptions.ClientAuthenticationError,
    exceptions.HttpResponseError
) as e:
    print(e.message)

Die Ausgabe lautet wie folgt:

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
Request URL: 'https://pythonazurestorage12345.blob.core.windows.net/blob-container-01/sample-blob-5588e.txt'
Request method: 'PUT'
Request headers:
    'Content-Length': '77'
    'x-ms-blob-type': 'BlockBlob'
    'If-None-Match': '*'
    'x-ms-version': '2023-11-03'
    'Content-Type': 'application/octet-stream'
    'Accept': 'application/xml'
    'User-Agent': 'azsdk-python-storage-blob/12.19.0 Python/3.10.11 (Windows-10-10.0.22631-SP0)'
    'x-ms-date': 'Fri, 19 Jan 2024 19:25:53 GMT'
    'x-ms-client-request-id': '8f7b1b0b-b700-11ee-b391-782b46f5c56b'
    'Authorization': '*****'
Request body:
b"Hello there, Azure Storage. I'm a friendly file ready to be stored in a blob."
Response status: 201
Response headers:
    'Content-Length': '0'
    'Content-MD5': 'SUytm0872jZh+KYqtgjbTA=='
    'Last-Modified': 'Fri, 19 Jan 2024 19:25:54 GMT'
    'ETag': '"0x8DC1924749AE3C3"'
    'Server': 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0'
    'x-ms-request-id': '7ac499fa-601e-006d-3f0d-4bdf28000000'
    'x-ms-client-request-id': '8f7b1b0b-b700-11ee-b391-782b46f5c56b'
    'x-ms-version': '2023-11-03'
    'x-ms-content-crc64': 'rtHLUlztgxc='
    'x-ms-request-server-encrypted': 'true'
    'Date': 'Fri, 19 Jan 2024 19:25:53 GMT'
Response content:
b''

Hinweis

Wenn Sie einen Autorisierungsfehler erhalten, vergewissern Sie sich, dass der Identität, unter der Sie arbeiten, die Rolle „Storage Blob Data Contributor“ auf Ihrem Blob-Container zugewiesen ist. Weitere Informationen finden Sie unter Blob-Speicher vom App-Code aus verwenden (Registerkarte „Kennwortlos“).