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:

1. Acquisire l'oggetto di registrazione per la libreria desiderata e impostare il livello di registrazione.
2. Registrare un gestore per il flusso di registrazione.
3. Per includere informazioni HTTP, passare un logging_enable=True parametro 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 su logging.DEBUG.
• È possibile chiamare logger.setLevel in 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:

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:

1. Nella cartella repository passare alla cartella sdk, quindi passare alla cartella del servizio specifico di interesse.

2. 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, è necessario passare logging_enable=True in modo esplicito a un costruttore di oggetti client o credenziali o a un metodo specifico.

Abilitare la registrazione HTTP per un oggetto client

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

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

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''