Configuration et utilisation de la journalisation

Voir aussi

• Référence de la journalisation dans Django
• Aperçu de la journalisation dans Django

Django contient une configuration de journalisation par défaut fonctionnelle qui peut facilement être étendue.

Appel de journalisation basique

Pour envoyer un message de journalisation à partir de votre code, écrivez un appel de journalisation.

Ne soyez pas tenté-e-s d’utiliser des appels de journalisation dans settings.py.

La façon dont la journalisation de Django est configuré dans le cadre de la fonction setup() signifie que les appels de journalisation placés dans settings.py peuvent ne pas fonctionner comme prévu, car la journalisation n’est pas encore configurée à ce stade. Pour explorer la journalisation, utilisez une fonction de vue comme suggéré dans l’exemple ci-dessous.

Tout d’abord, importez la bibliothèque Python logging et obtenez une instance de journalisation avec logging.getLogger(). Passez à la méthode getLogger() un nom pour l’identifier et pour les lignes qu’il produira. Une bonne option est d’utiliser __name__ (voir Utilisation de l’espace de noms des journaliseurs ci-dessous pour en savoir plus), ce qui donnera le nom du module Python actuel sous forme de chemin pointé

import logging

logger = logging.getLogger(__name__)

Par convention, il est bon d’effectuer cette déclaration au niveau du module.

Puis dans une fonction, par exemple dans une vue, envoyez un enregistrement au journaliseur

def some_view(request):
    ...
    if some_risky_state:
        logger.warning('Platform is running at risk')

Lorsque ce code est exécuté, un objet LogRecord contenant ce message sera envoyé au journaliseur. SI vous utilisez la configuration de journalisation de Django par défaut, le message apparaîtra dans la console.

Le niveau WARNING utilisé dans l’exemple ci-dessus est l’un des quelques niveaux de sévérité de journalisation: DEBUG`, INFO, WARNING, ERROR, CRITICAL. Un autre exemple pourrait être

logger.critical('Payment system is not responding')

Important

Les enregistrements ayant un niveau plus faible que WARNING n’apparaîtront pas dans la console par défaut. La modification de ce comportement nécessite une configuration supplémentaire.

Personnalisation de la configuration de journalisation

Même si la configuration de journalisation de Django fonctionne telle quelle, vous pouvez contrôler exactement la manière dont vos journaux sont envoyés à diverses destinations, vers des fichiers journaux, des services externes, par courriel, etc. en ajoutant un peu de configuration supplémentaire.

Vous pouvez configurer :

• les correspondances des journaliseurs (logger) pour déterminer quels enregistrements sont envoyés à quels gestionnaires
• les gestionnaires (handler) pour déterminer ce qu’ils font des enregistrements qu’ils reçoivent
• les filtres, pour ajouter du contrôle supplémentaire sur le transfert des enregistrements, et même les modifier sur place
• les formateurs, pour convertir les objets LogRecord en une chaîne ou toute autre forme qui soit lisible par les humains ou un autre système

Il existe plusieurs manières de configurer la journalisation. Dans Django, le réglage LOGGING est le plus couramment utilisé. Ce réglage utilise le format dictConfig, et étend la configuration de journalisation par défaut.

Consultez Configuration de la journalisation pour une explication sur la manière dont vos réglages personnalisés sont fusionnés avec ceux de Django.

Consultez la documentation de journalisation de Python pour plus de détails sur les autres manières de configurer la journalisation. Par simplification, cette documentation ne va considérer que la configuration au travers du réglage LOGGING.

Configuration de journalisation basique

Lors de la configuration de la journalisation, il est raisonnable de

Créer un dictionnaire LOGGING

Dans votre fichier settings.py:

LOGGING = {
    'version': 1,                       # the dictConfig format version
    'disable_existing_loggers': False,  # retain the default loggers
}

Il est presque toujours recommandé de conserver et étendre la configuration de journalisation par défaut en définissant disable_existing_loggers à False.

Configurer un gestionnaire

Cet exemple configure un seul gestionnaire (handler) nommé file, qui utilise la classe FileHandler de Python pour enregistrer les journaux de niveau DEBUG et plus élevé dans le fichier general.log (à la racine du projet) :

LOGGING = {
    [...]
    'handlers': {
        'file': {
            'class': 'logging.FileHandler',
            'filename': 'general.log',
        },
    },
}

Différentes classes de gestionnaire acceptent différentes options de configuration. Pour plus d’informations sur les classes de gestionnaire disponibles, consultez AdminEmailHandler fournie par Django et les diverses classes de gestionnaire fournies par Python.

Les niveaux de journalisation peuvent aussi être définis sur les gestionnaires (par défaut, elles acceptent des messages de tous les niveaux). En utilisant l’exemple ci-dessus, l’ajout de :

{
    'class': 'logging.FileHandler',
    'filename': 'general.log',
    'level': 'DEBUG',
}

définirait une configuration de gestionnaire n’acceptant que des enregistrements de niveau DEBUG ou supérieur.

Configuration d’une correspondance de journaliseur

Pour envoyer des enregistrements à ce gestionnaire, configurez une correspondance pour l’utiliser, par exemple :

LOGGING = {
    [...]
    'loggers': {
        '': {
            'level': 'DEBUG',
            'handlers': ['file'],
        },
    },
}

Le nom de correspondance détermine quels sont les enregistrements de journaux qu’il va traiter. Cette configuration ('') is anonyme. Cela signifie qu’elle traitera les enregistrements de tous les journaliseurs (voir Utilisation de l’espace de noms des journaliseurs ci-dessous sur la manière d’utiliser les noms de correspondance pour déterminer les journaliseurs concernés par le traitement de ses enregistrements).

Ceci va transmettre les messages de niveau DEBUG et supérieur au gestionnaire nommé file.

Notez qu’un journaliseur peut transmettre des messages à plusieurs gestionnaires, il existe donc une relation de type plusieurs-à-plusieurs entre les journaliseurs et les gestionnaires.

Si vous exécutez

logger.debug('Attempting to connect to API')

dans vote code, vous trouverez ce message dans le fichier general.log` à la racine de votre projet.

Configuration d’un formateur

Par défaut, le résultat final de journalisation contient la partie message de chaque enregistrement de journal. Utilisez un formateur si vous souhaitez inclure des données supplémentaires. Commencez par nommer et définir vos formateurs. Cet exemple définit des formateurs nommés verbose et simple:

LOGGING = {
    [...]
    'formatters': {
        'verbose': {
            'format': '{name} {levelname} {asctime} {module} {process:d} {thread:d} {message}',
            'style': '{',
        },
        'simple': {
            'format': '{levelname} {message}',
            'style': '{',
        },
    },
}

Le mot-clé style permet d’indiquer { pour la mise en forme str.format() ou $ pour string.Template; la valeur par défaut est $.

Voir LogRecord attributes au sujet des attributs de LogRecord qu’il est possible d’inclure.

Pour appliquer un formateur à un gestionnaire, ajoutez une entrée formatter au dictionnaire du gestionnaire en vous référant au formateur par son nom, par exemple :

'handlers': {
    'file': {
        'class': 'logging.FileHandler',
        'filename': 'general.log',
        'formatter': 'verbose',
    },
},

Utilisation de l’espace de noms des journaliseurs

La configuration de journalisation anonyme '' capture les journaux de n’importe quelle application Python. Une configuration de journalisation nommée ne capturera que les journaux de journaliseurs dont le nom correspond.

L’espace de noms d’une instance de journaliseur est défini en utilisant getLogger(). Par exemple, dans views.py de my_app:

logger = logging.getLogger(__name__)

va créer un journaliseur dans l’espace de noms my_app.views. __name__ permet d’organiser automatiquement les messages de journalisation en fonction de leur provenance dans les applications de votre projet. Cela garantit par la même occasion que les collisions de noms seront évitées.

Une correspondance de journaliseur nommée my_app.views va capturer les enregistrements de ce journaliseur :

LOGGING = {
    [...]
    'loggers': {
        'my_app.views': {
            ...
        },
    },
}

Une correspondance de journaliseur nommée my_app sera plus permissive, capturant les enregistrements de journaliseurs partout dans l’espace de noms my_app (y compris my_app.views`, my_app.utils et ainsi de suite) :

LOGGING = {
    [...]
    'loggers': {
        'my_app': {
            ...
        },
    },
}

Il est aussi possible de définir les espaces de noms des journaliseurs de manière explicite

logger = logging.getLogger('project.payment')

et de définir ensuite en fonction les correspondances de journaliseurs.

Utilisation des hiérarchies et de la propagation des journaliseurs

La nomenclature des journaliseurs est hiérarchique. my_app est le parent de my_app.views, qui est le parent de my_app.views.private. Sans autre indication, les correspondances de journaliseurs vont propager les enregistrements qu’elles traitent à leurs parents ; un enregistrement d’un journaliseur dans l’espace de noms my_app.views.private sera traité à la fois par les correspondances de my_app et de my_app.views.

Pour contrôler ce comportement, donnez une valeur à la clé de propagation sur les correspondances que vous définissez

LOGGING = {
    [...]
    'loggers': {
        'my_app': {
            [...]
        },
        'my_app.views': {
            [...]
        },
        'my_app.views.private': {
            [...]
            'propagate': False,
        },
    },
}

propagate vaut True par défaut. Dans cet exemple, les journaux de my_app.views.private ne seront pas traités par les parents, mais les journaux de my_app.views le seront.

Configuration de journalisation réactive

La journalisation est d’autant plus utile qu’elle contient des informations riches, mais sans information inutile, et cette pesée d’intérêts dépend de ce que vous faites. Lorsque vous êtes en mode débogage, le niveau d’informations souhaité dépasse largement ce qui sera nécessaire lorsque vous passerez votre projet en production.

Vous pouvez configurer la journalisation pour qu’elle vous offre le niveau de détail nécessaire au moment où vous en avez besoin. Au lieu de modifier manuellement la configuration pour cet objectif, une meilleure façon est d’appliquer une configuration automatiquement en fonction de l’environnement.

Par exemple, vous pouvez définir une variable d’environnement DJANGO_LOG_LEVEL appropriée dans vos environnements de développement et de pré-production, et en faire usage dans une configuration de journaliseur de cette façon

'level': os.getenv('DJANGO_LOG_LEVEL', 'WARNING')

de cette manière, tant que l’environnement n’indique par un niveau de journalisation plus bas, cette configuration ne propagera que les enregistrements de sévérité WARNING et supérieure à son gestionnaire.

D’autres options de la configuration (comme les options level ou formatter des gestionnaires) peuvent également être ajustées de cette façon.