Django utilise le module logging intégré de Python pour effectuer la journalisation système. L’utilisation de ce module est abordé en détails dans la propre documentation de Python. Cependant, si vous n’avez jamais utilisé le système de journalisation de Python (ou même si c’est le cas), voici un aperçu rapide.
Une configuration de journalisation Python consiste en quatre parties :
\n\nUn journaliseur (« logger ») est le point d’entrée dans le système de journalisation. Chaque journaliseur est un réceptacle nommé dans lequel les messages sont écrits en vue de leur traitement.
\nUn journaliseur est configuré avec un niveau de journalisation (« log level »). Ce niveau définit la sévérité des messages que le journaliseur va traiter. Python définit les niveaux de journalisation suivants :
\nDEBUG: information système de bas niveau à des fins de débogage
INFO: information système générale
WARNING: information décrivant la présence d’un problème mineur.
ERROR: information décrivant la présence d’un problème majeur.
CRITICAL: information décrivant la présence d’un problème critique.
Chaque message écrit dans le journaliseur est un enregistrement de journal (« log record »). Chacun de ces enregistrements possède également un niveau de journalisation indiquant la sévérité de ce message spécifique. Un enregistrement de journal peut aussi contenir des métadonnées utiles décrivant l’événement à journaliser. Cela peut inclure des détails tels qu’une trace de débogage ou un code d’erreur.
\nLorsqu’un message est transmis au journaliseur, le niveau de journalisation du message est comparé à celui du journaliseur. Si le niveau de journalisation du message correspond ou dépasse celui du journaliseur, le message continue d’être traité. Dans le cas contraire, le message est ignoré.
\nDès qu’un journaliseur a déterminé qu’un message doit être traité, il est transmis à un gestionnaire (« handler »).
\nLe gestionnaire est le moteur déterminant ce qui doit arriver à chaque message d’un journaliseur. Il décrit un comportement particulier de journalisation, tel que l’écriture d’un message à l’écran, dans un fichier ou dans un connecteur réseau.
\nComme les journaliseurs, les gestionnaires possèdent aussi un niveau de journalisation. Si le niveau de journalisation d’un enregistrement de journal n’est pas au moins équivalent à celui du gestionnaire, ce dernier ignore le message.
\nUn journaliseur peut avoir plusieurs gestionnaires et le niveau de journalisation de chaque gestionnaire peut être différent. De cette façon, il est possible de fournir différentes formes de notifications selon l’importance d’un message. Par exemple, vous pouvez installer un gestionnaire qui redirige les messages de niveau ERROR et CRITICAL vers un service de radiomessagerie, alors qu’un autre gestionnaire enverra tous les messages (y compris ceux de niveau ERROR et CRITICAL) dans un fichier pour analyse ultérieure.
Un filtre permet d’ajouter un contrôle supplémentaire sur la sélection des enregistrements de journal lorsqu’ils sont transmis du journaliseur au gestionnaire.
\nPar défaut, tout message de journal dont le niveau de journalisation est suffisant sera traité. Cependant, en installant un filtre, vous pouvez définir des critères supplémentaires dans le processus de journalisation. Par exemple, vous pourriez installer un filtre limitant l’émission de messages de niveau ERROR à une source particulière.
Les filtres peuvent ont aussi la possibilité de modifier l’enregistrement de journal avant son émission. Par exemple, vous pourriez écrire un filtre qui abaisse le niveau de journalisation du message de ERROR à WARNING si certains critères sont respectés.
Les filtres peuvent être installés pour les journaliseurs ou pour les gestionnaires ; il est aussi possible d’enchaîner plusieurs filtres pour effectuer différentes actions de filtrage.
\nPour terminer, un enregistrement de journal doit être produit sous forme de texte. Les formateurs spécifient le format exact de ce texte. En général, un formateur correspond à une chaîne de format Python contenant des attributs LogRecord ; cependant, vous pouvez très bien écrire vos propres formateurs afin d’implémenter un comportement de format spécifique.
\nAprès avoir configuré les journaliseurs, les gestionnaires, les filtres et les formateurs, il reste à placer les appels de journalisation dans votre code. L’utilisation du système de journalisation est très simple. Voici un exemple :
\n# import the logging library\nimport logging\n\n# Get an instance of a logger\nlogger = logging.getLogger(__name__)\n\ndef my_view(request, arg1, arg):\n ...\n if bad_mojo:\n # Log an error message\n logger.error('Something went wrong!')\nÇa y est ! Lors de chaque entrée dans la condition bad_mojo, une ligne d’erreur sera insérée dans le journal.
L’appel à logging.getLogger() obtient (et crée si nécessaire) une instance de journaliseur. Cette instance est identifiée par un nom. Ce nom sert à identifier le journaliseur pour la configuration.
Par convention, le nom du journaliseur est habituellement __name__, le nom du module Python contenant le journaliseur. Cela permet de filtrer et de traiter les appels de journalisation selon les modules. Cependant, si vous organisez vos messages de journalisation d’une autre manière, vous pouvez indiquer n’importe quel nom sous forme de notation pointée pour identifier un journaliseur :
# Get an instance of a specific named logger\nlogger = logging.getLogger('project.interesting.stuff')\nLa notation pointée des noms de journaliseurs définit une hiérarchie. Le journaliseur project.interesting est considéré comme le parent du journaliseur project.interesting.stuff. Le journaliseur project est le parent du journaliseur project.interesting.
Pourquoi cette hiérarchie est-elle importante ? Et bien, parce que les journaliseurs peuvent être configurés pour propager les appels de journalisation qu’ils reçoivent vers leurs parents. De cette manière, vous pouvez définir un seul ensemble de gestionnaires à la racine de l’arborescence d’un journaliseur et capturer tous les appels de journalisation dans la sous-arborescence des journaliseurs. Un gestionnaire de journalisation défini dans l’espace de noms project intercepte tous les messages de journalisation émis au niveau des journaliseurs project.interesting et project.interesting.stuff.
Cette propagation peut être contrôlée pour chaque journaliseur individuellement. Si vous souhaitez qu’un journaliseur particulier ne propage pas les messages à ses parents, vous pouvez désactiver ce comportement.
\nToute instance de journaliseur contient une méthode d’appel correspondant à chaque niveau de journalisation par défaut :
\nlogger.debug()
logger.info()
logger.warning()
logger.error()
logger.critical()
Deux autres appels de journalisation sont disponibles :
\nlogger.log(): émet manuellement un message de journalisation au niveau indiqué.
logger.exception(): crée un message de journalisation de niveau ERROR enveloppant la pile d’exception actuelle.
Le placement d’appels de journalisation dans le code n’est naturellement pas suffisant. Il faut aussi configurer les journaliseurs, les gestionnaires, les filtres et les formateurs pour s’assurer que le résultat de la journalisation s’affiche de manière exploitable.
\nPython’s logging library provides several techniques to configure\nlogging, ranging from a programmatic interface to configuration files.\nBy default, Django uses the dictConfig format.
\nPour configurer la journalisation, il s’agit de définir un dictionnaire de réglages de journalisation dans LOGGING. Ces réglages décrivent les journaliseurs, les gestionnaires, les filtres et les formateurs que vous souhaitez mettre en place, ainsi que les niveaux de journalisation et d’autres propriétés que vous voulez attribuer à ces composants.
Par défaut, le réglage LOGGING est fusionné avec la configuration de journalisation par défaut de Django en se basant sur les principes suivants.
Si la clé disable_existing_loggers du dictionnaire LOGGING contient True (valeur par défaut), tous les journaliseurs de la configuration par défaut seront désactivés. Désactiver un journaliseur n’est pas équivalent à sa suppression ; le journaliseur existe toujours, mais il élimine silencieusement les messages qu’il reçoit, sans même les propager au journaliseur parent. Vous devez donc vous méfier du réglage 'disable_existing_loggers': True; cela ne fait souvent pas ce qu’on aimerait. Par contre, vous pouvez définir disable_existing_loggers à False et redéfinir certains ou tous les journaliseurs par défaut. Une autre stratégie est de définir LOGGING_CONFIG à None et vous charger vous-même de la configuration de la journalisation.
La journalisation est configurée dans le cadre de la fonction setup() générale de Django. Ainsi, vous pouvez être certain que les journaliseurs sont toujours prêts à être utilisés par le code de votre projet.
The full documentation for dictConfig format\nis the best source of information about logging configuration dictionaries.\nHowever, to give you a taste of what is possible, here are several examples.
\nPremièrement, voici une configuration simple qui écrit toutes les journalisations provenant du journaliseur django dans un fichier local :
\nLOGGING = {\n 'version': 1,\n 'disable_existing_loggers': False,\n 'handlers': {\n 'file': {\n 'level': 'DEBUG',\n 'class': 'logging.FileHandler',\n 'filename': '/path/to/django/debug.log',\n },\n },\n 'loggers': {\n 'django': {\n 'handlers': ['file'],\n 'level': 'DEBUG',\n 'propagate': True,\n },\n },\n}\nSi vous utilisez cet exemple, prenez soin de remplacer le chemin 'filename' par un emplacement accessible en écriture par l’utilisateur faisant fonctionner l’application Django.
Deuxièmement, voici un exemple expliquant comment journaliser les messages de Django dans la console. Cela peut se révéler utile en phase de développement local.
\nPar défaut, cette configuration n’envoie que les messages de niveau INFO ou plus élevé vers la console (comme la configuration de journalisation par défaut de Django, sauf que cette dernière n’affiche les messages de journalisation que si DEBUG=True). Django ne génère pas tant de messages de ce genre. Cependant, avec cetet configuration, vous pouvez aussi définir la variable d’environnement DJANGO_LOG_LEVEL=DEBUG pour voir tous les messages de débogage journalisés par Django, ce qui est très bavard car toutes les requêtes de base de données sont incluses :
import os\n\nLOGGING = {\n 'version': 1,\n 'disable_existing_loggers': False,\n 'handlers': {\n 'console': {\n 'class': 'logging.StreamHandler',\n },\n },\n 'loggers': {\n 'django': {\n 'handlers': ['console'],\n 'level': os.getenv('DJANGO_LOG_LEVEL', 'INFO'),\n },\n },\n}\nFinalement, voici un exemple d’une configuration de journalisation plutôt complexe :
\nLOGGING = {\n 'version': 1,\n 'disable_existing_loggers': False,\n 'formatters': {\n 'verbose': {\n 'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'\n },\n 'simple': {\n 'format': '%(levelname)s %(message)s'\n },\n },\n 'filters': {\n 'special': {\n '()': 'project.logging.SpecialFilter',\n 'foo': 'bar',\n },\n 'require_debug_true': {\n '()': 'django.utils.log.RequireDebugTrue',\n },\n },\n 'handlers': {\n 'console': {\n 'level': 'INFO',\n 'filters': ['require_debug_true'],\n 'class': 'logging.StreamHandler',\n 'formatter': 'simple'\n },\n 'mail_admins': {\n 'level': 'ERROR',\n 'class': 'django.utils.log.AdminEmailHandler',\n 'filters': ['special']\n }\n },\n 'loggers': {\n 'django': {\n 'handlers': ['console'],\n 'propagate': True,\n },\n 'django.request': {\n 'handlers': ['mail_admins'],\n 'level': 'ERROR',\n 'propagate': False,\n },\n 'myproject.custom': {\n 'handlers': ['console', 'mail_admins'],\n 'level': 'INFO',\n 'filters': ['special']\n }\n }\n}\nCette configuration de journalisation effectue les choses suivantes :
\nElle identifie la configuration comme étant au format « dictConfig version 1 ». C’est actuellement la seule version du format dictConfig.
Elle définit deux formateurs :
\nsimple qui ne fait qu’afficher le nom du niveau de journal (par ex. DEBUG) et le message de journal.
The format string is a normal Python formatting string\ndescribing the details that are to be output on each logging\nline. The full list of detail that can be output can be\nfound in Formatter Objects.
verbose qui affiche le nom du niveau de journal, le message de journal ainsi que l’heure, le processus, le fil d’exécution et le module qui ont généré le message.
Elle définit deux filtres :
\nproject.logging.SpecialFilter par l’alias special. Si ce filtre nécessite des paramètres supplémentaires, ils peuvent être fournis sous forme de clés supplémentaires dans le dictionnaire de configuration du filtre. Dans ce cas, le paramètre foo reçoit la valeur bar au moment de l’instanciation de SpecialFilter.
django.utils.log.RequireDebugTrue, qui transmet plus loin les messages lorsque DEBUG vaut True.
Elle définit deux gestionnaires :
\nconsole, un gestionnaire StreamHandler affichant tout message de niveau DEBUG ou plus élevé vers la sortie d’erreur (stderr). Ce gestionnaire utilise le format d’affichage simple.
mail_admins, un gestionnaire AdminEmailHandler qui avertit par courriel les administrateurs du site de tout message de niveau ERROR ou plus élevé. Ce gestionnaire utilise le filtre d’affichage special.
Elle configure trois journaliseurs :
\ndjango, qui transmet tous les messages au gestionnaire console.
django.request qui transmet tous les messages de niveau ERROR au gestionnaire mail_admins. De plus, ce journaliseur est configuré pour ne pas propager les messages. Cela signifie que les messages à destination de django.request ne seront pas traités par le journaliseur parent django.
myproject.custom qui transmet tous les messages de niveau INFO ou plus élevé et correspondant au filtre special vers deux gestionnaires, console et mail_admins. Cela signifie que tous les messages de niveau INFO ou plus élevé seront affichés dans la console. Les messages de niveau ERROR et CRITICAL seront de plus expédiés par courriel.
Si vous ne souhaitez pas utiliser le format dictConfig de Python pour configurer la journalisation, il est possible d’indiquer un système de configuration alternatif.
Le réglage LOGGING_CONFIG définit l’exécutable utilisé pour configurer les journaliseurs de Django. Par défaut, il indique la fonction logging.config.dictConfig() de Python. Cependant, si vous souhaitez utiliser un autre procédé de configuration, vous pouvez indiquer n’importe quel autre exécutable acceptant un seul paramètre. Le contenu de LOGGING sera fourni comme valeur de ce paramètre au moment de la configuration de la journalisation.
Si vous ne souhaitez pas configurer de journalisation (ou que vous vouliez le faire manuellement selon votre propre méthode), vous pouvez définir LOGGING_CONFIG à None. Cela va désactiver le processus de configuration pour la ref:journalisation par défaut de Django <default-logging-configuration>. Voici un exemple qui désactive la configuration de journalisation de Django, puis qui configure manuellement la journalisation :
settings.pyLOGGING_CONFIG = None\n\nimport logging.config\nlogging.config.dictConfig(...)\nEn définissant LOGGING_CONFIG à None, vous ne faites que désactiver le processus de configuration automatique, pas la journalisation elle-même. Même quand vous désactivez le processus de configuration, Django continue de faire appel à la journalisation, dont le comportement correspondra alors à ce qui est défini par défaut.
Django fournit un certain nombre d’utilitaires pour gérer les exigences particulières de la journalisation dans le contexte d’un environnement de serveur Web.
\nDjango fournit plusieurs journaliseurs intégrés :
\ndjangoLien vers cette rubrique#django est le journaliseur « fourre-tout ». Aucun message n’est directement envoyé à ce journaliseur.
django.requestLien vers cette rubrique#Messages de journal liés au traitement des requêtes. Les réponses 5xx sont signalées comme des messages ERROR. Les réponses 4xx sont signalées comme des messages WARNING.
Les messages envoyés à ce journaliseur possèdent le contexte supplémentaire suivant :
\nstatus_code: le code de réponse HTTP associé à la requête.
request: l’objet requête qui a généré le message de journal.
django.templateLien vers cette rubrique#Journalise les messages liés au rendu des gabarits.
\nLes variables de contexte manquantes sont journalisées comme des messages de type DEBUG.
Les exceptions non interceptées générées pendant le rendu d’une balise {% include %} sont journalisées comme messages WARNING lorsque le mode débogage est désactivé (utile car {% include %} réduit au silence l’exception et renvoie une chaîne vide dans ce cas).
django.db.backendsLien vers cette rubrique#Messages en lien avec l’interaction entre le code et la base de données. Par exemple, chaque instruction SQL de niveau applicatif exécutée par une requête est envoyée à ce journaliseur au niveau DEBUG.
Les messages envoyés à ce journaliseur possèdent le contexte supplémentaire suivant :
\nduration: le temps d’exécution de l’instruction SQL concernée.
sql: l’instruction SQL exécutée.
params: les paramètres utilisés dans l’appel SQL.
Pour des raisons de performance, la journalisation SQL n’est activée que lorsque settings.DEBUG est défini à True, peu importe le niveau de journalisation ou les gestionnaires installés.
Cette journalisation ne concerne pas l’initialisation au niveau infrastructure (par ex. SET TIMEZONE) ni les requêtes de gestion de transaction (par ex. BEGIN, COMMIT ou ROLLBACK). Activez la journalisation des requêtes au niveau de la base de données si vous souhaitez voir toutes les requêtes à la base de données.
django.security.*Lien vers cette rubrique#Les journaliseurs security reçoivent les messages à chaque occurrence de SuspiciousOperation. Il existe un sous-sérialiseur pour chaque sous-type de SuspiciousOperation. Le niveau des événements journalisés dépend de l’endroit où l’exception est traitée. La plupart des occurrences sont journalisées comme des avertissements, alors que toute exception SuspiciousOperation atteignant le gestionnaire WSGI sera journalisée comme une erreur. Par exemple, lorsqu’un en-tête HTTP Host contenu dans une requête de client ne correspond pas à ALLOWED_HOSTS, Django renvoie une réponse 400 et un message d’erreur est journalisé dans le journaliseur django.security.DisallowedHost.
Ces événements de journal aboutissent par défaut dans le journaliseur django, qui envoie les erreurs par courriel aux administrateurs lorsque DEBUG=False. Les requêtes aboutissant à une réponse 400 en raison d’une erreur SuspiciousOperation ne sont pas journalisées dans django.request, mais seulement dans le journaliseur django.security.
Pour réduire au silence un type particulier de SuspiciousOperation, vous pouvez surcharger le journaliseur correspondant en suivant cet exemple :
'handlers': {\n 'null': {\n 'class': 'logging.NullHandler',\n },\n},\n'loggers': {\n 'django.security.DisallowedHost': {\n 'handlers': ['null'],\n 'propagate': False,\n },\n},\ndjango.db.backends.schemaLien vers cette rubrique#Journalise les requêtes SQL exécutées pendant les modifications de schéma de la base de données effectuées par le système des migrations. Notez que les requêtes exécutées par RunPython ne sont pas journalisées.
Django propose un gestionnaire de journalisation en plus de ceux offerts par le module logging de Python.
Ce gestionnaire envoie un courriel aux administrateurs du site pour chaque message de journal qu’il reçoit.
\nIf the log record contains a request attribute, the full details\nof the request will be included in the email. The email subject will\ninclude the phrase « internal IP » if the client’s IP address is in the\nINTERNAL_IPS setting; if not, it will include « EXTERNAL IP ».
Si la ligne de journal contient des informations sur une trace de débogage, celle-ci est incluse dans le courriel.
\nLe paramètre include_html de AdminEmailHandler est utilisé pour contrôler si le courriel contenant la trace de débogage doit inclure une pièce jointe HTML contenant la page Web complète de débogage qui aurait été affichée si le réglage DEBUG valait True. Pour définir cette valeur dans votre configuration, incluez ce paramètre dans la définition du gestionnaire pour django.utils.log.AdminEmailHandler, comme ceci :
'handlers': {\n 'mail_admins': {\n 'level': 'ERROR',\n 'class': 'django.utils.log.AdminEmailHandler',\n 'include_html': True,\n }\n},\nNotez que cette version HTML du courriel contient une trace de débogage complète, avec les noms et valeurs des variables locales à chaque niveau de la trace, en plus des valeurs de vos réglages Django. Ces informations peuvent contenir des éléments très sensibles et il n’est pas toujours souhaitable de les envoyer par courriel. Envisagez l’utilisation d’un service comme Sentry pour obtenir le meilleur des deux mondes, de riches informations avec des traces de débogage complètes, mais avec la sécurité de ne pas envoyer ces informations par messagerie. Vous pouvez aussi désigner explicitement certaines informations sensibles comme devant être exclues des rapports d’erreurs ; voir Filtrage des rapports d’erreurs pour plus de détails à ce sujet.
\nEn définissant le paramètre email_backend de AdminEmailHandler, le moteur de messagerie utilisé par le gestionnaire peut être surchargé, comme ceci :
'handlers': {\n 'mail_admins': {\n 'level': 'ERROR',\n 'class': 'django.utils.log.AdminEmailHandler',\n 'email_backend': 'django.core.mail.backends.filebased.EmailBackend',\n }\n},\nPar défaut, c’est une instance du moteur de messagerie indiqué dans EMAIL_BACKEND qui est utilisée.
Envoie des courriels aux utilisateurs administrateurs. Pour personnaliser ce comportement, vous pouvez créer une sous-classe de AdminEmailHandler et surcharger cette méthode.
Django propose deux filtres de journalisation en plus de ceux offerts par le module logging de Python.
Ce filtre accepte une fonction de rappel (qui ne doit accepter qu’un seul paramètre, l’enregistrement à journaliser) et appelle celle-ci pour chaque enregistrement qui transite par ce filtre. Le traitement de l’enregistrement s’arrête si la fonction de rappel renvoie False.
Par exemple, pour exclure UnreadablePostError (généré lorsqu’un utilisateur annule un téléversement) des courriels envoyés aux administrateurs, cette fonction de filtre pourrait être créée :
from django.http import UnreadablePostError\n\ndef skip_unreadable_post(record):\n if record.exc_info:\n exc_type, exc_value = record.exc_info[:2]\n if isinstance(exc_value, UnreadablePostError):\n return False\n return True\npuis ajoutée à la configuration de journalisation :
\n'filters': {\n 'skip_unreadable_posts': {\n '()': 'django.utils.log.CallbackFilter',\n 'callback': skip_unreadable_post,\n }\n},\n'handlers': {\n 'mail_admins': {\n 'level': 'ERROR',\n 'filters': ['skip_unreadable_posts'],\n 'class': 'django.utils.log.AdminEmailHandler'\n }\n},\nCe filtre ne laisse passer les enregistrements que lorsque settings.DEBUG vaut False.
Ce filtre est utilisé comme le montre l’exemple ci-dessous dans la configuration par défaut de LOGGING pour garantir que AdminEmailHandler n’envoie des courriels d’erreur aux administrateurs que lorsque DEBUG vaut False:
'filters': {\n 'require_debug_false': {\n '()': 'django.utils.log.RequireDebugFalse',\n }\n},\n'handlers': {\n 'mail_admins': {\n 'level': 'ERROR',\n 'filters': ['require_debug_false'],\n 'class': 'django.utils.log.AdminEmailHandler'\n }\n},\nCe filtre est similaire à RequireDebugFalse, sauf que les enregistrements ne sont retransmis que lorsque DEBUG vaut True.
Par défaut, Django configure la journalisation suivante :
\nLorsque DEBUG vaut True:
Le journaliseur « fourre-tout » django envoie tous les messages de niveau INFO ou plus élevé vers la console.
Le journaliseur py.warnings qui s’occupe des messages produits par warnings.warn(), envoie les messages vers la console.
Lorsque DEBUG vaut False:
Le journaliseur django envoie les messages de niveau ERROR ou CRITICAL à AdminEmailHandler.
Consultez aussi Configuration de la journalisation pour savoir comment compléter ou remplacer cette configuration de journalisation par défaut.
\n