源代碼鏈接

當(dāng)前調(diào)試痛點(diǎn)

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

什么是 ObjWatch？

ObjWatch 專為簡化復(fù)雜項目的調(diào)試和監(jiān)控而設(shè)計。它提供對象屬性和方法調(diào)用的實時跟蹤，并允許自定義掛鉤來幫助開發(fā)人員更深入地了解代碼庫。

快速使用示例

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

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

執(zhí)行上述代碼會產(chǎn)生以下調(diào)用信息：

[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 調(diào)用來使用該工具。在示例中，我們指定對examples/example_usage.py 文件進(jìn)行跟蹤，這意味著該工具將記錄examples/example_usage.py 中的任何函數(shù)、方法或變量。這種清晰的分層日志記錄有助于可視化和監(jiān)視嵌套函數(shù)調(diào)用和對象交互。打印的日志包括以下幾種執(zhí)行類型：

• run：表示函數(shù)或類方法執(zhí)行的開始。
• end：表示函數(shù)或類方法執(zhí)行結(jié)束。
• upd：代表創(chuàng)建一個新變量。
• apd：表示向列表、集合或字典等數(shù)據(jù)結(jié)構(gòu)添加元素。
• pop：標(biāo)記從數(shù)據(jù)結(jié)構(gòu)（如列表、集合或字典）??中刪除元素。

示例相對簡單，但此功能對于執(zhí)行大型項目非常有用。

整體特點(diǎn)

ObjWatch 提供以下接口：

• 目標(biāo)（列表）：要監(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，可選）：自定義包裝器以擴(kuò)展跟蹤和日志記錄功能。
• with_locals（bool，可選）：在函數(shù)執(zhí)行期間啟用函數(shù)內(nèi)局部變量的跟蹤和記錄。
• with_module_path (bool, 可選): 控制是否在日志中的函數(shù)名稱前面添加模塊路徑。

主要功能：自定義包裝擴(kuò)展

ObjWatch 提供了 FunctionWrapper 抽象基類，允許用戶創(chuàng)建自定義包裝器來擴(kuò)展和自定義庫的跟蹤和日志記錄功能。通過繼承FunctionWrapper，開發(fā)人員可以實現(xiàn)針對特定項目需求的定制行為。這些行為會在函數(shù)調(diào)用和返回時執(zhí)行，提供更專業(yè)的監(jiān)控。

函數(shù)包裝類

FunctionWrapper 類定義了兩個必須實現(xiàn)的核心方法：

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

該方法在函數(shù)調(diào)用開始時被調(diào)用。它接收函數(shù)名稱和當(dāng)前幀對象，其中包含執(zhí)行上下文，包括局部變量和調(diào)用堆棧。實現(xiàn)此方法以在函數(shù)執(zhí)行之前提取、記錄或修改信息。

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

此方法在函數(shù)返回時調(diào)用。它接收函數(shù)名稱和函數(shù)返回的結(jié)果。使用此方法在函數(shù)完成執(zhí)行后記錄、分析或更改信息。

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

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

有關(guān)框架對象的更多詳細(xì)信息，請參閱Python官方文檔。

張量形狀記錄器

這是我根據(jù)我的使用場景實現(xiàn)的自定義包裝器的示例。代碼位于 objwatch/wrappers.py 文件中。該包裝器自動記錄指定模塊內(nèi)所有函數(shù)方法調(diào)用中輸入和輸出的張量形狀以及變量的狀態(tài)。這對于理解復(fù)雜分布式框架的執(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ù)尺寸錯誤。
• 優(yōu)化模型架構(gòu)：通過跟蹤張量形狀的變化，優(yōu)化網(wǎng)絡(luò)結(jié)構(gòu)以提高模型性能。
• 提高調(diào)試效率：減少手動檢查張量形狀所花費(fèi)的時間，從而專注于核心模型開發(fā)。

使用自定義包裝器的示例

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

筆記

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

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

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

以上是調(diào)試救星！利用 ObjWatch 在復(fù)雜的 Python 項目中進(jìn)行高效的代碼理解和調(diào)試的詳細(xì)內(nèi)容。更多信息請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！