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é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.

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 :

settings.py
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:

settings.py
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 :

settings.py
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 :

settings.py
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’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 :

    • console, un gestionnaire StreamHandler affichant tout message de niveau INFO ou plus élevé vers la sortie d’erreur (sys.stderr). Ce gestionnaire utilise le format d’affichage simple.

    • mail_admins, un gestionnaire AdminEmailHandler qui avertit par courriel les ADMINS du site de tout message de niveau ERROR ou plus élevé. Ce gestionnaire utilise le filtre d’affichage special.

  • Elle configure trois journaliseurs :

    • django, 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.

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 :

settings.py
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.

Back to Top