Journalisation¶
Voir aussi
Les programmeurs Python utilisent fréquemment print()
dans leur code comme méthode rapide et pratique de débogage. L’utilisation de l’infrastructure de journalisation demande à peine plus d’effort que ça, mais c’est beaucoup plus élégant et souple. En plus d’être pratique pour le débogage, la journalisation peut aussi offrir plus d’information mieux structurée au sujet de l’état et de la santé de votre application.
Aperçu¶
Django utilise et étend le module logging
intégré de Python pour effectuer la journalisation au niveau système. Ce module est abordé en détails dans la propre documentation de Python ; cette section fournit un aperçu rapide.
Les acteurs en jeu¶
Une configuration de journalisation Python consiste en quatre parties :
Journaliseurs¶
Un 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.
Un 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 :
DEBUG
: information système de bas niveau à des fins de débogageINFO
: information système généraleWARNING
: 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.
Lorsqu’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é.
Dès qu’un journaliseur a déterminé qu’un message doit être traité, il est transmis à un gestionnaire (« handler »).
Gestionnaires¶
Le gestionnaire (handler) 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.
Comme 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.
Un 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.
Filtres¶
Un filtre (filter) permet d’ajouter un contrôle supplémentaire sur la sélection des enregistrements de journal lorsqu’ils sont transmis du journaliseur au gestionnaire.
Par 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.
Formateurs¶
Pour 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.
Implications quant à la sécurité¶
Le système de journalisation traite de l’information potentiellement sensible. Par exemple, une entrée de journalisation peut contenir de l’information au sujet d’une requête web ou une trace d’erreur, alors que certaines données collectées dans vos propres journaliseurs peuvent aussi présenter des implications quant à la sécurité. Vous devez être sûr-e de savoir :
- quelle information est collectée
- où celle-ci sera ensuite stockée
- comment va-t-elle être transférée
- qui pourra y avoir accès.
Pour aider à contrôler la collecte des informations sensibles, vous pouvez explicitement désigner certaines informations comme sensibles pour qu’elles soient exclues des rapports d’erreurs – des informations plus complètes se trouvent dans filtrage des rapports d’erreurs.
AdminEmailHandler
¶
La classe AdminEmailHandler
mérite d’être mentionnée dans un contexte de sécurité. Si son option include_html
est activée, le courriel qu’elle envoie contiendra une trace d’erreur complète, avec les noms et les valeurs des variables locales à chaque niveau de la pile, en plus des valeurs de vos réglages Django (en d’autres termes, le même niveau de détail qui est exposé dans une page Web lorsque DEBUG
vaut True
).
Il n’est généralement pas considéré comme une bonne idée d’envoyer de telles informations potentiellement sensibles par courriel. Considérez plutôt le recours à l’un des nombreux services tiers auxquels des journaux détaillés peuvent être envoyés pour obtenir le meilleur de plusieurs mondes – l’information riche de traces d’erreurs complètes, une gestion claire de qui est averti et peut accéder à l’information, et ainsi de suite.
Configuration de la journalisation¶
La bibliothèque de journalisation de Python fournit plusieurs techniques de configuration, que ce soit par interface programmable ou par des fichiers de configuration. Par défaut, Django utilise le format dictConfig.
Pour 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
(qui est la valeur par défaut dictConfig
si la clé est manquante), 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.
Exemples¶
La documentation complète du format dictConfig est la meilleure source d’informations concernant les dictionnaires de configuration de la journalisation. Cependant, pour vous donner un petit aperçu de ce qui est réalisable, voici quelques exemples.
Pour commencer, voici une petite configuration qui permet d’afficher tous les messages de journal dans la console :
import os
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'console': {
'class': 'logging.StreamHandler',
},
},
'root': {
'handlers': ['console'],
'level': 'WARNING',
},
}
Ceci configure le journaliseur parent root
pour envoyer les messages de niveau WARNING
ou plus élevé vers le gestionnaire de la console. En ajustant le niveau à INFO
ou DEBUG
, vous pouvez afficher plus de messages. Ceci peut se révéler utile durant le développement.
Ensuite, nous pouvons ajouter plus de journalisation fine. Voici un exemple sur la façon de faire produire plus de messages par le système de journalisation pour le journaliseur nommé spécifiquement django:
import os
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'console': {
'class': 'logging.StreamHandler',
},
},
'root': {
'handlers': ['console'],
'level': 'WARNING',
},
'loggers': {
'django': {
'handlers': ['console'],
'level': os.getenv('DJANGO_LOG_LEVEL', 'INFO'),
'propagate': False,
},
},
}
Par défaut, cette configuration envoie les messages du journaliseur django
de niveau INFO
ou plus élevé vers la console. Il s’agit du même niveau que dans 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 ces messages de niveau INFO
. Cependant, avec cette 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.
Vous n’êtes pas obligé d’envoyer la journalisation vers la console. Voici une configuration qui écrit toutes les journalisations provenant du journaliseur nommé django dans un fichier local :
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'file': {
'level': 'DEBUG',
'class': 'logging.FileHandler',
'filename': '/path/to/django/debug.log',
},
},
'loggers': {
'django': {
'handlers': ['file'],
'level': 'DEBUG',
'propagate': True,
},
},
}
Si 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.
Finalement, voici un exemple d’une configuration de journalisation plutôt complexe :
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'verbose': {
'format': '{levelname} {asctime} {module} {process:d} {thread:d} {message}',
'style': '{',
},
'simple': {
'format': '{levelname} {message}',
'style': '{',
},
},
'filters': {
'special': {
'()': 'project.logging.SpecialFilter',
'foo': 'bar',
},
'require_debug_true': {
'()': 'django.utils.log.RequireDebugTrue',
},
},
'handlers': {
'console': {
'level': 'INFO',
'filters': ['require_debug_true'],
'class': 'logging.StreamHandler',
'formatter': 'simple'
},
'mail_admins': {
'level': 'ERROR',
'class': 'django.utils.log.AdminEmailHandler',
'filters': ['special']
}
},
'loggers': {
'django': {
'handlers': ['console'],
'propagate': True,
},
'django.request': {
'handlers': ['mail_admins'],
'level': 'ERROR',
'propagate': False,
},
'myproject.custom': {
'handlers': ['console', 'mail_admins'],
'level': 'INFO',
'filters': ['special']
}
}
}
Cette configuration de journalisation effectue les choses suivantes :
Elle identifie la configuration comme étant au format « dictConfig version 1 ». C’est actuellement la seule version du format dictConfig.
Elle définit deux formateurs :
simple
qui affiche le nom du niveau de journal (par ex.DEBUG
) et le message de journal.La chaîne
format
est une chaîne de format Python normale décrivant les détails de ce qui doit être affiché pour chaque ligne de journal. La liste complète des détails pouvant être affichés se trouve dans 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 :
project.logging.SpecialFilter
par l’aliasspecial
. 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ètrefoo
reçoit la valeurbar
au moment de l’instanciation deSpecialFilter
.django.utils.log.RequireDebugTrue
, qui transmet plus loin les messages lorsqueDEBUG
vautTrue
.
Elle définit deux gestionnaires :
console
, un gestionnaireStreamHandler
affichant tout message de niveauINFO
ou plus élevé vers la sortie d’erreur (sys.stderr
). Ce gestionnaire utilise le format d’affichagesimple
.mail_admins
, un gestionnaireAdminEmailHandler
qui avertit par courriel lesADMINS
du site de tout message de niveauERROR
ou plus élevé. Ce gestionnaire utilise le filtre d’affichagespecial
.
Elle configure trois journaliseurs :
django
, qui transmet tous les messages au gestionnaireconsole
.django.request
qui transmet tous les messages de niveauERROR
au gestionnairemail_admins
. De plus, ce journaliseur est configuré pour ne pas propager les messages. Cela signifie que les messages à destination dedjango.request
ne seront pas traités par le journaliseur parentdjango
.myproject.custom
qui transmet tous les messages de niveauINFO
ou plus élevé et correspondant au filtrespecial
vers deux gestionnaires,console
etmail_admins
. Cela signifie que tous les messages de niveauINFO
ou plus élevé seront affichés dans la console. Les messages de niveauERROR
etCRITICAL
seront de plus expédiés par courriel.
Configuration personnalisée de la journalisation¶
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.
Désactivation de la configuration de 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 de la journalisation par défaut de Django.
En 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.
Voici un exemple qui désactive la configuration de la journalisation par défaut de Django, puis configure manuellement la journalisation :
LOGGING_CONFIG = None
import logging.config
logging.config.dictConfig(...)
Notez que le processus de configuration par défaut n’appelle LOGGING_CONFIG
qu’une fois que les réglages sont complètement chargés. Par contraste, la configuration manuelle de la journalisation dans votre fichier de réglages va charger immédiatement la configuration de journalisation. En conséquence, votre configuration de journalisation doit apparaître après tout réglage dont elle dépend.