# aeeeeeep/objwatch architecture

> Architecture diagram of the GitHub repository aeeeeeep/objwatch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aeeeeeep/objwatch
- Repository: https://github.com/aeeeeeep/objwatch

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Application Code
    subgraph "User/Application Code"
        U1["User/Application Code"]:::user
    end

    %% ObjWatch API/Entry Point
    subgraph "ObjWatch API/Entry Point"
        API["ObjWatch API (Entry Point)"]:::api
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        CONF["Config (config.py)"]:::config
        UTIL1["Logger (logger.py)"]:::config
        UTIL2["Weak References (weak.py)"]:::config
    end

    %% Core Tracing Engine
    subgraph "Core Tracing Engine"
        CORE["Core Logic (core.py & tracer.py)"]:::core
        EVENT["Event Handling (event_handls.py, events.py, mp_handls.py)"]:::event
    end

    %% Wrappers Module
    subgraph "Wrappers Module"
        WRAPPER1["ABCWrapper (abc_wrapper.py)"]:::wrapper
        WRAPPER2["BaseWrapper (base_wrapper.py)"]:::wrapper
        WRAPPER3["CPUMemoryWrapper (cpu_memory_wrapper.py)"]:::wrapper
        WRAPPER4["TensorShapeWrapper (tensor_shape_wrapper.py)"]:::wrapper
        WRAPPER5["TorchMemoryWrapper (torch_memory_wrapper.py)"]:::wrapper
    end

    %% Logging & External Libraries
    subgraph "Logging & External Libraries"
        LOGG["Logging (Python logging)"]:::external
        PSUTIL["psutil"]:::external
        TORCH["PyTorch (torch.cuda)"]:::external
    end

    %% Documentation & Tests
    subgraph "Documentation & Tests"
        DOC["Documentation (docs/)"]:::doc
        TEST["Test Suite (tests/)"]:::doc
    end

    %% Connections
    U1 ---|"initiates"| API
    API ---|"loads"| CONF
    API ---|"loads"| UTIL1
    API ---|"loads"| UTIL2
    API ---|"starts"| CORE
    CORE ---|"captures"| EVENT
    CORE <==>|"applies wrappers"| WRAPPER1
    CORE <==>|"applies wrappers"| WRAPPER2
    CORE <==>|"applies wrappers"| WRAPPER3
    CORE <==>|"applies wrappers"| WRAPPER4
    CORE <==>|"applies wrappers"| WRAPPER5
    EVENT ---|"logs events to"| LOGG
    EVENT ---|"external stats from"| PSUTIL
    EVENT ---|"external monitoring with"| TORCH
    DOC ---|"supports"| TEST

    %% Click Events
    click U1 "https://github.com/aeeeeeep/objwatch/blob/main/examples/example_usage.py"
    click TEST "https://github.com/aeeeeeep/objwatch/tree/main/tests/"
    click API "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/__init__.py"
    click CORE "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/core.py"
    click EVENT "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/event_handls.py"
    click CONF "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/config.py"
    click UTIL1 "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/utils/logger.py"
    click UTIL2 "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/utils/weak.py"
    click WRAPPER1 "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/wrappers/abc_wrapper.py"
    click WRAPPER2 "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/wrappers/base_wrapper.py"
    click WRAPPER3 "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/wrappers/cpu_memory_wrapper.py"
    click WRAPPER4 "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/wrappers/tensor_shape_wrapper.py"
    click WRAPPER5 "https://github.com/aeeeeeep/objwatch/blob/main/objwatch/wrappers/torch_memory_wrapper.py"
    click DOC "https://github.com/aeeeeeep/objwatch/tree/main/docs/"

    %% Styles
    classDef user fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef core fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef event fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef wrapper fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef external fill:#f8f9fa,stroke:#6c757d,stroke-width:2px;
    classDef doc fill:#d6d8db,stroke:#1b1e21,stroke-width:2px;
```
