Konfigurera loggning i Azure-biblioteken för Python

Azure-bibliotek för Python som baseras på azure.core ger loggningsutdata med hjälp av standardbiblioteket för Python-loggning.

Den allmänna processen för att arbeta med loggning är följande:

1. Hämta loggningsobjektet för önskat bibliotek och ange loggningsnivån.
2. Registrera en hanterare för loggningsströmmen.
3. Om du vill inkludera HTTP-information skickar du en logging_enable=True parameter till en klientobjektkonstruktor, en konstruktor för autentiseringsuppgifter eller till en specifik metod.

Information finns i de återstående avsnitten i den här artikeln.

Som en allmän regel är den bästa resursen för att förstå loggningsanvändningen i biblioteken att bläddra i SDK-källkoden på github.com/Azure/azure-sdk-for-python. Vi rekommenderar att du klonar den här lagringsplatsen lokalt så att du enkelt kan söka efter information när det behövs, enligt följande avsnitt.

Ange loggningsnivåer

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)

• Det här exemplet hämtar loggaren azure.mgmt.resource för biblioteket och anger sedan loggningsnivån till logging.DEBUG.
• Du kan när som helst anropa logger.setLevel för att ändra loggningsnivån för olika kodsegment.

Om du vill ange en nivå för ett annat bibliotek använder du bibliotekets namn i anropet logging.getLogger . Biblioteket azure-eventhubs innehåller till exempel en logger med namnet azure.eventhubs, azure-storage-queue-biblioteket innehåller en logger med namnet azure.storage.queueoch så vidare. (SDK-källkoden använder ofta -instruktionen logging.getLogger(__name__), som hämtar en loggare med namnet på den innehållande modulen.)

Du kan också använda mer allmänna namnområden. Ett exempel:

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)

Loggern azure används av vissa bibliotek i stället för en specifik loggning. Till exempel använder azure azure-storage-blob-biblioteket loggern.

Du kan använda logger.isEnabledFor metoden för att kontrollera om en viss loggningsnivå är aktiverad:

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)}"
)

Loggningsnivåerna är desamma som standardnivån för loggningsbiblioteket. I följande tabell beskrivs den allmänna användningen av dessa loggningsnivåer i Azure-biblioteken för Python:

Beteende på biblioteksspecifik loggningsnivå

Det exakta loggningsbeteendet på varje nivå beror på biblioteket i fråga. Vissa bibliotek, till exempel azure.eventhub, utför omfattande loggning medan andra bibliotek inte gör mycket.

Det bästa sättet att undersöka den exakta loggningen för ett bibliotek är att söka efter loggningsnivåerna i Azure SDK för Python-källkod:

1. I mappen lagringsplats navigerar du till mappen sdk och navigerar sedan till mappen för den specifika tjänsten av intresse.

2. Sök efter någon av följande strängar i mappen:

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

Registrera en loggströmshanterare

Om du vill samla in loggningsutdata måste du registrera minst en loggströmshanterare i koden:

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)

I det här exemplet registreras en hanterare som dirigerar loggutdata till stdout. Du kan använda andra typer av hanterare enligt beskrivningen på logging.handlers i Python-dokumentationen eller använda standardmetoden logging.basicConfig .

Aktivera HTTP-loggning för ett klientobjekt eller en åtgärd

Som standard innehåller loggning i Azure-biblioteken ingen HTTP-information. Om du vill inkludera HTTP-information i loggutdata måste du uttryckligen skicka logging_enable=True till en klient- eller autentiseringsobjektkonstruktor eller till en specifik metod.

Aktivera HTTP-loggning för ett klientobjekt

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)

Genom att aktivera HTTP-loggning för ett klientobjekt kan du logga alla åtgärder som anropas via objektet.

Aktivera HTTP-loggning för ett autentiseringsobjekt

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)

Genom att aktivera HTTP-loggning för ett autentiseringsobjekt kan du logga alla åtgärder som anropas via objektet, men inte för åtgärder i ett klientobjekt som inte omfattar autentisering.

Aktivera loggning för en enskild metod

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)

Exempel på loggningsutdata

Följande kod visas i Exempel: Använd ett lagringskonto med tillägg av aktivering av FELSÖKNING och HTTP-loggning:

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)

Utdata är följande:

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