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. 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:

Loggningsnivå	Normal användning
Loggning. FEL	Fel där programmet sannolikt inte kommer att återställas (till exempel slut på minne).
Loggning. VARNING (standard)	En funktion kan inte utföra sin avsedda uppgift (men inte när funktionen kan återställas, till exempel om ett REST API-anrop). Funktioner loggar vanligtvis en varning när undantag uppstår. Varningsnivån aktiverar automatiskt felnivån.
logging.INFO	Funktionen fungerar normalt eller så avbryts ett tjänstanrop. Informationshändelser omfattar vanligtvis begäranden, svar och rubriker. Informationsnivån aktiverar automatiskt fel- och varningsnivåer.
Loggning. DEBUG	Detaljerad information som ofta används för felsökning och innehåller en stackspårning för undantag. Felsökningsnivån aktiverar automatiskt informations-, varnings- och felnivåerna. VARNING! Om du också anger logging_enable=Trueinnehåller felsökningsnivån känslig information, till exempel kontonycklar i rubriker och andra autentiseringsuppgifter. Se till att skydda loggarna för att undvika att äventyra säkerheten.
Loggning. NOTSET	Inaktivera all loggning.

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 (som FELSÖKNINGsnivå) måste du uttryckligen skicka logging_enable=True till en klient- eller autentiseringsobjektkonstruktor eller till en specifik metod.

Varning

HTTP-loggning kan innehålla känslig information, till exempel kontonycklar i rubriker och andra autentiseringsuppgifter. Se till att skydda loggarna för att undvika att äventyra säkerheten.

Aktivera HTTP-loggning för ett klientobjekt (FELSÖKNINGsnivå)

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 (FELSÖKNINGsnivå)

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 (FELSÖKNINGsnivå)

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

Kommentar

Om du får ett auktoriseringsfel kontrollerar du att den identitet som du kör under har tilldelats rollen "Storage Blob Data Contributor" i blobcontainern. Mer information finns i Använda bloblagring med autentisering.