Naplózás konfigurálása a PythonHoz készült Azure-kódtárakban

Az Azure.core-on alapuló Python-kódtárak a standard Python-naplózási kódtár használatával biztosítják a naplózási kimenetet.

A naplózással kapcsolatos általános folyamat a következő:

1. Szerezze be a kívánt tár naplózási objektumát, és állítsa be a naplózási szintet.
2. Regisztráljon egy kezelőt a naplózási adatfolyamhoz.
3. HTTP-információk megadásához adjon meg egy paramétert logging_enable=True egy ügyfélobjektum-konstruktornak, egy hitelesítőadat-objektum konstruktorának vagy egy adott metódusnak.

A részleteket a cikk további szakaszaiban találja.

Általános szabály, hogy a kódtárak naplózási használatának megértéséhez a legjobb erőforrás az SDK forráskódjának tallózása github.com/Azure/azure-sdk-for-python. Javasoljuk, hogy helyileg klónozza ezt az adattárat, hogy szükség esetén könnyen rákereshesse a részletekre, ahogy az alábbi szakaszok is sugallják.

Naplózási szintek beállítása

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)

• Ez a példa beolvasja a kódtár naplózóit azure.mgmt.resource , majd beállítja a naplózási szintet logging.DEBUG.
• Bármikor felhívhatja logger.setLevel a különböző kódszegmensek naplózási szintjét.

Ha egy másik kódtár szintjét szeretné beállítani, használja a kódtár nevét a logging.getLogger hívásban. Az azure-eventhubs kódtár például egy logger nevű azure.eventhubs, az azure-storage-queue kódtár pedig egy névvel ellátott azure.storage.queuenaplózót biztosít, és így tovább. (Az SDK-forráskód gyakran használja az utasítást logging.getLogger(__name__), amely egy naplózót szerez be az azt tartalmazó modul nevével.)

Általánosabb névtereket is használhat. Például:

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)

A azure naplózót egyes kódtárak használják egy adott naplózó helyett. Az azure-storage-blob kódtár például a naplózót azure használja.

Ezzel a logger.isEnabledFor módszerrel ellenőrizheti, hogy engedélyezve van-e egy adott naplózási szint:

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

A naplózási szintek megegyeznek a normál naplózási kódtárszintekkel. Az alábbi táblázat az alábbi naplózási szintek általános használatát ismerteti a Pythonhoz készült Azure-kódtárakban:

Naplózási szint	Tipikus használat
Naplózási. HIBA	Olyan hibák, amikor az alkalmazás nem valószínű, hogy helyreáll (például nincs memória).
Naplózási. FIGYELMEZTETÉS (alapértelmezett)	A függvények nem hajtják végre a kívánt feladatot (de nem akkor, amikor a függvény helyreállhat, például rest API-hívás újrapróbálkozása). A függvények általában figyelmeztetést naplóznak a kivételek emelésekor. A figyelmeztetési szint automatikusan engedélyezi a hibaszintet.
logging.INFO	A függvény normálisan működik, vagy egy szolgáltatáshívás megszakad. Az információs események általában kéréseket, válaszokat és fejléceket tartalmaznak. Az információs szint automatikusan engedélyezi a hiba- és figyelmeztetési szinteket.
Naplózási. DEBUG	A hibaelhárításhoz gyakran használt részletes információk, valamint a kivételek veremkövetését is tartalmazzák. A hibakeresési szint automatikusan engedélyezi az információs, figyelmeztetési és hibaszinteket. FIGYELEM: Ha azt is beállítja logging_enable=True, a hibakeresési szint bizalmas információkat tartalmaz, például a fejlécekben lévő fiókkulcsokat és más hitelesítő adatokat. A biztonság veszélyeztetésének elkerülése érdekében mindenképpen védje ezeket a naplókat.
Naplózási. NEM Standard kiadás T	Tiltsa le az összes naplózást.

Társpecifikus naplózási szint viselkedése

Az egyes szintek pontos naplózási viselkedése a szóban forgó kódtártól függ. Egyes kódtárak, például az azure.eventhub, széles körű naplózást végeznek, míg más kódtárak nem sokat tesznek.

A kódtárak pontos naplózásának vizsgálatához a legjobb módszer a naplózási szintek keresése a Pythonhoz készült Azure SDK forráskódjában:

1. Az adattár mappájában lépjen az sdk mappába, majd lépjen az adott szolgáltatáshoz tartozó mappába.

2. Ebben a mappában keresse meg a következő sztringek bármelyikét:

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

Naplóstream-kezelő regisztrálása

A naplózási kimenet rögzítéséhez regisztrálnia kell legalább egy naplóstream-kezelőt a kódban:

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)

Ez a példa regisztrál egy kezelőt, amely a naplókimenetet stdoutra irányítja. Használhat más típusú kezelőket is a Logging.handlersben leírtak szerint a Python dokumentációjában, vagy használhatja a standard logging.basicConfig metódust.

HTTP-naplózás engedélyezése ügyfélobjektumhoz vagy művelethez

Alapértelmezés szerint az Azure-kódtárakon belüli naplózás nem tartalmaz HTTP-információkat. Ha HTTP-adatokat szeretne felvenni a naplókimenetbe (DEBUG-szintként), explicit módon át kell adnia logging_enable=True egy ügyfél- vagy hitelesítőadat-objektumkonstruktornak vagy egy adott metódusnak.

Figyelemfelhívás

A HTTP-naplózás tartalmazhat bizalmas információkat, például a fejlécekben lévő fiókkulcsokat és más hitelesítő adatokat. A biztonság veszélyeztetésének elkerülése érdekében mindenképpen védje ezeket a naplókat.

HTTP-naplózás engedélyezése ügyfélobjektumhoz (HIBAKERESÉSi szint)

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)

Az ügyfélobjektum HTTP-naplózásának engedélyezése lehetővé teszi az adott objektumon keresztül meghívott összes művelet naplózását.

HTTP-naplózás engedélyezése hitelesítő objektumhoz (HIBAKERESÉSi szint)

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)

A hitelesítő objektum HTTP-naplózásának engedélyezése lehetővé teszi az adott objektumon keresztül meghívott összes művelet naplózását, de nem olyan ügyfélobjektumokban végzett műveletek esetében, amelyek nem igényelnek hitelesítést.

Naplózás engedélyezése egyéni metódushoz (DEBUG szint)

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élda naplózási kimenetre

A következő kód jelenik meg a példában : Tárfiók használata a DEBUG és a HTTP naplózás engedélyezésével:

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)

A kimenet a következő:

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

Feljegyzés

Ha hitelesítési hibát kap, győződjön meg arról, hogy a futtatott identitás a "Storage Blob Data Contributor" szerepkörhöz van rendelve a blobtárolón. További információ: Blob Storage használata hitelesítéssel.