Journalisation¶
Voir aussi
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.
Configuration de journalisation par défaut de Django¶
Par défaut, Django utilise le format logging.config.dictConfig de Python.
Conditions de journalisation par défaut¶
Les conditions complètes de journalisation par défaut sont :
Lorsque DEBUG
vaut True
:
- Le journaliseur
django
envoie les messages de la hiérarchiedjango
(saufdjango.server
) de niveauINFO
ou plus vers la console.
Lorsque DEBUG
vaut False
:
- Le journaliseur
django
envoie les messages de la hiérarchiedjango
(saufdjango.server
) de niveauERROR
ouCRITICAL
à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.
Définition de journalisation par défaut¶
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:
{
"version": 1,
"disable_existing_loggers": False,
"filters": {
"require_debug_false": {
"()": "django.utils.log.RequireDebugFalse",
},
"require_debug_true": {
"()": "django.utils.log.RequireDebugTrue",
},
},
"formatters": {
"django.server": {
"()": "django.utils.log.ServerFormatter",
"format": "[{server_time}] {message}",
"style": "{",
}
},
"handlers": {
"console": {
"level": "INFO",
"filters": ["require_debug_true"],
"class": "logging.StreamHandler",
},
"django.server": {
"level": "INFO",
"class": "logging.StreamHandler",
"formatter": "django.server",
},
"mail_admins": {
"level": "ERROR",
"filters": ["require_debug_false"],
"class": "django.utils.log.AdminEmailHandler",
},
},
"loggers": {
"django": {
"handlers": ["console", "mail_admins"],
"level": "INFO",
},
"django.server": {
"handlers": ["django.server"],
"level": "INFO",
"propagate": False,
},
},
}
Consultez Configuring logging pour savoir comment compléter ou remplacer cette configuration de journalisation par défaut.
Extensions de journalisation de Django¶
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.
Journaliseurs¶
Django fournit plusieurs journaliseurs intégrés :
django
¶
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.
django.request
¶
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 :
status_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.server
¶
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 :
status_code
: le code de réponse HTTP associé à la requête.request
: l’objet requête (de typesocket.socket
) qui a généré le message de journal.
django.template
¶
Journalise les messages liés au rendu des gabarits.
- Les variables de contexte manquantes sont journalisées comme des messages de type
DEBUG
.
django.db.backends
¶
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 :
duration
: 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
). 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.
La prise en charge de la journalisation des requêtes de gestion de transaction (BEGIN
, COMMIT
et ROLLBACK
) a été ajoutée.
django.security.*
¶
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 :
LOGGING = {
# ...
"handlers": {
"null": {
"class": "logging.NullHandler",
},
},
"loggers": {
"django.security.DisallowedHost": {
"handlers": ["null"],
"propagate": False,
},
},
# ...
}
Les autres journaliseurs django.security
non basés sur SuspiciousOperation
sont :
django.security.csrf
: pour les échecs CSRF.
django.db.backends.schema
¶
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.
Gestionnaires¶
Django propose un gestionnaire de journalisation en plus de ceux offerts par le module logging de Python
.
-
class
AdminEmailHandler
(include_html=False, email_backend=None, reporter_class=None)¶ 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églageINTERNAL_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.
Le paramètre
include_html
deAdminEmailHandler
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églageDEBUG
valaitTrue
. Pour définir cette valeur dans votre configuration, incluez ce paramètre dans la définition du gestionnaire pourdjango.utils.log.AdminEmailHandler
, comme ceci :"handlers": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "include_html": True, }, }
Soyez conscient des implications sécuritaires de la journalisation lorsque vous utilisez
AdminEmailHandler
.En définissant le paramètre
email_backend
deAdminEmailHandler
, le moteur de messagerie utilisé par le gestionnaire peut être surchargé, comme ceci :"handlers": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "email_backend": "django.core.mail.backends.filebased.EmailBackend", }, }
Par défaut, c’est une instance du moteur de messagerie indiqué dans
EMAIL_BACKEND
qui est utilisée.Le paramètre
reporter_class
deAdminEmailHandler
permet de fournir une sous-classe dedjango.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": { "mail_admins": { "level": "ERROR", "class": "django.utils.log.AdminEmailHandler", "include_html": True, "reporter_class": "somepackage.error_reporter.CustomErrorReporter", }, }
-
send_mail
(subject, message, *args, **kwargs)¶ Envoie des courriels aux utilisateurs administrateurs. Pour personnaliser ce comportement, vous pouvez créer une sous-classe de
AdminEmailHandler
et surcharger cette méthode.
-
Filtres¶
Django propose quelques filtres de journalisation en plus de ceux offerts par le module logging
de Python.
-
class
CallbackFilter
(callback)¶ 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 def skip_unreadable_post(record): if record.exc_info: exc_type, exc_value = record.exc_info[:2] if isinstance(exc_value, UnreadablePostError): return False return True
puis ajoutée à la configuration de journalisation :
LOGGING = { # ... "filters": { "skip_unreadable_posts": { "()": "django.utils.log.CallbackFilter", "callback": skip_unreadable_post, }, }, "handlers": { "mail_admins": { "level": "ERROR", "filters": ["skip_unreadable_posts"], "class": "django.utils.log.AdminEmailHandler", }, }, # ... }
-
class
RequireDebugFalse
¶ Ce filtre ne laisse passer les enregistrements que lorsque
settings.DEBUG
vautFalse
.Ce filtre est utilisé comme le montre l’exemple ci-dessous dans la configuration par défaut de
LOGGING
pour garantir queAdminEmailHandler
n’envoie des courriels d’erreur aux administrateurs que lorsqueDEBUG
vautFalse
:LOGGING = { # ... "filters": { "require_debug_false": { "()": "django.utils.log.RequireDebugFalse", }, }, "handlers": { "mail_admins": { "level": "ERROR", "filters": ["require_debug_false"], "class": "django.utils.log.AdminEmailHandler", }, }, # ... }
-
class
RequireDebugTrue
¶ Ce filtre est similaire à
RequireDebugFalse
, sauf que les enregistrements ne sont retransmis que lorsqueDEBUG
vautTrue
.