Sauveur du débogage ! Tirer parti d'ObjWatch pour une compréhension et un débogage efficaces du code dans des projets Python complexes

Lien vers le code source

aeeeeep / objwatch

?️ ObjWatch est une bibliothèque Python pour tracer et surveiller les attributs d'objet et les appels de méthode.

ObjWatch

[ Anglais | 中文 ]

Aperçu

ObjWatch est une bibliothèque Python robuste conçue pour rationaliser le débogage et la surveillance de projets complexes. En offrant un suivi en temps réel des attributs d'objet et des appels de méthode, ObjWatch permet aux développeurs d'obtenir des informations plus approfondies sur leurs bases de code, facilitant ainsi l'identification des problèmes, l'optimisation des performances et l'amélioration globale de la qualité du code.

⚠️ Avertissement de performances

ObjWatch peut avoir un impact sur les performances de votre application. Il est recommandé de l'utiliser uniquement dans des environnements de débogage.

Caractéristiques

• Traçage de structures imbriquées : visualisez et surveillez les appels de fonctions imbriquées et les interactions d'objets avec une journalisation claire et hiérarchique.

• Prise en charge améliorée de la journalisation : exploitez le module de journalisation intégré de Python pour des sorties de journaux structurées et personnalisables, y compris la prise en charge de formats simples et détaillés. De plus, pour garantir que les journaux sont capturés même si l'enregistreur est désactivé ou supprimé par des bibliothèques externes, vous pouvez définir level="force". Lorsque le niveau est défini sur "force", ObjWatch contourne les gestionnaires de journalisation standard et utilise print() pour…

Voir sur GitHub

Problèmes de débogage actuels

Lors de la lecture et du débogage de projets complexes, il est courant de rencontrer des appels imbriqués comportant jusqu'à une douzaine de couches, ce qui rend difficile la détermination de l'ordre d'exécution. L'aspect le plus frustrant est le débogage dans un environnement multi-processus ; le débogage d'un seul processus entraîne souvent l'attente et l'expiration des autres processus, ce qui nécessite un redémarrage constant du programme de débogage. L'utilisation d'instructions print entraîne fréquemment des appels de fonction manqués, ce qui prend du temps et est laborieux. Actuellement, il n'existe pas de bibliothèque de débogage alliant simplicité et exhaustivité, j'ai donc passé un week-end à développer un outil qui résout ce problème.

Qu’est-ce qu’ObjWatch ?

ObjWatch est spécialement conçu pour simplifier le débogage et la surveillance de projets complexes. Il fournit un suivi en temps réel des propriétés des objets et des appels de méthodes, et permet des hooks personnalisés pour aider les développeurs à mieux comprendre la base de code.

Exemple d'utilisation rapide

Vous pouvez l'installer directement en utilisant pip install objwatch. À des fins de démonstration, vous devez cloner le code source :

git clone https://github.com/aeeeeeep/objwatch
cd objwatch
pip install .
python3 examples/example_usage.py

L'exécution du code ci-dessus produira les informations d'appel suivantes :

[2025-01-04 19:15:13] [DEBUG] objwatch: Processed targets:
>>>>>>>>>>
examples/example_usage.py
<<<<<<<<<<
[2025-01-04 19:15:13] [WARNING] objwatch: wrapper 'BaseLogger' loaded
[2025-01-04 19:15:13] [INFO] objwatch: Starting ObjWatch tracing.
[2025-01-04 19:15:13] [INFO] objwatch: Starting tracing.
[2025-01-04 19:15:13] [DEBUG] objwatch: run main <-
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.__init__ <- '0':(type)SampleClass, '1':10
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.__init__ -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.increment <- '0':(type)SampleClass
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value None -> 10
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value 10 -> 11
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.increment -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.increment <- '0':(type)SampleClass
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value 11 -> 12
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.increment -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.increment <- '0':(type)SampleClass
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value 12 -> 13
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.increment -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.increment <- '0':(type)SampleClass
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value 13 -> 14
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.increment -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.increment <- '0':(type)SampleClass
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value 14 -> 15
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.increment -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.decrement <- '0':(type)SampleClass
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value 15 -> 14
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.decrement -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.decrement <- '0':(type)SampleClass
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value 14 -> 13
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.decrement -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: | run SampleClass.decrement <- '0':(type)SampleClass
[2025-01-04 19:15:13] [DEBUG] objwatch: | | upd SampleClass.value 13 -> 12
[2025-01-04 19:15:13] [DEBUG] objwatch: | end SampleClass.decrement -> None
[2025-01-04 19:15:13] [DEBUG] objwatch: end main -> None
[2025-01-04 19:15:13] [INFO] objwatch: Stopping ObjWatch tracing.
[2025-01-04 19:15:13] [INFO] objwatch: Stopping tracing.

La partie la plus cruciale du code est la suivante :

# Using as a Context Manager with Detailed Logging
with objwatch.ObjWatch(['examples/example_usage.py']):
    main()

# Using the API with Simple Logging
obj_watch = objwatch.watch(['examples/example_usage.py'])
main()
obj_watch.stop()

Nous pouvons utiliser l'outil à la fois via un gestionnaire de contexte et via des appels API. Dans l'exemple, nous spécifions le suivi du fichier examples/example_usage.py, ce qui signifie que toute fonction, méthode ou variable dans examples/example_usage.py sera enregistrée par l'outil. Cette journalisation claire et hiérarchique permet de visualiser et de surveiller les appels de fonctions imbriqués et les interactions d'objets. Les journaux imprimés incluent les types d'exécution suivants :

• run : Indique le début de l'exécution d'une fonction ou d'une méthode de classe.
• end : Signifie la fin de l'exécution d'une fonction ou d'une méthode de classe.
• upd : Représente la création d'une nouvelle variable.
• apd : désigne l'ajout d'éléments à des structures de données telles que des listes, des ensembles ou des dictionnaires.
• pop : marque la suppression d'éléments des structures de données telles que des listes, des ensembles ou des dictionnaires.

L'exemple est relativement simple, mais cette fonctionnalité sera extrêmement utile pour exécuter des projets à grande échelle.

Caractéristiques générales

ObjWatch propose les interfaces suivantes :

• cibles (liste) : Fichiers ou modules à surveiller.
• include_targets (liste, facultatif) : fichiers ou modules à exclure de la surveillance.
• rangs (liste, facultatif) : classements GPU à suivre lors de l'utilisation de torch.distributed.
• sortie (str, facultatif) : chemin d'accès à un fichier pour l'écriture des journaux.
• output_xml (str, facultatif) : chemin d'accès au fichier XML pour l'écriture des journaux structurés. Si spécifié, les informations de traçage seront enregistrées dans un format XML imbriqué pour une navigation et une analyse faciles.
• level (str, facultatif) : niveau de journalisation (par exemple, logging.DEBUG, logging.INFO, force, etc.).
• simple (bool, facultatif) : Activez le mode de journalisation simple au format "DEBUG : {msg}".
• wrapper (FunctionWrapper, facultatif) : wrapper personnalisé pour étendre les fonctionnalités de traçage et de journalisation.
• with_locals (bool, facultatif) : Activer le traçage et la journalisation des variables locales dans les fonctions pendant leur exécution.
• with_module_path (bool, facultatif) : contrôlez s'il faut ajouter le chemin du module aux noms de fonctions dans les journaux.

Fonctionnalité clé : extensions de wrapper personnalisées

ObjWatch fournit la classe de base abstraite FunctionWrapper, permettant aux utilisateurs de créer des wrappers personnalisés pour étendre et personnaliser les fonctionnalités de suivi et de journalisation de la bibliothèque. En héritant de FunctionWrapper, les développeurs peuvent mettre en œuvre des comportements personnalisés adaptés aux exigences spécifiques du projet. Ces comportements seront exécutés lors des appels et des retours de fonctions, offrant ainsi un suivi plus professionnel.

Classe FunctionWrapper

La classe FunctionWrapper définit deux méthodes principales qui doivent être implémentées :

• wrap_call(self, func_name : str, frame : FrameType) -> str :

Cette méthode est invoquée au début d’un appel de fonction. Il reçoit le nom de la fonction et l'objet frame actuel, qui contient le contexte d'exécution, y compris les variables locales et la pile d'appels. Implémentez cette méthode pour extraire, enregistrer ou modifier les informations avant l'exécution de la fonction.

• wrap_return(self, func_name : str, résultat : Any) -> str :

Cette méthode est appelée lors du retour d'une fonction. Il reçoit le nom de la fonction et le résultat renvoyé par la fonction. Utilisez cette méthode pour enregistrer, analyser ou modifier les informations une fois l'exécution de la fonction terminée.

• wrap_upd(self, old_value : Any, current_value : Any) -> Tuple[str, str] :

Cette méthode est déclenchée lorsqu'une variable est mise à jour, recevant l'ancienne valeur et la valeur actuelle. Il peut être utilisé pour enregistrer les modifications apportées aux variables, permettant ainsi le suivi et le débogage des transitions d'état des variables.

Pour plus de détails sur les objets frame, reportez-vous à la documentation officielle de Python.

TensorShapeLogger

Ceci est un exemple de wrapper personnalisé que j'ai implémenté en fonction de mon scénario d'utilisation. Le code se trouve dans le fichier objwatch/wrappers.py. Ce wrapper enregistre automatiquement les formes tensorielles des entrées et des sorties dans tous les appels de méthode de fonction au sein du module spécifié, ainsi que les états des variables. Ceci est extrêmement utile pour comprendre la logique d'exécution de frameworks distribués complexes.

git clone https://github.com/aeeeeeep/objwatch
cd objwatch
pip install .
python3 examples/example_usage.py

Dans les projets d'apprentissage profond, la forme et les dimensions des tenseurs sont cruciales. Une petite erreur de dimension peut empêcher l’ensemble du modèle de s’entraîner ou de prédire correctement. Vérifier manuellement la forme de chaque tenseur est fastidieux et sujet aux erreurs. Le TensorShapeLogger automatise l'enregistrement des formes tensorielles, aidant ainsi les développeurs à :

• Identifiez rapidement les problèmes de non-concordance des dimensions : enregistre automatiquement les informations de forme pour détecter et corriger rapidement les erreurs de dimension.
• Optimiser l'architecture du modèle : en suivant les changements dans les formes des tenseurs, optimisez la structure du réseau pour améliorer les performances du modèle.
• Augmentez l'efficacité du débogage : réduisez le temps passé à vérifier manuellement les formes de tenseurs, ce qui permet de se concentrer sur le développement du modèle de base.

Exemple d'utilisation d'un wrapper personnalisé

Il est recommandé de se référer au fichier tests/test_torch_train.py. Ce fichier contient un exemple complet d'un processus de formation PyTorch, démontrant comment intégrer ObjWatch pour la surveillance et la journalisation.

Remarques

⚠️ Avertissement de performances
ObjWatch peut avoir un impact sur les performances de votre programme lorsqu'il est utilisé dans un environnement de débogage. Par conséquent, il est recommandé de l'utiliser uniquement pendant les phases de débogage et de développement.

Ceci n'est qu'un premier article ; Je prévois d'en ajouter d'autres au fil du temps. Si vous le trouvez utile, n'hésitez pas à lui donner une étoile.

La bibliothèque est toujours activement mise à jour. Si vous avez des questions ou des suggestions, veuillez laisser un commentaire ou ouvrir un ticket dans le référentiel.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!