Konfigurowanie rejestrowania w bibliotekach platformy Azure dla języka Python

Artykuł
11/14/2024

Biblioteki platformy Azure dla języka Python oparte na pliku azure.core udostępniają dane wyjściowe rejestrowania przy użyciu standardowej biblioteki rejestrowania języka Python.

Ogólny proces pracy z rejestrowaniem jest następujący:

Uzyskaj obiekt rejestrowania dla żądanej biblioteki i ustaw poziom rejestrowania.
Zarejestruj procedurę obsługi strumienia rejestrowania.
Aby dołączyć informacje HTTP, przekaż logging_enable=True parametr do konstruktora obiektu klienta, konstruktora obiektu poświadczeń lub określonej metody.

Szczegółowe informacje znajdują się w pozostałych sekcjach tego artykułu.

Ogólnie rzecz biorąc, najlepszym zasobem do zrozumienia użycia rejestrowania w bibliotekach jest przeglądanie kodu źródłowego zestawu SDK w github.com/Azure/azure-sdk-for-python. Zachęcamy do sklonowania tego repozytorium lokalnie, aby w razie potrzeby można było łatwo wyszukać szczegóły, jak sugerują poniższe sekcje.

Ustawianie poziomów rejestrowania

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)

Ten przykład uzyskuje rejestrator dla azure.mgmt.resource biblioteki, a następnie ustawia poziom rejestrowania na logging.DEBUG.
W dowolnym momencie można wywołać logger.setLevel metodę , aby zmienić poziom rejestrowania dla różnych segmentów kodu.

Aby ustawić poziom dla innej biblioteki, użyj nazwy tej biblioteki w wywołaniu logging.getLogger . Na przykład biblioteka azure-eventhubs udostępnia rejestrator o nazwie , biblioteka azure-storage-queue udostępnia rejestrator o nazwie azure.eventhubsazure.storage.queuei tak dalej. (Kod źródłowy zestawu SDK często używa instrukcji logging.getLogger(__name__), która uzyskuje rejestrator przy użyciu nazwy modułu zawierającego).

Możesz również użyć bardziej ogólnych przestrzeni nazw. Na przykład:

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)

Rejestrator azure jest używany przez niektóre biblioteki zamiast określonego rejestratora. Na przykład biblioteka azure-storage-blob używa rejestratora azure .

Możesz użyć logger.isEnabledFor metody , aby sprawdzić, czy dany poziom rejestrowania jest włączony:

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

Poziomy rejestrowania są takie same jak standardowe poziomy bibliotek rejestrowania. W poniższej tabeli opisano ogólne użycie tych poziomów rejestrowania w bibliotekach platformy Azure dla języka Python:

Poziom rejestrowania	Typowe użycie
wyrąb. BŁĄD	Błędy, w których aplikacja jest mało prawdopodobne, aby odzyskać (np. brak pamięci).
wyrąb. OSTRZEŻENIE (ustawienie domyślne)	Funkcja nie może wykonać zamierzonego zadania (ale nie wtedy, gdy funkcja może odzyskać, na przykład ponowić próbę wywołania interfejsu API REST). Funkcje zwykle rejestrują ostrzeżenie podczas zgłaszania wyjątków. Poziom ostrzeżenia automatycznie włącza poziom błędu.
logging.INFO	Funkcja działa normalnie lub jest anulowane wywołanie usługi. Zdarzenia informacji zwykle obejmują żądania, odpowiedzi i nagłówki. Poziom informacji automatycznie włącza poziomy błędów i ostrzeżeń.
wyrąb. DEBUGOWAĆ	Szczegółowe informacje, które są często używane do rozwiązywania problemów i zawierają ślad stosu dla wyjątków. Poziom debugowania automatycznie włącza poziomy informacji, ostrzeżeń i błędów. UWAGA: Jeśli ustawisz `logging_enable=True`również poziom debugowania, zawiera informacje poufne, takie jak klucze konta w nagłówkach i inne poświadczenia. Pamiętaj, aby chronić te dzienniki, aby uniknąć naruszenia zabezpieczeń.
wyrąb. NOTSET	Wyłącz wszystkie rejestrowanie.

Zachowanie na poziomie rejestrowania specyficzne dla biblioteki

Dokładne zachowanie rejestrowania na każdym poziomie zależy od danej biblioteki. Niektóre biblioteki, takie jak azure.eventhub, wykonują obszerne rejestrowanie, podczas gdy inne biblioteki niewiele robią.

Najlepszym sposobem zbadania dokładnego rejestrowania biblioteki jest wyszukanie poziomów rejestrowania w zestawie Azure SDK dla kodu źródłowego języka Python:

W folderze repozytorium przejdź do folderu zestawu SDK , a następnie przejdź do folderu, aby uzyskać dostęp do określonej usługi.
W tym folderze wyszukaj dowolny z następujących ciągów:
- _LOGGER.error
- _LOGGER.warning
- _LOGGER.info
- _LOGGER.debug

Rejestrowanie procedury obsługi strumienia dziennika

Aby przechwycić dane wyjściowe rejestrowania, należy zarejestrować co najmniej jedną procedurę obsługi strumienia dziennika w kodzie:

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)

W tym przykładzie zarejestrowano procedurę obsługi, która kieruje dane wyjściowe dziennika do elementu stdout. W dokumentacji języka Python można używać innych typów procedur obsługi zgodnie z opisem w temacie logging.handlers lub użyć standardowej metody logging.basicConfig .

Włączanie rejestrowania HTTP dla obiektu lub operacji klienta

Domyślnie rejestrowanie w bibliotekach platformy Azure nie zawiera żadnych informacji HTTP. Aby uwzględnić informacje HTTP w danych wyjściowych dziennika, należy jawnie przekazać logging_enable=True do konstruktora obiektu klienta lub poświadczeń lub do określonej metody.

Uwaga

Rejestrowanie HTTP może zawierać poufne informacje, takie jak klucze konta w nagłówkach i inne poświadczenia. Pamiętaj, aby chronić te dzienniki, aby uniknąć naruszenia zabezpieczeń.

Włączanie rejestrowania HTTP dla obiektu klienta

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)

Włączenie rejestrowania HTTP dla obiektu klienta umożliwia rejestrowanie wszystkich operacji wywoływanych za pośrednictwem tego obiektu.

Włączanie rejestrowania HTTP dla obiektu poświadczeń

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)

Włączenie rejestrowania HTTP dla obiektu poświadczeń umożliwia rejestrowanie wszystkich operacji wywoływanych za pośrednictwem tego obiektu, ale nie dla operacji w obiekcie klienta, które nie obejmują uwierzytelniania.

Włączanie rejestrowania dla pojedynczej metody

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)

Przykładowe dane wyjściowe rejestrowania

Poniższy kod pokazany w przykładzie: Użyj konta magazynu z dodatkiem włączania rejestrowania debugowania i protokołu 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)

Wynik jest następujący:

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