← Blog
Un enregistreur lavande avec un rouleau de papier ivoire et un bouton orange sur fond lavande pâle.
Publié le
2026-11-17

Python logging : niveaux, handlers et journaux utiles

Le module logging de Python permet de retrouver les actions d'une application, l'opération qui a échoué et le contexte nécessaire pour comprendre le problème. Commencez par un logger nommé et un seuil de gravité explicite. Ajoutez des champs structurés lorsque vous devez retrouver tous les événements d'un traitement ou d'une requête. Le but est de disposer d'une trace courte et exploitable en cas d'incident.

Ce guide construit un petit exemple avec la bibliothèque standard de Python. Il couvre les niveaux, les handlers, la sortie JSON, les exceptions et les messages en double, avec un traitement par lots qui échoue volontairement. Les exemples ont été testés avec Python 3.12.14.

Commencer par un logger nommé

Enregistrez le code suivant dans basic_example.py, puis lancez python basic_example.py. Aucun paquet supplémentaire n'est nécessaire.

import logging

logger = logging.getLogger(__name__)

if __name__ == "__main__":
    logging.basicConfig(
        level=logging.INFO,
        format="%(levelname)s %(name)s %(message)s",
    )
    logger.debug("Detailed input inspection")
    logger.info("Processed %s rows", 3)

La sortie observée est INFO __main__ Processed 3 rows sur la sortie d'erreur standard. L'événement de débogage est filtré. Un logger créé avec __name__ reprend le nom du module lorsqu'il est importé ; un script exécuté directement utilise __main__. Cette identité permet de distinguer votre traitement d'un client HTTP ou d'une bibliothèque de base de données.

Utilisez print() pour le résultat demandé par l'utilisateur d'un outil en ligne de commande, par exemple des données exportées. Utilisez logging pour les événements de fonctionnement qui entourent ce résultat. Le guide Python sur la journalisation explique cette distinction et les niveaux de gravité standard.

Choisir des niveaux qui décrivent le résultat

Choisissez le niveau selon ce qui est arrivé à l'opération. Un rejet de validation attendu peut justifier un événement informatif dans un service, mais constituer une erreur dans un import nocturne censé réussir. Appliquez une règle cohérente dans toute l'application.

NiveauExemple dans un traitement par lotsQuestion à résoudre
DEBUGUn point de contrôle détaillé pour diagnostiquer l'analyse des donnéesQue s'est-il passé dans cette étape ?
INFOUn traitement a commencé ou s'est terminéLe travail attendu avance-t-il ?
WARNINGUne nouvelle tentative a été nécessaire, mais le traitement peut continuerCette situation demande-t-elle une intervention ?
ERRORUn traitement a échoué sans produire de résultat exploitableQuelle opération faut-il reprendre ?
CRITICALLe service ne peut pas initialiser un composant indispensableCe processus peut-il encore remplir son rôle ?

Dans le premier exemple, le seuil INFO inclut les événements informatifs et les niveaux supérieurs. Un petit traitement a généralement besoin d'un événement de démarrage, d'un résultat final et du contexte qui les relie. Consigner chaque ligne de données complique la recherche des événements importants et augmente le volume stocké. Ajoutez des détails pour une investigation précise, puis réduisez-les.

Configurer les handlers et la sortie JSON au démarrage

Le logger crée un événement. Un handler l'envoie vers une destination. Un formatter définit sa représentation. Ici, un handler associé au logger racine écrit du JSON sur la sortie standard. Le logger du module lui transmet ses événements par propagation. Les deux seuils sont explicites. Un logger enfant configuré séparément doit toujours franchir le seuil du handler.

Enregistrez ce code dans logging_demo.py. Exécutez-le séparément du premier script avec python logging_demo.py.

import json
import logging
from datetime import datetime, timezone
from logging.config import dictConfig

logger = logging.getLogger(__name__)


class JsonFormatter(logging.Formatter):
    def format(self, record):
        event = {
            "time": datetime.fromtimestamp(
                record.created, timezone.utc
            ).isoformat(timespec="milliseconds"),
            "level": record.levelname,
            "logger": record.name,
            "message": record.getMessage(),
        }
        for key, expected_type in (("job_id", str), ("rows", int)):
            value = getattr(record, key, None)
            if type(value) is expected_type:
                event[key] = value
        if record.exc_info:
            event["exception"] = self.formatException(record.exc_info)
        return json.dumps(event, ensure_ascii=True)


def configure_logging(level="INFO"):
    # Application startup only: this replaces logging configuration.
    dictConfig({
        "version": 1,
        "disable_existing_loggers": False,
        "formatters": {"json": {"()": JsonFormatter}},
        "handlers": {
            "console": {
                "class": "logging.StreamHandler",
                "stream": "ext://sys.stdout",
                "formatter": "json",
                "level": level,
            }
        },
        "root": {"handlers": ["console"], "level": level},
    })


def run_demo():
    context = {"job_id": "job-17"}
    logger.debug("Inspecting fixture")
    logger.info("Job started", extra=context)
    rows = ["12", "7", "invalid"]
    try:
        values = [int(row) for row in rows]
    except ValueError:
        logger.exception("Job rejected", extra=context)
        return 1
    logger.info("Job completed", extra={**context, "rows": len(values)})
    return 0


if __name__ == "__main__":
    configure_logging()
    raise SystemExit(run_demo())

L'exemple échoue volontairement lors de la conversion de invalid. Notre exécution a produit deux lignes JSON : un événement INFO portant le message Job started, puis un événement ERROR avec Job rejected, le même job_id et la trace d'une exception ValueError. Le processus s'est terminé avec le code 1. Le message de débogage et l'événement de réussite étaient absents.

Chaque enregistrement contient une date en UTC, la gravité, le nom du logger et le message. Les champs facultatifs job_id et rows ne sont inclus que si leur type correspond à celui attendu. Le formatter échappe les sauts de ligne : la trace de l'exception tient dans une seule ligne JSON physique. Un outil de lecture peut ensuite l'afficher sur plusieurs lignes.

dictConfig rassemble les relations entre handlers et formatters. Appelez cette configuration au démarrage de l'application, avant le début du travail. La répéter dans notre test isolé n'a laissé qu'un handler racine, mais elle remplace la configuration de journalisation. Elle ne convient donc pas à une action exécutée à l'import d'une bibliothèque réutilisable. Le paramètre disable_existing_loggers=False ne garantit ni la disparition des handlers tiers, ni la conservation intacte de leur configuration.

Consigner les exceptions sans masquer l'échec

Dans un bloc de gestion d'exception, logger.exception() enregistre une erreur avec sa trace. L'exemple l'appelle au moment où le traitement est rejeté et renvoie un code de sortie signalant l'échec. La journalisation ne relance pas une tâche, n'annule pas des écritures partielles et n'informe pas, à elle seule, l'ordonnanceur de l'échec. Définissez ces comportements séparément.

Désignez l'endroit responsable de l'événement d'échec. Si une fonction consigne une exception puis la relance, et que son appelant la consigne à nouveau, deux enregistrements peuvent décrire le même incident malgré des handlers bien configurés. Une organisation utile consiste à laisser les fonctions internes lever les erreurs, puis à consigner le résultat à la limite du traitement ou de la requête, avec son identifiant.

Dans l'exemple, job-17 relie le démarrage au rejet. Dans un service réel, choisissez un identifiant non sensible qui reste stable entre les nouvelles tentatives. Distinguez le résultat du traitement du texte de diagnostic : l'écriture réussie d'un message ne prouve pas que l'import des données a réussi.

Choisir les champs structurés avec soin

Le formatter JSON construit un petit dictionnaire de sortie au lieu de sérialiser tous les attributs de l'enregistrement. Nos tests ont fourni, via extra, des champs contenant une clé API, un mot de passe et un contenu sensible fictifs. Aucun n'est apparu dans le JSON produit. L'absence de contexte facultatif et les champs de type incorrect n'ont pas non plus empêché l'émission de l'événement.

Cette liste de champs autorisés a une limite précise. Le formatter écrit toujours le message et le texte de l'exception. Un autre test a volontairement placé des secrets fictifs dans ces deux emplacements : ils sont restés visibles. Le champ autorisé job_id pourrait lui aussi contenir des informations sensibles fournies par l'appelant. Cet exemple montre une sélection de champs, pas un système général de masquage.

Évitez de transmettre aux appels de journalisation des identifiants de connexion, des en-têtes d'autorisation, des corps de requête bruts ou des données personnelles. Examinez les messages d'erreur des bibliothèques avant de les envoyer vers une destination partagée. Définissez les droits de lecture et la durée de conservation. Testez ces choix avec des données fictives représentatives avant de collecter du trafic réel.

Un formatter textuel contenant %(job_id)s exige ce champ dans chaque enregistrement qu'il traite. Nous avons reproduit une erreur de formatage lorsque ce champ manquait. L'exemple JSON évite cette dépendance en vérifiant chaque champ facultatif. N'utilisez pas un nom réservé comme message pour le contexte personnalisé.

Corriger les messages en double ou manquants

Notre test de duplication a ajouté un handler au logger enfant tout en conservant celui du logger racine. Un appel a produit deux enregistrements. Le retrait du handler enfant a rétabli une seule sortie. La référence du module logging explique la propagation et la répétition possible d'un événement lorsque plusieurs niveaux de la hiérarchie possèdent un handler.

SymptômePremière vérificationCorrection utile
Un appel produit deux enregistrements identiquesPrésence de handlers sur l'enfant et sur un ancêtreChoisir un seul chemin de sortie, généralement celui du logger racine
Les événements INFO restent absentsNiveau effectif du logger et niveau du handlerDéfinir explicitement les deux seuils
Une modification de basicConfig semble sans effetPrésence de handlers racine déjà configurésExaminer la configuration existante de l'application
Seuls les enregistrements sans contexte disparaissentChamps obligatoires du formatterFournir des valeurs par défaut ou rendre les champs facultatifs
La sortie existe localement, mais pas dans le collecteurFlux choisi et configuration du collecteurSuivre un événement connu à chaque étape

Par défaut, basicConfig() ne modifie pas un logger racine déjà configuré. L'option force=True retire et ferme ses handlers existants. Réservez-la aux cas où votre application maîtrise la configuration : elle peut perturber un notebook, un outil de test ou un environnement d'hébergement. Pour un logger volontairement indépendant qui possède son propre handler, désactiver la propagation peut convenir. Sans destination fonctionnelle, cela risque au contraire de masquer des événements.

Choisir la destination des journaux

La sortie standard constitue un point de départ pratique pour ce traitement, car le gestionnaire de processus peut la capturer. Notre exemple JSON l'utilise explicitement ; le premier exemple écrit sur la sortie d'erreur standard. Si une commande réserve sa sortie standard à des résultats destinés à un autre programme, envoyez les événements de fonctionnement sur la sortie d'erreur ou vers une autre destination.

Dans un conteneur, le guide Docker logs, en anglais explique comment récupérer la sortie et configurer sa conservation. Pour un fichier local, la bibliothèque standard propose des handlers avec rotation des fichiers. La rotation demande une règle de taille ou de durée et une limite de conservation ; elle ne fournit ni sauvegarde ni service d'alerte.

Cet exemple utilise un seul processus. Ne le copiez pas dans plusieurs processus avec un handler indépendant écrivant dans le même fichier : cette organisation n'est pas prise en charge par l'implémentation standard de logging. Le recueil de recettes Python décrit une organisation avec une file et un seul composant chargé de l'écriture. Nous ne l'avons ni implémentée ni testée ici. Pour la question distincte de la répartition du travail sur CPU, consultez le guide Python multiprocessing.

Vérifier le comportement avant une exécution continue

La suite locale a réussi 16 tests avec Python 3.12.14. Elle a vérifié les seuils de gravité, la configuration répétée, le contexte des exceptions, les champs facultatifs, l'analyse du JSON, Unicode et les sauts de ligne, une duplication de handler suivie de sa correction, ainsi que les limites volontaires de la sélection des champs. Elle a également exécuté les deux scripts dans des processus distincts et contrôlé le code de sortie du traitement en échec.

Ces vérifications portent sur l'application. Elles ne testent pas la livraison des journaux pendant une panne, des processus de travail concurrents, la rotation sur disque, les performances d'un collecteur ou un déploiement cloud. Avant de laisser fonctionner un service, vérifiez qu'un événement connu arrive à sa destination finale et qu'un disque plein ou un collecteur indisponible a un effet acceptable sur l'application.

Une fois l'application observable localement, choisissez son mode d'exploitation. Notre comparatif des hébergements d'API, en anglais précise les responsabilités associées à une VM, à une plateforme gérée et au serverless. Compute avec Hivenet, page en anglais fournit une infrastructure CPU pour les applications et les traitements ; le guide vCPU présente les configurations d'instances. Sur une VM que vous exploitez, prévoyez la supervision de l'application, la collecte des journaux, leur conservation et les alertes.

Votre prochaine charge de travail sur Hivenet.

Choisissez une charge de travail d’IA, de calcul ou de stockage à tester sur Hivenet, ou échangez avec notre équipe sur sa mise en production.