ソースコードリンク

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

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

オブジェクトウォッチ

Debugging Savior! Leveraging ObjWatch for Efficient Code Comprehension and Debugging in Complex Python Projects

[英語 | 中文 ]

概要

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.
出力 (文字列、オプション): ログを書き込むためのファイルへのパス。
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 はテンソル形状の記録を自動化し、開発者が次のことを行えるようにします。

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