---
title: "Configuration et utilisation de la journalisation"
version: 4.1
locale: fr
source: https://docs.djangoproject.com/fr/4.1/howto/logging/
canonical: https://djangodocs.dev/fr/4.1/howto/logging/
---
# Configuration et utilisation de la journalisation

> **See also**
>
> - [Référence de la journalisation dans Django](/fr/4.1/ref/logging/#logging-ref)
> - [Aperçu de la journalisation dans Django](/fr/4.1/topics/logging/#logging-explanation)

Django contient une [configuration de journalisation par défaut](/fr/4.1/ref/logging/#default-logging-configuration) 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()`](https://docs.python.org/3/library/logging.html#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](#naming-loggers) 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`](https://docs.python.org/3/library/logging.html#logging.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](/fr/4.1/topics/logging/#topic-logging-parts-loggers): 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`](https://docs.python.org/3/library/logging.html#logging.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`](/fr/4.1/ref/settings/#std-setting-LOGGING) est le plus couramment utilisé. Ce réglage utilise le [format dictConfig](https://docs.python.org/3/library/logging.config.html#logging-config-dictschema), et étend la [configuration de journalisation par défaut](/fr/4.1/ref/logging/#default-logging-definition).

Consultez [Configuration de la journalisation](/fr/4.1/topics/logging/#configuring-logging) 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`](https://docs.python.org/3/library/logging.config.html#module-logging.config) 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`](https://docs.python.org/3/library/logging.handlers.html#logging.FileHandler) de Python pour enregistrer les journaux de niveau `DEBUG` et plus élevé dans le fichier `general.log` (à la racine du projet) :

```python
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`](/fr/4.1/ref/logging/#django.utils.log.AdminEmailHandler) fournie par Django et les diverses [`classes de gestionnaire`](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers) 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 :

```python
{
    '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 :

```python
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](#naming-loggers) 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`](https://docs.python.org/3/library/logging.html#logging.LogRecord). 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`:

```python
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()`](https://docs.python.org/3/library/stdtypes.html#str.format) ou `$` pour [`string.Template`](https://docs.python.org/3/library/string.html#string.Template); la valeur par défaut est `$`.

Voir [LogRecord attributes](https://docs.python.org/3/library/logging.html#logrecord-attributes) au sujet des attributs de [`LogRecord`](https://docs.python.org/3/library/logging.html#logging.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 :

```python
'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()`](https://docs.python.org/3/library/logging.html#logging.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 :

```python
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) :

```python
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.