デバッグの救世主！ ObjWatch を活用して複雑な Python プロジェクトの効率的なコード理解とデバッグを行う

ソースコードリンク

ああああ / オブジェウォッチ

?️ ObjWatch は、オブジェクトの属性とメソッド呼び出しをトレースおよび監視するための Python ライブラリです。

オブジェクトウォッチ

[英語 | 中文 ]

概要

ObjWatch は、複雑なプロジェクトのデバッグと監視を合理化するために設計された堅牢な Python ライブラリです。 ObjWatch は、オブジェクト属性とメソッド呼び出しのリアルタイム トレースを提供することで、開発者がコードベースについてより深い洞察を得ることができるようにし、問題の特定、パフォーマンスの最適化、全体的なコード品質の向上を促進します。

⚠️ パフォーマンスに関する警告

ObjWatch はアプリケーションのパフォーマンスに影響を与える可能性があります。デバッグ環境でのみ使用することをお勧めします。

特徴

• ネストされた構造のトレース: 明確な階層ログを使用して、ネストされた関数呼び出しとオブジェクトの相互作用を視覚化して監視します。

• 強化されたログ サポート: Python の組み込みログ モジュールを活用して、単純で詳細な形式のサポートを含む、構造化されたカスタマイズ可能なログ出力を実現します。さらに、ロガーが無効になっているか、外部ライブラリによって削除されている場合でも、ログが確実にキャプチャされるように、level="force" を設定できます。レベルが「force」に設定されている場合、ObjWatch は標準のロギング ハンドラーをバイパスし、print() を使用して…

GitHub で表示

現在のデバッグの問題点

複雑なプロジェクトを読み取ってデバッグする場合、最大 12 層のネストされた呼び出しが発生することがよくあり、実行順序を決定することが困難になります。最もイライラするのは、マルチプロセス環境でのデバッグです。単一のプロセスをデバッグすると、多くの場合、他のプロセスが待機してタイムアウトになり、デバッグ プログラムを常に再起動する必要があります。 print ステートメントを使用すると関数呼び出しが失われることが多く、時間と労力がかかります。現在のところ、シンプルさと包括性を兼ね備えたデバッグ ライブラリは存在しないため、私は週末を費やしてこの問題点に対処するツールを開発しました。

ObjWatchとは何ですか?

ObjWatch は、複雑なプロジェクトのデバッグと監視を簡素化するために特別に設計されています。これにより、オブジェクト プロパティとメソッド呼び出しのリアルタイム追跡が可能になり、開発者がコードベースについてより深い洞察を得るのに役立つカスタム フックが可能になります。

簡単な使用例

pip install objwatch を使用して直接インストールできます。デモンストレーションの目的で、ソース コードのクローンを作成する必要があります:

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

上記のコードを実行すると、次の呼び出し情報が生成されます:

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

コードの最も重要な部分は次のとおりです:

# 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()

このツールは、コンテキスト マネージャーと API 呼び出しの両方で使用できます。この例では、example_usage.py ファイルの追跡を指定しています。これは、example_usage.py 内の関数、メソッド、または変数がツールによってログに記録されることを意味します。この明確な階層ログは、入れ子になった関数呼び出しとオブジェクトの相互作用を視覚化し、監視するのに役立ちます。出力されるログには、次の種類の実行が含まれます:

• run: 関数またはクラス メソッドの実行の開始を示します。
• end: 関数またはクラス メソッドの実行の終了を示します。
• upd: 新しい変数の作成を表します。
• apd: リスト、セット、辞書などのデータ構造への要素の追加を示します。
• pop: リスト、セット、辞書などのデータ構造からの要素の削除をマークします。

この例は比較的単純ですが、この機能は大規模なプロジェクトを実行する場合に非常に役立ちます。

全体的な特徴

ObjWatch は次のインターフェイスを提供します:

• ターゲット (リスト): 監視するファイルまたはモジュール。
• exclude_targets (リスト、オプション): 監視から除外するファイルまたはモジュール。
• ランク (リスト、オプション): torch.distributed.
を使用するときに追跡する GPU ランク。
• 出力 (文字列、オプション): ログを書き込むためのファイルへのパス。
• Output_xml (文字列、オプション): 構造化ログを書き込むための XML ファイルへのパス。指定した場合、トレース情報はネストされた XML 形式で保存され、簡単に参照および分析できるようになります。
• level (str、オプション): ログレベル (logging.DEBUG、logging.INFO、force など)。
• simple (bool、オプション): "DEBUG: {msg}" という形式で簡易ロギング モードを有効にします。
• ラッパー (FunctionWrapper、オプション): トレースおよびロギング機能を拡張するためのカスタム ラッパー。
• with_locals (ブール値、オプション): 実行中の関数内のローカル変数のトレースとロギングを有効にします。
• with_module_path (ブール値、オプション): ログ内の関数名の先頭にモジュール パスを追加するかどうかを制御します。

主な機能: カスタム ラッパー拡張機能

ObjWatch は FunctionWrapper 抽象基本クラスを提供し、ユーザーがカスタム ラッパーを作成してライブラリの追跡およびログ機能を拡張およびカスタマイズできるようにします。 FunctionWrapper から継承することにより、開発者は特定のプロジェクト要件に合わせてカスタマイズされた動作を実装できます。これらの動作は関数の呼び出し時と戻り時に実行され、より専門的な監視が可能になります。

FunctionWrapper クラス

FunctionWrapper クラスは、実装する必要がある 2 つのコア メソッドを定義します。

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

このメソッドは関数呼び出しの開始時に呼び出されます。これは、関数名と、ローカル変数や呼び出しスタックを含む実行コンテキストを含む現在のフレーム オブジェクトを受け取ります。関数を実行する前に情報を抽出、記録、または変更するには、このメソッドを実装します。

• wrap_return(self, func_name: str, result: Any) -> str:

このメソッドは関数が返されたときに呼び出されます。関数名と関数から返された結果を受け取ります。関数の実行完了後に情報をログ、分析、または変更するには、このメソッドを使用します。

• wrap_upd(self, old_value: 任意、current_value: 任意) ->タプル[str, str]:

このメソッドは、変数が更新されるときにトリガーされ、古い値と現在の値を受け取ります。これを使用して変数への変更をログに記録し、変数の状態遷移の追跡とデバッグが可能になります。

フレーム オブジェクトの詳細については、Python の公式ドキュメントを参照してください。

TensorShapeLogger

これは、私の使用シナリオに基づいて実装したカスタム ラッパーの例です。コードは objwatch/wrappers.py ファイルにあります。このラッパーは、指定されたモジュール内のすべての関数メソッド呼び出しの入力と出力のテンソル形状と変数の状態を自動的に記録します。これは、複雑な分散フレームワークの実行ロジックを理解するのに非常に役立ちます。

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

深層学習プロジェクトでは、テンソルの形状と次元が重要です。寸法誤差が小さいと、モデル全体が正しくトレーニングまたは予測できなくなる可能性があります。各テンソルの形状を手動で確認するのは面倒で、エラーが発生しやすくなります。 TensorShapeLogger はテンソル形状の記録を自動化し、開発者が次のことを行えるようにします。

• 寸法の不一致の問題を迅速に特定: 形状情報を自動的に記録し、寸法エラーを迅速に検出して修正します。
• モデル アーキテクチャの最適化: テンソル形状の変化を追跡することで、ネットワーク構造を最適化し、モデルのパフォーマンスを向上させます。
• デバッグ効率の向上: テンソル形状の手動チェックに費やす時間を削減し、コア モデルの開発に集中できるようにします。

カスタムラッパーの使用例

tests/test_torch_train.py ファイルを参照することをお勧めします。このファイルには、PyTorch トレーニング プロセスの完全な例が含まれており、監視とログ記録のために ObjWatch を統合する方法を示しています。

注意事項

⚠️パフォーマンスに関する警告
ObjWatch をデバッグ環境で使用すると、プログラムのパフォーマンスに影響を与える可能性があります。したがって、デバッグ段階と開発段階でのみ使用することをお勧めします。

これは単なる最初の記事です。時間をかけてさらに追加する予定です。役立つと思われた場合は、お気軽にスターを付けてください。

ライブラリは現在も積極的に更新されています。ご質問やご提案がございましたら、コメントを残すか、リポジトリで問題を開いてください。

以上がデバッグの救世主！ ObjWatch を活用して複雑な Python プロジェクトの効率的なコード理解とデバッグを行うの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。