Passer au contenu principal
LogBrew est une plateforme d’observabilité pour les développeurs et les agents de codage, avec une offre gratuite généreuse et sans carte bancaire. Ce guide couvre le logging Python avec le module standard logging, les 5 niveaux de log Python, la gestion des erreurs en Python et les types d’erreurs Python courants. Les dernières sections envoient les mêmes logs et plantages à LogBrew avec logbrew-sdk 0.1.29. Chaque exemple a tourné sous Python 3.13. Chaque bloc de sortie montre la sortie réelle. Pour une app Flask, utilisez plutôt Logging Flask. Ce guide ajoute les traces de requête à la même configuration de logging.

Écrire un premier log Python

Enregistrez ce fichier sous app.py. Appelez logging.basicConfig() une seule fois, au point d’entrée du programme. Récupérez un logger nommé dans chaque module.
Exécutez python3 app.py. La sortie va sur la sortie d’erreur standard.
L’enregistrement debug n’apparaît pas, car le niveau est INFO. logger.exception() écrit au niveau ERROR et ajoute le traceback. Appelez cette méthode uniquement dans un bloc except. Passez les valeurs en arguments, comme dans "payment retry %d of %d", 2, 3. Python construit le message seulement quand un handler accepte l’enregistrement. Le modèle de message reste identique à chaque nouvelle tentative. Vous pouvez donc le rechercher.

Niveaux de log Python

Un logger transmet un enregistrement seulement si le niveau de l’enregistrement est égal ou supérieur au niveau du logger. Un handler peut définir un second niveau, plus élevé. Le logger racine démarre à WARNING. Un nouveau logger a le niveau NOTSET (0) et utilise le niveau de son parent. Utilisez INFO en production, et DEBUG seulement en développement ou pour un diagnostic court.
La première ligne affiche les enregistrements de debug d’un module. La deuxième ligne supprime le bruit d’une bibliothèque.

Loggers, handlers et formatters

  • Un logger reçoit l’appel. Utilisez logging.getLogger(__name__) pour que le nom du logger suive le chemin du module.
  • Un handler envoie les enregistrements vers une destination, comme la console, un fichier ou LogBrew.
  • Un formatter transforme un enregistrement en texte.
Une bibliothèque ne doit pas configurer le logging. Elle ajoute seulement un logging.NullHandler() à son propre logger. L’application configure les handlers et les niveaux une seule fois. Pour une configuration importante, utilisez logging.config.dictConfig().

Gestion des erreurs en Python

Interceptez l’exception la plus précise que vous savez gérer. Utilisez else pour le code qui s’exécute seulement en cas de succès. Utilisez finally pour le code qui s’exécute toujours. Utilisez raise ... from error pour garder la cause d’origine. Enregistrez ce fichier sous orders.py.
La sortie montre les deux exceptions de la chaîne d’exceptions.
Suivez ces règles pour chaque exception.
  • Écrivez une exception dans les logs une seule fois, là où vous la gérez. Ne l’écrivez pas pour la relancer ensuite à chaque couche, car chaque couche ajoute un enregistrement en double.
  • N’écrivez pas except Exception: pass. Si vous ignorez une erreur, écrivez la raison dans les logs au niveau WARNING ou plus.
  • Interceptez Exception, pas BaseException. BaseException intercepte aussi KeyboardInterrupt et SystemExit, qui arrêtent le programme volontairement.
  • Définissez vos propres classes d’exception pour les erreurs que les appelants doivent gérer, comme le fait OrderError.

Signaler plusieurs erreurs

Python 3.11 et les versions plus récentes peuvent lever une ExceptionGroup. Utilisez-la quand une vérification trouve plusieurs anomalies. Gérez chaque type avec except*.

Types d’erreurs Python courants

Toutes les erreurs intégrées qu’un programme peut gérer héritent de Exception. Ce tableau liste les erreurs Python les plus fréquentes et la première vérification pour chacune. KeyboardInterrupt et SystemExit héritent de BaseException, pas de Exception. Ce ne sont pas des erreurs de votre code.

Envoyer les logs Python à LogBrew

LogBrewLoggingHandler est un handler de logging standard. Il envoie à LogBrew chaque enregistrement qu’il accepte. Le handler de console ne change pas.
1

Créer une clé de projet

Connectez-vous avec la CLI. Créez un projet et stockez sa clé d’ingestion dans un fichier lisible par son seul propriétaire.
La CLI n’affiche pas la clé. En production, utilisez le gestionnaire de secrets de votre plateforme.
2

Installer le SDK

Activez l’environnement virtuel de l’application. Installez ensuite le paquet. Il exige Python 3.10 ou plus récent.
3

Définir la clé et l’identité de déploiement

Le client ajoute le service, l’environnement et la version à chaque signal.
4

Ajouter le handler

Enregistrez ce fichier sous worker.py. Appelez logging.basicConfig() avant de créer le client. Le client ajoute un handler au logger racine. Or basicConfig() ne fait rien quand le logger racine a déjà un handler.
HttpTransport() envoie les signaux en arrière-plan, 1 seconde après le premier signal ou dès 50 signaux. client.shutdown() envoie les signaux restants et ferme le client.
5

Exécuter le programme

La sortie console ne change pas. LogBrew reçoit 1 log par enregistrement. Voici le premier signal, sans le contexte d’exécution partagé.
Les valeurs primitives de extra={...} deviennent des métadonnées. Le second signal a exceptionName KeyError et exceptionMessage 'seats'. Pour envoyer le texte complet du traceback, créez le handler avec include_exception_text=True.
6

Relire les logs

Une lecture qui renvoie ces logs montre que LogBrew les a stockés. Pour lire depuis la CI ou un agent de codage, utilisez une clé de lecture du projet. Consultez Vérifier la configuration.

Choisir les enregistrements envoyés à LogBrew

Donnez au handler son propre niveau pour envoyer moins d’enregistrements. La console reçoit toujours INFO et plus.
Les niveaux Python deviennent des niveaux LogBrew. Le nom et la valeur d’origine du niveau restent dans les métadonnées.

Signaler les plantages Python comme problèmes

install_process_error_capture(client) signale les exceptions non interceptées dans les scripts, les workers, le code de démarrage et les threads. Chaque plantage devient 1 problème avec le type d’exception, le message, les frames de pile et les causes chaînées. Python affiche toujours le traceback et s’arrête comme avant. Enregistrez ce fichier sous startup.py et exécutez-le.
LogBrew reçoit un problème avec le titre FileNotFoundError, le niveau critical et le mécanisme python.excepthook. Ses frames contiennent le nom du fichier, la ligne et la fonction, mais pas le chemin complet. Un plantage dans un thread a le niveau error. Avant l’arrêt de Python, le SDK attend au plus 2 secondes pour la livraison.
Le problème contient le message de l’exception. Ne mettez ni identifiants ni données personnelles dans les messages d’exception ou de log. Consultez Contrôler les données capturées.

Dépannage

Pour les applications web, consultez Logging Flask. Pour choisir un format de log, consultez Logs structurés. Pour les autres environnements d’exécution, consultez Intégration du SDK.