Django contient une configuration de journalisation par défaut fonctionnelle qui peut facilement être étendue.
\nPour envoyer un message de journalisation à partir de votre code, écrivez un appel de journalisation.
\n\nTout d’abord, importez la bibliothèque Python logging et obtenez une instance de journalisation avec logging.getLogger(). Passez à la méthode getLogger() un nom pour l’identifier et pour les lignes qu’il produira. Une bonne option est d’utiliser __name__ (voir Utilisation de l’espace de noms des journaliseurs ci-dessous pour en savoir plus), ce qui donnera le nom du module Python actuel sous forme de chemin pointé
import logging\n\nlogger = logging.getLogger(__name__)\nPar convention, il est bon d’effectuer cette déclaration au niveau du module.
\nPuis dans une fonction, par exemple dans une vue, envoyez un enregistrement au journaliseur
\ndef some_view(request):\n ...\n if some_risky_state:\n logger.warning("Platform is running at risk")\nLorsque ce code est exécuté, un objet LogRecord contenant ce message sera envoyé au journaliseur. SI vous utilisez la configuration de journalisation de Django par défaut, le message apparaîtra dans la console.
Le niveau WARNING utilisé dans l’exemple ci-dessus est l’un des quelques niveaux de sévérité de journalisation: DEBUG`, INFO, WARNING, ERROR, CRITICAL. Un autre exemple pourrait être
logger.critical("Payment system is not responding")\nMême si la configuration de journalisation de Django fonctionne telle quelle, vous pouvez contrôler exactement la manière dont vos journaux sont envoyés à diverses destinations, vers des fichiers journaux, des services externes, par courriel, etc. en ajoutant un peu de configuration supplémentaire.
\nVous pouvez configurer :
\nles correspondances des journaliseurs (logger) pour déterminer quels enregistrements sont envoyés à quels gestionnaires
les gestionnaires (handler) pour déterminer ce qu’ils font des enregistrements qu’ils reçoivent
les filtres, pour ajouter du contrôle supplémentaire sur le transfert des enregistrements, et même les modifier sur place
les formateurs, pour convertir les objets LogRecord en une chaîne ou toute autre forme qui soit lisible par les humains ou un autre système
Il existe plusieurs manières de configurer la journalisation. Dans Django, le réglage LOGGING est le plus couramment utilisé. Ce réglage utilise le format dictConfig, et étend la configuration de journalisation par défaut.
Consultez Configuration de la journalisation pour une explication sur la manière dont vos réglages personnalisés sont fusionnés avec ceux de Django.
\nConsultez la documentation de journalisation de Python pour plus de détails sur les autres manières de configurer la journalisation. Par simplification, cette documentation ne va considérer que la configuration au travers du réglage LOGGING.
Lors de la configuration de la journalisation, il est raisonnable de
\nLOGGINGLien vers cette rubrique#Dans votre fichier settings.py:
LOGGING = {\n "version": 1, # the dictConfig format version\n "disable_existing_loggers": False, # retain the default loggers\n}\nIl est presque toujours recommandé de conserver et étendre la configuration de journalisation par défaut en définissant disable_existing_loggers à False.
Cet exemple configure un seul gestionnaire (handler) nommé file, qui utilise la classe FileHandler de Python pour enregistrer les journaux de niveau DEBUG et plus élevé dans le fichier general.log (à la racine du projet) :
LOGGING = {\n # ...\n "handlers": {\n "file": {\n "class": "logging.FileHandler",\n "filename": "general.log",\n },\n },\n}\nDifférentes classes de gestionnaire acceptent différentes options de configuration. Pour plus d’informations sur les classes de gestionnaire disponibles, consultez AdminEmailHandler fournie par Django et les diverses classes de gestionnaire fournies par Python.
Les niveaux de journalisation peuvent aussi être définis sur les gestionnaires (par défaut, elles acceptent des messages de tous les niveaux). En utilisant l’exemple ci-dessus, l’ajout de :
\n{\n "class": "logging.FileHandler",\n "filename": "general.log",\n "level": "DEBUG",\n}\ndéfinirait une configuration de gestionnaire n’acceptant que des enregistrements de niveau DEBUG ou supérieur.
Pour envoyer des enregistrements à ce gestionnaire, configurez une correspondance pour l’utiliser, par exemple :
\nLOGGING = {\n # ...\n "loggers": {\n "": {\n "level": "DEBUG",\n "handlers": ["file"],\n },\n },\n}\nLe nom de correspondance détermine quels sont les enregistrements de journaux qu’il va traiter. Cette configuration ('') is anonyme. Cela signifie qu’elle traitera les enregistrements de tous les journaliseurs (voir Utilisation de l’espace de noms des journaliseurs ci-dessous sur la manière d’utiliser les noms de correspondance pour déterminer les journaliseurs concernés par le traitement de ses enregistrements).
Ceci va transmettre les messages de niveau DEBUG et supérieur au gestionnaire nommé file.
Notez qu’un journaliseur peut transmettre des messages à plusieurs gestionnaires, il existe donc une relation de type plusieurs-à-plusieurs entre les journaliseurs et les gestionnaires.
\nSi vous exécutez
\nlogger.debug("Attempting to connect to API")\ndans vote code, vous trouverez ce message dans le fichier general.log` à la racine de votre projet.
\nPar défaut, le résultat final de journalisation contient la partie message de chaque enregistrement de journal. Utilisez un formateur si vous souhaitez inclure des données supplémentaires. Commencez par nommer et définir vos formateurs. Cet exemple définit des formateurs nommés verbose et simple:
LOGGING = {\n # ...\n "formatters": {\n "verbose": {\n "format": "{name} {levelname} {asctime} {module} {process:d} {thread:d} {message}",\n "style": "{",\n },\n "simple": {\n "format": "{levelname} {message}",\n "style": "{",\n },\n },\n}\nLe mot-clé style permet d’indiquer { pour la mise en forme str.format() ou $ pour string.Template; la valeur par défaut est $.
Voir LogRecord attributes au sujet des attributs de LogRecord qu’il est possible d’inclure.
Pour appliquer un formateur à un gestionnaire, ajoutez une entrée formatter au dictionnaire du gestionnaire en vous référant au formateur par son nom, par exemple :
"handlers": {\n "file": {\n "class": "logging.FileHandler",\n "filename": "general.log",\n "formatter": "verbose",\n },\n}\nLa configuration de journalisation anonyme '' capture les journaux de n’importe quelle application Python. Une configuration de journalisation nommée ne capturera que les journaux de journaliseurs dont le nom correspond.
L’espace de noms d’une instance de journaliseur est défini en utilisant getLogger(). Par exemple, dans views.py de my_app:
logger = logging.getLogger(__name__)\nva créer un journaliseur dans l’espace de noms my_app.views. __name__ permet d’organiser automatiquement les messages de journalisation en fonction de leur provenance dans les applications de votre projet. Cela garantit par la même occasion que les collisions de noms seront évitées.
Une correspondance de journaliseur nommée my_app.views va capturer les enregistrements de ce journaliseur :
LOGGING = {\n # ...\n "loggers": {\n "my_app.views": {...},\n },\n}\nUne correspondance de journaliseur nommée my_app sera plus permissive, capturant les enregistrements de journaliseurs partout dans l’espace de noms my_app (y compris my_app.views`, my_app.utils et ainsi de suite) :
LOGGING = {\n # ...\n "loggers": {\n "my_app": {...},\n },\n}\nIl est aussi possible de définir les espaces de noms des journaliseurs de manière explicite
\nlogger = logging.getLogger("project.payment")\net de définir ensuite en fonction les correspondances de journaliseurs.
\nLa nomenclature des journaliseurs est hiérarchique. my_app est le parent de my_app.views, qui est le parent de my_app.views.private. Sans autre indication, les correspondances de journaliseurs vont propager les enregistrements qu’elles traitent à leurs parents ; un enregistrement d’un journaliseur dans l’espace de noms my_app.views.private sera traité à la fois par les correspondances de my_app et de my_app.views.
Pour contrôler ce comportement, donnez une valeur à la clé de propagation sur les correspondances que vous définissez
\nLOGGING = {\n # ...\n "loggers": {\n "my_app": {\n # ...\n },\n "my_app.views": {\n # ...\n },\n "my_app.views.private": {\n # ...\n "propagate": False,\n },\n },\n}\npropagate vaut True par défaut. Dans cet exemple, les journaux de my_app.views.private ne seront pas traités par les parents, mais les journaux de my_app.views le seront.
La journalisation est d’autant plus utile qu’elle contient des informations riches, mais sans information inutile, et cette pesée d’intérêts dépend de ce que vous faites. Lorsque vous êtes en mode débogage, le niveau d’informations souhaité dépasse largement ce qui sera nécessaire lorsque vous passerez votre projet en production.
\nVous pouvez configurer la journalisation pour qu’elle vous offre le niveau de détail nécessaire au moment où vous en avez besoin. Au lieu de modifier manuellement la configuration pour cet objectif, une meilleure façon est d’appliquer une configuration automatiquement en fonction de l’environnement.
\nPar exemple, vous pouvez définir une variable d’environnement DJANGO_LOG_LEVEL appropriée dans vos environnements de développement et de pré-production, et en faire usage dans une configuration de journaliseur de cette façon
"level": os.getenv("DJANGO_LOG_LEVEL", "WARNING")\nde cette manière, tant que l’environnement n’indique par un niveau de journalisation plus bas, cette configuration ne propagera que les enregistrements de sévérité WARNING et supérieure à son gestionnaire.
D’autres options de la configuration (comme les options level ou formatter des gestionnaires) peuvent également être ajustées de cette façon.