Configurare la registrazione nelle librerie di Azure per Python
Le librerie di Azure per Python basate su azure.core forniscono l'output di registrazione usando la libreria di registrazione Python standard.
Il processo generale per lavorare con la registrazione è il seguente:
- Acquisire l'oggetto di registrazione per la libreria desiderata e impostare il livello di registrazione.
- Registrare un gestore per il flusso di registrazione.
- Per includere informazioni HTTP, passare un
logging_enable=Trueparametro a un costruttore di oggetti client, a un costruttore di oggetti credenziali o a un metodo specifico.
I dettagli sono disponibili nelle sezioni rimanenti di questo articolo.
Come regola generale, la risorsa migliore per comprendere l'utilizzo della registrazione all'interno delle librerie è il codice sorgente dell'SDK disponibile all'indirizzo github.com/Azure/azure-sdk-for-python. È consigliabile clonare il repository in locale, in modo da poter cercare facilmente i dettagli quando necessario, come suggerito nelle sezioni seguenti.
Impostare i livelli di registrazione
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)
- Questo esempio acquisisce il logger per la libreria
azure.mgmt.resource, quindi imposta il livello di registrazione sulogging.DEBUG. - È possibile chiamare
logger.setLevelin qualsiasi momento per cambiare il livello di registrazione per i diversi segmenti di codice.
Per impostare un livello per una libreria diversa, usare il nome della libreria nella chiamata a logging.getLogger. Ad esempio, la libreria azure-eventhubs fornisce un logger denominato azure.eventhubs, la libreria azure-storage-queue fornisce un logger denominato azure.storage.queue e così via. Il codice sorgente dell'SDK usa spesso l'istruzione logging.getLogger(__name__), che acquisisce un logger usando il nome del modulo che lo contiene.
Si possono anche usare spazi dei nomi più generali. ad esempio:
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)
Il azure logger viene usato da alcune librerie anziché da un logger specifico. Ad esempio, la libreria azure-storage-blob usa il azure logger.
È possibile usare il metodo logger.isEnabledFor per verificare se è abilitato un determinato livello di registrazione:
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)}"
)
I livelli di registrazione corrispondono ai livelli della libreria logging standard. La tabella seguente descrive l'uso generale di questi livelli di registrazione nelle librerie di Azure per Python:
| Livello di registrazione | Uso tipico |
|---|---|
| logging.ERROR | Errori da cui è improbabile che venga ripristinato lo stato normale dell'applicazione (ad esempio memoria insufficiente). |
| logging.WARNING (predefinito) | Una funzione non riesce a eseguire l'attività prevista (ma non quando la funzione può essere ripristinata, come nel caso di un nuovo tentativo di chiamata all'API REST). In genere le funzioni registrano un avviso in caso di generazione di eccezioni. Il livello di avviso abilita automaticamente il livello di errore. |
| logging.INFO | La funzione funziona normalmente o una chiamata al servizio viene annullata. Gli eventi informativi includono in genere richieste, risposte e intestazioni. Il livello di informazioni abilita automaticamente i livelli di errore e avviso. |
| logging.DEBUG | Informazioni dettagliate comunemente usate per la risoluzione dei problemi e includono un'analisi dello stack per le eccezioni. Il livello di debug abilita automaticamente i livelli di informazioni, avviso ed errore. ATTENZIONE: se si imposta logging_enable=Trueanche , il livello di debug include informazioni riservate, ad esempio le chiavi dell'account nelle intestazioni e altre credenziali. Assicurarsi di proteggere questi log per evitare di compromettere la sicurezza. |
| logging.NOTSET | Disabilita tutte le registrazioni. |
Comportamento del livello di registrazione specifico della libreria
L'esatto comportamento di registrazione per ogni livello dipende dalla libreria in questione. Alcune librerie, ad esempio azure.eventhub, eseguono una registrazione estesa, mentre altre non fanno altro.
Il modo migliore per esaminare la registrazione esatta per una libreria consiste nel cercare i livelli di registrazione nel codice sorgente di Azure SDK per Python:
Nella cartella repository passare alla cartella sdk, quindi passare alla cartella del servizio specifico di interesse.
In questa cartella cercare una delle stringhe seguenti:
_LOGGER.error_LOGGER.warning_LOGGER.info_LOGGER.debug
Registrare un gestore del flusso di registrazione
Per acquisire l'output di registrazione, è necessario registrare almeno un gestore del flusso di registrazione nel codice:
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)
Questo esempio registra un gestore che indirizza l'output di registrazione a stdout. È possibile usare altri tipi di gestori come descritto in logging.handlers nella documentazione di Python o usare il metodo logging.basicConfig standard.
Abilitare la registrazione HTTP per un oggetto client o un'operazione
Per impostazione predefinita, la registrazione all'interno delle librerie di Azure non include informazioni HTTP. Per includere informazioni HTTP nell'output del log (come livello DEBUG), è necessario passare logging_enable=True in modo esplicito a un costruttore di oggetti client o credenziali o a un metodo specifico.
Attenzione
La registrazione HTTP può includere informazioni riservate, ad esempio le chiavi dell'account nelle intestazioni e altre credenziali. Assicurarsi di proteggere questi log per evitare di compromettere la sicurezza.
Abilitare la registrazione HTTP per un oggetto client (livello DEBUG)
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)
L'abilitazione della registrazione HTTP per un oggetto client consente la registrazione per tutte le operazioni richiamate tramite tale oggetto.
Abilitare la registrazione HTTP per un oggetto credenziale (livello DEBUG)
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)
L'abilitazione della registrazione HTTP per un oggetto credenziale consente la registrazione per tutte le operazioni richiamate tramite tale oggetto, ma non per le operazioni in un oggetto client che non comportano l'autenticazione.
Abilitare la registrazione per un singolo metodo (livello DEBUG)
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)
Esempio di output di registrazione
Il codice seguente è illustrato in Esempio: Usare un account di archiviazione con l'aggiunta dell'abilitazione della registrazione DEBUG e HTTP:
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)
L'output è il seguente:
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''
Nota
Se viene visualizzato un errore di autorizzazione, assicurarsi che all'identità in esecuzione sia assegnato il ruolo "Collaboratore dati BLOB Archiviazione" nel contenitore BLOB. Per altre informazioni, vedere Usare l'archiviazione BLOB con l'autenticazione.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per