Konfigurieren von Protokollierung in den Azure-Bibliotheken für Python
Azure Libraries for Python that are based on azure.core provide logging output using the standard Python logging library.
Der allgemeine Prozess zum Arbeiten mit der Protokollierung ist wie folgt:
- Rufen Sie das Protokollierungsobjekt für die gewünschte Bibliothek ab, und legen Sie den Protokolliergrad fest.
- Registrieren Sie einen Handler für den Protokollierungsdatenstrom.
- 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 auflogging.DEBUGfestgelegt. - Sie können
logger.setLeveljederzeit 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 azure Logger wird von einigen Bibliotheken anstelle eines bestimmten 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 auch festlegen logging_enable=True, enthält die Debugebene vertrauliche Informationen wie Kontoschlüssel in Kopfzeilen und anderen 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, z. B. azure.eventhub, führen umfangreiche Protokollierungen aus, während andere Bibliotheken wenig tun.
Die beste Möglichkeit, die genaue Protokollierung für eine Bibliothek zu untersuchen, besteht darin, nach den Protokollierungsebenen im Azure SDK für Python-Quellcode zu suchen:
Navigieren Sie im Repositoryordner zum Ordner sdk, und navigieren Sie dann zu dem Ordner für den betreffenden Dienst.
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 in den Azure-Bibliotheken keine HTTP-Informationen. Um HTTP-Informationen in die Protokollausgabe (als DEBUG-Ebene) einzuschließen, müssen Sie explizit an einen Client- oder Anmeldeinformationsobjektkonstruktor oder an eine bestimmte Methode übergeben logging_enable=True .
Achtung
Die HTTP-Protokollierung kann vertrauliche Informationen wie Kontoschlüssel in Headern und anderen 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)
Das Aktivieren der HTTP-Protokollierung für ein Anmeldeinformationsobjekt ermöglicht die Protokollierung für alle Vorgänge, die über dieses Objekt aufgerufen werden, jedoch nicht für Vorgänge in einem Clientobjekt, das keine Authentifizierung umfasst.
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, stellen Sie sicher, dass die Identität, unter der Sie ausgeführt werden, der Rolle "Mitwirkender von Speicher-BLOB-Daten" im BLOB-Container zugewiesen ist. Weitere Informationen finden Sie unter Verwenden von BLOB-Speicher mit Authentifizierung.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für