# Documentation Django 5.2.8

# Journalisation

Voir aussi

- Configuration et utilisation de la journalisation

- Référence de la journalisation dans Django

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

- Gestionnaires

- Filtres

- Formateurs

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

The `LOGGING_CONFIG` setting defines the callable that will be used to configure Django’s loggers. By default, it points at Python’s `logging.config.dictConfig()` function. However, if you want to use a different configuration process, you can use any other callable that takes a single argument. The contents of `LOGGING` will be provided as the value of that argument when logging is configured.

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