Share via

Konfigurace protokolování v knihovnách Azure pro Python

  • Článek

Knihovny Azure pro Python založené na azure.core poskytují výstup protokolování pomocí standardní knihovny protokolování Pythonu.

Obecný postup pro práci s protokolováním je následující:

  1. Získejte objekt protokolování pro požadovanou knihovnu a nastavte úroveň protokolování.
  2. Zaregistrujte obslužnou rutinu pro stream protokolování.
  3. Pokud chcete zahrnout informace HTTP, předejte logging_enable=True parametr konstruktoru objektu klienta, konstruktoru objektu pověření nebo konkrétní metodě.

Podrobnosti najdete ve zbývajících částech tohoto článku.

Obecně platí, že nejlepším prostředkem pro pochopení využití protokolování v knihovnách je procházení zdrojového kódu sady SDK v github.com/Azure/azure-sdk-for-python. Doporučujeme, abyste toto úložiště naklonovali místně, abyste v případě potřeby mohli snadno vyhledat podrobnosti podle následujících pokynů.

Nastavení úrovní protokolování

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)
  • Tento příklad získá protokolovací nástroj pro knihovnu azure.mgmt.resource a pak nastaví úroveň protokolování na logging.DEBUG.
  • Kdykoli můžete volat logger.setLevel a změnit úroveň protokolování pro různé segmenty kódu.

Pokud chcete nastavit úroveň pro jinou knihovnu, použijte název této knihovny ve logging.getLogger volání. Například knihovna azure-eventhubs poskytuje protokolovací nástroj s názvem azure.eventhubs, knihovna azure-storage-queue poskytuje protokolovací nástroj s názvem azure.storage.queueatd. (Zdrojový kód sady SDK často používá příkaz logging.getLogger(__name__), který získává protokolovací nástroj pomocí názvu obsahujícího modulu.)

Můžete také použít obecnější obory názvů. Příklad:

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)

Protokolovací azure nástroj používá některé knihovny místo konkrétního protokolovacího nástroje. Například knihovna azure-storage-blob používá azure protokolovací nástroj.

Pomocí této metody můžete logger.isEnabledFor zkontrolovat, jestli je povolená nějaká úroveň protokolování:

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

Úrovně protokolování jsou stejné jako standardní úrovně knihovny protokolování. Následující tabulka popisuje obecné použití těchto úrovní protokolování v knihovnách Azure pro Python:

Úroveň protokolování Typické použití
Protokolování. CHYBA Selhání, kdy se aplikace pravděpodobně neobnoví (například nedostatek paměti).
Protokolování. UPOZORNĚNÍ (výchozí) Funkci se nepodaří provést zamýšlenou úlohu (ale ne v případě, že se funkce může obnovit, například opakování volání rozhraní REST API). Funkce obvykle protokolují upozornění při vyvolání výjimek. Úroveň upozornění automaticky povolí úroveň chyby.
logging.INFO Funkce funguje normálně nebo se zruší volání služby. Mezi informační události obvykle patří požadavky, odpovědi a hlavičky. Úroveň informací automaticky povolí úrovně chyb a upozornění.
Protokolování. LADĚNÍ Podrobné informace, které se běžně používají k řešení potíží a obsahují trasování zásobníku pro výjimky. Úroveň ladění automaticky povolí informace, upozornění a úrovně chyb. UPOZORNĚNÍ: Pokud jste také nastavili logging_enable=True, úroveň ladění obsahuje citlivé informace, jako jsou klíče účtu v hlavicích a dalších přihlašovacích údajích. Nezapomeňte tyto protokoly chránit, abyste se vyhnuli ohrožení zabezpečení.
Protokolování. NOTSET Zakažte veškeré protokolování.

Chování na úrovni protokolování specifické pro knihovnu

Přesné chování protokolování na jednotlivých úrovních závisí na příslušné knihovně. Některé knihovny, jako je azure.eventhub, provádějí rozsáhlé protokolování, zatímco jiné knihovny dělají málo.

Nejlepší způsob, jak prozkoumat přesné protokolování pro knihovnu, je vyhledat úrovně protokolování ve zdrojovém kódu sady Azure SDK pro Python:

  1. Ve složce úložiště přejděte do složky sdk a pak přejděte do složky pro konkrétní službu, která je zajímají.

  2. V této složce vyhledejte některý z následujících řetězců:

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

Registrace obslužné rutiny streamu protokolu

Pokud chcete zaznamenat výstup protokolování, musíte v kódu zaregistrovat aspoň jednu obslužnou rutinu streamu protokolu:

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)

Tento příklad zaregistruje obslužnou rutinu, která směruje výstup protokolu na stdout. V dokumentaci k Pythonu můžete použít jiné typy obslužných rutin, jak je popsáno v dokumentaci k log.handlers , nebo použít standardní metodu logging.basicConfig .

Povolení protokolování HTTP pro objekt nebo operaci klienta

Protokolování v knihovnách Azure ve výchozím nastavení neobsahuje žádné informace HTTP. Pokud chcete zahrnout informace HTTP do výstupu protokolu (jako úroveň LADĚNÍ), musíte explicitně předat logging_enable=True klientovi nebo konstruktoru objektu přihlašovacích údajů nebo konkrétní metodě.

Upozornění

Protokolování HTTP může obsahovat citlivé informace, jako jsou klíče účtu, do hlaviček a dalších přihlašovacích údajů. Nezapomeňte tyto protokoly chránit, abyste se vyhnuli ohrožení zabezpečení.

Povolení protokolování HTTP pro objekt klienta (úroveň LADĚNÍ)

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)

Povolení protokolování PROTOKOLU HTTP pro objekt klienta umožňuje protokolování pro všechny operace vyvolané prostřednictvím daného objektu.

Povolení protokolování HTTP pro objekt přihlašovacích údajů (úroveň LADĚNÍ)

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)

Povolení protokolování PROTOKOLU HTTP pro objekt přihlašovacích údajů umožňuje protokolování pro všechny operace vyvolané tímto objektem, ale ne pro operace v objektu klienta, které nezahrnují ověřování.

Povolení protokolování pro jednotlivé metody (úroveň LADĚNÍ)

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)

Příklad výstupu protokolování

Následující kód je uvedený v příkladu: Použijte účet úložiště s přidáním povolení protokolování DEBUG a 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)

Výstup je následující:

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

Poznámka:

Pokud se zobrazí chyba autorizace, ujistěte se, že je ve vašem kontejneru objektů blob v kontejneru objektů blob přiřazená role Přispěvatel dat objektů blob úložiště. Další informace najdete v tématu Použití úložiště objektů blob s ověřováním.