Le module de journalisation de Django étend le module Python intégré logging.
La journalisation est configurée dans le contexte plus général de la fonction django.setup() de Django, ce qui fait qu’elle est toujours disponible, sauf si elle est explicitement désactivée.
Par défaut, Django utilise le format logging.config.dictConfig de Python.
\nLes conditions complètes de journalisation par défaut sont :
\nLorsque DEBUG vaut True:
Le journaliseur django envoie les messages de la hiérarchie django (sauf django.server) de niveau INFO ou plus vers la console.
Lorsque DEBUG vaut False:
Le journaliseur django envoie les messages de la hiérarchie django (sauf django.server) de niveau ERROR ou CRITICAL à AdminEmailHandler.
Indépendamment de la valeur de DEBUG:
Le journaliseur django.server envoie des messages au niveau INFO et plus à la console.
Tous les journaliseurs à l’exception de django.server propagent la journalisation vers leur parent, jusqu’au journaliseur racine django. Les gestionnaires console et mail_admins sont liés au journaliseur racine pour offrir le comportement décrit ci-dessus.
Les valeurs par défaut de Python envoient les enregistrements de niveau WARNING et supérieur dans la console.
La configuration de journalisation par défaut de Django hérite des valeurs par défaut de Python. Elle est disponible dans django.utils.log.DEFAULT_LOGGING et définie dans django/utils/log.py:
{\n 'version': 1,\n 'disable_existing_loggers': False,\n 'filters': {\n 'require_debug_false': {\n '()': 'django.utils.log.RequireDebugFalse',\n },\n 'require_debug_true': {\n '()': 'django.utils.log.RequireDebugTrue',\n },\n },\n 'formatters': {\n 'django.server': {\n '()': 'django.utils.log.ServerFormatter',\n 'format': '[{server_time}] {message}',\n 'style': '{',\n }\n },\n 'handlers': {\n 'console': {\n 'level': 'INFO',\n 'filters': ['require_debug_true'],\n 'class': 'logging.StreamHandler',\n },\n 'django.server': {\n 'level': 'INFO',\n 'class': 'logging.StreamHandler',\n 'formatter': 'django.server',\n },\n 'mail_admins': {\n 'level': 'ERROR',\n 'filters': ['require_debug_false'],\n 'class': 'django.utils.log.AdminEmailHandler'\n }\n },\n 'loggers': {\n 'django': {\n 'handlers': ['console', 'mail_admins'],\n 'level': 'INFO',\n },\n 'django.server': {\n 'handlers': ['django.server'],\n 'level': 'INFO',\n 'propagate': False,\n },\n }\n}\nConsultez Configuration de la journalisation pour savoir comment compléter ou remplacer cette configuration de journalisation par défaut.
\nDjango 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#Le journaliseur parent des messages dans la hiérarchie des journaliseurs nommés de Django. Django lui-même ne poste pas de messages avec ce nom. Il utilise plutôt l’un des journaliseurs ci-dessous.
\ndjango.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 requêtes journalisées vers django.security ne sont pas journalisées vers django.request.
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.serverLien vers cette rubrique#Messages de journal liés au traitement des requêtes reçues par le serveur sollicité par la commande runserver. Les réponses HTTP 5xx sont journalisées comme des messages ERROR. Les réponses 4xx sont journalisées comme des messages WARNING, et tout le reste est journalisé comme message INFO.
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.
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.
alias: l’alias de la base de données utilisée 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 et des autres erreurs liées à la sécurité. Il existe un sous-sérialiseur pour chaque sous-type d’erreur de sécurité, y compris toutes les 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},\nLes autres journaliseurs django.security non basés sur SuspiciousOperation sont :
django.security.csrf: pour les échecs CSRF.
django.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. Les messages de ce journaliseur possèdent params et sql dans leur contexte complémentaire (mais pas la durée comme django.db.backends). Ces valeurs ont la même signification que django.db.backends l’explique.
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 (ADMINS) pour chaque message de journal qu’il reçoit.
Si le message de journalisation contient un attribut request, les détails complets de la requête seront inclus dans le courriel. Le sujet du courriel contiendra « internal IP » si l’adresse IP du client se trouve dans le réglage INTERNAL_IPS; sinon, il contiendra « 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},\nSoyez conscient des implications sécuritaires de la journalisation lorsque vous utilisez AdminEmailHandler.
En 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.
Le paramètre reporter_class de AdminEmailHandler permet de fournir une sous-classe de django.views.debug.ExceptionReporter pour personnaliser le texte de trace d’erreur envoyé dans le corps du courriel. Indiquez un chemin d’importation sous forme de chaîne vers la classe que vous souhaitez utiliser, comme ceci
'handlers': {\n 'mail_admins': {\n 'level': 'ERROR',\n 'class': 'django.utils.log.AdminEmailHandler',\n 'include_html': True,\n 'reporter_class': 'somepackage.error_reporter.CustomErrorReporter',\n },\n},\nEnvoie 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 quelques 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.