How aeeeeeep/objwatch works
Main Components
• User/Application Code: Represents client code that imports and uses ObjWatch (as shown in examples and tests).
• ObjWatch Entry Point: The main API, represented by the ObjWatch class and the “watch” function. This is where tracing starts.
• Core Tracing Engine:
• Core Logic: Modules such as core.py and tracer.py implement the tracing mechanisms.
• Event Handling: Modules like event_handls.py, events.py, and mp_handls.py that manage tracing events, including multi-process support.
• Configuration and Utilities:
• Config: Contains configuration logic (config.py).
• Utilities: Includes helper functions and logging support (under objwatch/utils/logger.py and weak.py).
• Wrappers Module:
• BaseWrapper and its Variants (e.g., cpu_memory_wrapper.py, tensor_shape_wrapper.py, torch_memory_wrapper.py) provide the custom wrapping logic that intercepts function calls and returns.
• ABCWrapper serves as the abstract base class for all wrappers.
• External/Supporting Modules:
• Logging: Python's built-in logging module is used.
• Third-Party Libraries: For instance, psutil for CPU memory stats and PyTorch-related modules for GPU monitoring.
• Documentation and Tests:
• Documentation (docs/) and examples (examples/) – while not part of the runtime architecture, they illustrate usage and integration patterns.
• Test Suite: Located in tests/ for ensuring correct behavior and validating interactions between components.
Relationships and Data Flow
• The User/Application initiates tracing by calling either the ObjWatch context manager or using the watch() function.
• The ObjWatch entry point sets up the core tracing engine, which reads the provided configuration (targets, exclude lists, etc.).
• The Core Tracing Engine intercepts function calls in the target modules, leveraging Python's dynamic features to wrap calls.
• Event Handlers capture various events (function “run”, “end”, “upd”, etc.) and forward the information to the logging system (either via the logging API or direct output via print() when "force" is set).
• Utilities and configuration files support and enhance this process by providing logging helpers and weaker references.
Important Architectural Patterns & Design Principles
• Modular Design: Clearly separates responsibilities (tracing, event handling, configuration, wrappers).
• Decorator-Like Wrapping: Wrappers are applied to function calls to monitor execution before and after the call.
• Context Management: Offers a context manager interface that guarantees proper start/stop of tracing.
• Extensibility: Use of custom wrappers (based on the ABCWrapper) shows a plug-in architecture.
• Multi-Process Support: Through modules like mp_handls.py for handling distributed or multi-GPU environments.