原始碼連結(jié)

當前調(diào)試痛點

在讀取和調(diào)試複雜項目時，經(jīng)常會遇到多達十幾層的嵌套調(diào)用，導(dǎo)致難以確定執(zhí)行順序。最令人沮喪的方面是在多進程環(huán)境中進行偵錯；調(diào)試單一進程常常會導(dǎo)致其他進程等待並逾時，需要不斷重新啟動偵錯程式。頻繁使用print語句會導(dǎo)致錯過函數(shù)調(diào)用，費時費力。目前還沒有一個兼具簡單性和全面性的調(diào)試庫，所以我花了一個週末開發(fā)了一個工具來解決這個痛點。

什麼是 ObjWatch？

ObjWatch 專為簡化複雜專案的調(diào)試和監(jiān)控而設(shè)計。它提供物件屬性和方法呼叫的即時追蹤，並允許自訂掛鉤來幫助開發(fā)人員更深入地了解程式碼庫。

快速使用範例

您可以直接使用 pip install objwatch 安裝它。為了演示目的，您需要克隆原始程式碼：

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

執(zhí)行上述程式碼會產(chǎn)生以下呼叫資訊：

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

程式碼中最關(guān)鍵的部分如下：

# 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 中的任何函數(shù)、方法或變數(shù)。這種清晰的分層日誌記錄有助於視覺化和監(jiān)視巢狀函數(shù)呼叫和物件互動。列印的日誌包括以下幾個執(zhí)行類型：

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

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

整體特點

ObjWatch 提供以下介面：

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

主要功能：自訂包裝擴展

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

函數(shù)包裝類

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

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

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

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

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

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

當變數(shù)更新時會觸發(fā)方法，接收舊值和目前值。它可用於記錄變數(shù)的更改，從而允許追蹤和調(diào)試變數(shù)狀態(tài)轉(zhuǎn)換。

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

張量形狀記錄器

這是我根據(jù)我的使用場景實現(xiàn)的自訂包裝器的範例。程式碼位於 objwatch/wrappers.py 檔案中。此包裝器會自動記錄指定模組內(nèi)所有函數(shù)方法呼叫中輸入和輸出的張量形狀以及變數(shù)的狀態(tài)。這對於理解複雜分散式框架的執(zhí)行邏輯非常有用。

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

在深度學(xué)習(xí)項目中，張量的形狀和維度至關(guān)重要。小尺寸誤差可能會導(dǎo)致整個模型無法正確訓(xùn)練或預(yù)測。手動檢查每個張量的形狀既乏味又容易出錯。 TensorShapeLogger 自動記錄張量形狀，幫助開發(fā)人員：

• 快速識別尺寸不符問題：自動記錄形狀訊息，以便及時檢測並修復(fù)尺寸錯誤。
• 最佳化模型架構(gòu)：透過追蹤張量形狀的變化，優(yōu)化網(wǎng)路結(jié)構(gòu)以提高模型效能。
• 提高調(diào)試效率：減少手動檢查張量形狀所花費的時間，從而專注於核心模型開發(fā)。

使用自訂包裝器的範例

建議參考tests/test_torch_train.py檔。該文件包含 PyTorch 訓(xùn)練過程的完整範例，演示如何整合 ObjWatch 進行監(jiān)控和日誌記錄。

筆記

?? 效能警告
在調(diào)試環(huán)境中使用 ObjWatch 會影響程式的效能。因此，建議僅在調(diào)試和開發(fā)階段使用它。

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

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

以上是調(diào)試救星！利用 ObjWatch 在複雜的 Python 專案中進行高效的程式碼理解和調(diào)試的詳細內(nèi)容。更多資訊請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！