原始碼連結

當前調試痛點

在讀取和調試複雜項目時，經常會遇到多達十幾層的嵌套調用，導致難以確定執行順序。最令人沮喪的方面是在多進程環境中進行偵錯；調試單一進程常常會導致其他進程等待並逾時，需要不斷重新啟動偵錯程式。頻繁使用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 呼叫來使用該工具。在範例中，我們指定對examples/example_usage.py 檔案進行跟踪，這表示工具將記錄examples/example_usage.py 中的任何函數、方法或變數。這種清晰的分層日誌記錄有助於視覺化和監視巢狀函數呼叫和物件互動。列印的日誌包括以下幾個執行類型：

• run：表示函數或類別方法執行的開始。
• end：表示函數或類別方法執行結束。
• upd：代表建立一個新變數。
• apd：表示為清單、集合或字典等資料結構新增元素。
• pop：標記從資料結構（如清單、集合或字典）​​中刪除元素。

範例相對簡單，但此功能對於執行大型專案非常有用。

整體特點

ObjWatch 提供以下介面：

• 目標（清單）：要監視的檔案或模組。
• except_targets（列表，可選）：要從監視中排除的檔案或模組。
• ranks（列表，可選）：使用 torch.distributed 時要追蹤的 GPU 排名。
• 輸出（str，可選）：用於寫入日誌的檔案的路徑。
• output_xml（str，可選）：用於寫入結構化日誌的 XML 檔案的路徑。如果指定，追蹤資訊將以巢狀 XML 格式儲存，以便於瀏覽和分析。
• level (str, 可選): 日誌記錄等級(例如logging.DEBUG、logging.INFO、force等)。
• simple (bool, 可選): 啟用簡單日誌記錄模式，格式為「DEBUG: {msg}」。
• 包裝器（FunctionWrapper，可選）：自訂包裝器以擴展追蹤和日誌記錄功能。
• with_locals（bool，可選）：在函數執行期間啟用函數內局部變數的追蹤和記錄。
• with_module_path (bool, 可選): 控制是否在日誌中的函式名稱前面新增模組路徑。

主要功能：自訂包裝擴展

ObjWatch 提供了 FunctionWrapper 抽象基類，允許使用者建立自訂包裝器來擴展和自訂庫的追蹤和日誌記錄功能。透過繼承FunctionWrapper，開發人員可以實現針對特定專案需求的客製化行為。這些行為會在函數呼叫和返回時執行，提供更專業的監控。

函數包裝類

FunctionWrapper 類別定義了兩個必須實作的核心方法：

• wrap_call（self，func_name：str，frame：FrameType）-> str:

該方法在函數呼叫開始時被呼叫。它接收函數名稱和當前幀對象，其中包含執行上下文，包括局部變數和呼叫堆疊。實現此方法以在函數執行之前提取、記錄或修改資訊。

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

此方法在函數傳回時呼叫。它接收函數名稱和函數傳回的結果。使用此方法在函數完成執行後記錄、分析或變更資訊。

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

當變數更新時會觸發方法，接收舊值和目前值。它可用於記錄變數的更改，從而允許追蹤和調試變數狀態轉換。

有關框架物件的更多詳細信息，請參閱Python官方文件。

張量形狀記錄器

這是我根據我的使用場景實現的自訂包裝器的範例。程式碼位於 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 會影響程式的效能。因此，建議僅在調試和開發階段使用它。

這只是初步的寫作；我計劃隨著時間的推移添加更多。如果您覺得有用，請隨意給它一個star。

該庫仍在積極更新中。如果您有任何問題或建議，請發表評論或在儲存庫中開啟問題。

以上是調試救星！利用 ObjWatch 在複雜的 Python 專案中進行高效的程式碼理解和調試的詳細內容。更多資訊請關注PHP中文網其他相關文章！