Configurer la journalisation dans les bibliothèques Azure pour Python
Les bibliothèques Azure pour Python 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 affectelogging.DEBUGcomme 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)
L’enregistreur azure d’événements est utilisé par certaines bibliothèques au lieu d’un enregistreur d’événements 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 logging_enable=Trueégalement, le niveau de débogage inclut des informations sensibles telles que des 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 étendue, tandis que d’autres bibliothèques ne font que peu.
La meilleure façon d’examiner la journalisation exacte d’une bibliothèque consiste à rechercher les niveaux de journalisation dans le code source du Kit de développement logiciel (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 aucune information HTTP. Pour inclure des informations HTTP dans la sortie du journal (en tant que niveau DEBUG), vous devez transmettre logging_enable=True explicitement à un constructeur d’objet client ou d’informations d’identification ou à une méthode spécifique.
Attention
La journalisation HTTP peut inclure des informations sensibles telles que des 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’impliquent 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, vérifiez que l’identité sous laquelle vous vous exécutez est affectée au rôle « contributeur de données blob Stockage » sur votre conteneur d’objets blob. Pour plus d’informations, consultez Utiliser le stockage d’objets blob avec l’authentification.
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour