Configurer la journalisation dans les bibliothèques Azure pour Python

Article
10/14/2024

Les bibliothèques Azure pour Python qui sont basées sur azure.core fournissent une sortie de journalisation à l’aide de la bibliothèque de journalisation Python standard.

Le processus général d’utilisation de la journalisation est le suivant :

Obtenez l’objet de journalisation pour la bibliothèque souhaitée et définissez le niveau de journalisation.
Inscrivez un gestionnaire pour le flux de journalisation.
Pour inclure des informations HTTP, transmettez un paramètre logging_enable=True à un constructeur d’objet client, un constructeur d’objet d’informations d’identification ou à une méthode en particulier.

Les détails sont fournis dans les autres sections de cet article.

En règle générale, la meilleure ressource pour comprendre l’utilisation de la journalisation dans les bibliothèques consiste à parcourir le code source du SDK sur github.com/Azure/azure-sdk-for-python. Nous vous encourageons à cloner ce dépôt localement afin de pouvoir facilement rechercher des détails si nécessaire, comme le suggèrent les sections suivantes.

Définir les niveaux de journalisation

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)

Cet exemple acquiert le journaliseur pour la bibliothèque azure.mgmt.resource, puis affecte logging.DEBUG comme niveau de journalisation.
Vous pouvez appeler logger.setLevel à tout moment afin de changer le niveau de journalisation pour différents segments de code.

Pour définir un niveau pour une autre bibliothèque, utilisez le nom de cette bibliothèque dans l’appel logging.getLogger. Par exemple, la bibliothèque azure-eventhubs fournit un journaliseur nommé azure.eventhubs, la bibliothèque azure-storage-queue fournit un journaliseur nommé azure.storage.queue, et ainsi de suite. (Le code source du SDK utilise fréquemment l’instruction logging.getLogger(__name__), qui acquiert un journaliseur à l’aide du nom du module conteneur.)

Vous pouvez également utiliser des espaces de noms plus généraux. Par exemple,

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)

Le journaliseur azure est utilisé par certaines bibliothèques à la place d’un journaliseur spécifique. Par exemple, la bibliothèque azure-storage-blob utilise l’enregistreur d’événements azure.

Vous pouvez utiliser la méthode logger.isEnabledFor pour vérifier si un niveau de journalisation donné est activé :

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

Les niveaux de journalisation sont identiques à ceux de la bibliothèque de journalisation standard. Le tableau suivant décrit l’utilisation générale de ces niveaux de journalisation dans les bibliothèques Azure pour Python :

Niveau de journalisation	Utilisation courante
logging.ERROR	Échecs suite auxquels la récupération de l’application est peu probable (par exemple mémoire insuffisante).
logging.WARNING (par défaut)	Une fonction ne parvient pas à exécuter sa tâche prévue (mais pas quand la fonction peut récupérer, par exemple en effectuant une nouvelle tentative d’appel d’API REST). Les fonctions enregistrent généralement un avertissement quand elles lèvent des exceptions. Le niveau warning active automatiquement le niveau error.
logging.INFO	La fonction fonctionne normalement ou un appel de service est annulé. Les événements info incluent généralement les requêtes, les réponses et les en-têtes. Le niveau info active automatiquement le niveaux error et warning.
logging.DEBUG	Informations détaillées couramment utilisées pour la résolution des problèmes avec une trace de pile pour les exceptions. Le niveau debug active automatiquement les niveaux info, warning et error. ATTENTION : si vous définissez également `logging_enable=True`, le niveau de débogage comprend des informations sensibles telles que les clés de compte dans les en-têtes et d’autres informations d’identification. Veillez à protéger ces journaux afin d’éviter de mettre la sécurité en danger.
logging.NOTSET	Désactive la journalisation.

Comportement de niveau de journalisation propre à la bibliothèque

Le comportement de journalisation exact à chaque niveau dépend de la bibliothèque en question. Certaines bibliothèques, telles qu’azure.eventhub, effectuent une journalisation complète, tandis que d’autres bibliothèques n’en effectuent que peu.

La meilleure façon d’examiner la journalisation exacte pour une bibliothèque consiste à rechercher les niveaux de journalisation dans le code source du SDK Azure pour Python :

Dans le dossier du dépôt, accédez au dossier sdk, puis accédez au dossier du service qui vous intéresse.
Dans ce dossier, recherchez l’une des chaînes suivantes :
- _LOGGER.error
- _LOGGER.warning
- _LOGGER.info
- _LOGGER.debug

Inscrire un gestionnaire de flux de journal

Pour capturer la sortie de journalisation, vous devez inscrire au moins un gestionnaire de flux de journal dans votre code :

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)

Cet exemple inscrit un gestionnaire qui dirige la sortie de journal vers stdout. Vous pouvez utiliser d’autres types de gestionnaires comme décrit dans logging.handlers dans la documentation Python ou utiliser la méthode standard logging.basicConfig.

Activer la journalisation HTTP pour une opération ou un objet client

Par défaut, la journalisation dans les bibliothèques Azure n’inclut pas d’informations HTTP. Pour inclure des informations HTTP dans la sortie du journal (au niveau débogage), vous devez explicitement transmettre logging_enable=True à un constructeur d’objet client ou d’informations d’identification ou à une méthode donnée.

Attention

La journalisation HTTP comprend des informations sensibles telles que les clés de compte dans les en-têtes et d’autres informations d’identification. Veillez à protéger ces journaux afin d’éviter de mettre la sécurité en danger.

Activer la journalisation HTTP pour un objet client (niveau débogage)

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)

L’activation de la journalisation HTTP pour un objet client active la journalisation pour toutes les opérations appelées par le biais de cet objet.

Activer la journalisation l’enregistrement HTTP pour un objet d’informations d’identification (niveau débogage)

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)

L’activation de la journalisation HTTP pour un objet d’informations d’identification active la journalisation pour toutes les opérations appelées via cet objet, mais pas pour les opérations dans un objet client qui n’implique pas l’authentification.

Activer la journalisation pour une méthode individuelle (niveau débogage)

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)

Exemple de sortie de journalisation

Le code suivant est celui présenté dans Exemple : Utiliser un compte de stockage avec l’ajout de l’activation de la journalisation DEBUG et 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)

La sortie se présente comme suit :

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

Remarque

Si vous recevez une erreur d’autorisation, assurez-vous que l’identité sous laquelle vous travaillez est affectée au rôle « Contributeur aux données Blob de stockage » sur votre conteneur d’objets blob. Pour en savoir plus, consultez Utiliser le stockage d’objets Blob à partir du code d’application (onglet « Sans mot de passe »).

Partager via