diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml index cc4aa23..5dc21a4 100644 --- a/.github/workflows/python-test.yml +++ b/.github/workflows/python-test.yml @@ -47,8 +47,8 @@ jobs: run: | # Stop the build if there are Python syntax errors or undefined names flake8 ./objwatch ./examples --count --select=E9,F63,F7,F82 --show-source --statistics - # Exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide - flake8 ./objwatch ./examples --count --exit-zero --max-complexity=16 --max-line-length=127 --statistics + # The GitHub editor is 127 chars wide + flake8 ./objwatch ./examples --count --max-complexity=16 --max-line-length=127 --statistics - name: Type check with mypy run: | diff --git a/README.md b/README.md index 5ef1777..8b71074 100644 --- a/README.md +++ b/README.md @@ -21,24 +21,6 @@ ObjWatch is a Python library for OOP debugging with nested tracing and configura [ObjWatch Log Viewer](tools/vscode_extension) extension is now available on the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=aeeeeeep.objwatch-log-viewer), significantly enhancing the readability of ObjWatch logs through intelligent syntax highlighting, hierarchical structure recognition, and flexible folding capabilities. -## ✨ Features - -- **🎯 Flexible Target Monitoring**: Supports multiple target selection modes such as file paths, modules, classes, class members, class methods, functions, and global variables. -- **🌳 Nested Structure Tracing**: Visualize and monitor nested function calls and object interactions with clear, hierarchical logging. -- **📝 Enhanced Logging Support**: Utilize Python's built-in `logging` module for structured, customizable log outputs, including support for simple and detailed formats. -- **📋 Logging Message Types**: ObjWatch categorizes log messages into various types to provide detailed insights into code execution. The primary types include: - - - **`run`**: Function/method execution start - - **`end`**: Function/method execution end - - **`upd`**: Variable creation - - **`apd`**: Element addition to data structures - - **`pop`**: Element removal from data structures - - These classifications help developers efficiently trace and debug their code by understanding the flow and state changes within their applications. -- **🔥 Multi-Process Support**: Seamlessly trace distributed applications running across multiple processes/GPUs, ensuring comprehensive monitoring in high-performance environments. -- **🔌 Custom Wrapper Extensions**: Extend ObjWatch's functionality with custom wrappers, allowing tailored tracing and logging to fit specific project needs. -- **🎛️ Context Manager & API Integration**: Integrate ObjWatch effortlessly into your projects using context managers or API functions without relying on command-line interfaces. - ## 📦 Installation ObjWatch is available on [PyPI](https://pypi.org/project/objwatch). Install it using `pip`: @@ -55,6 +37,48 @@ cd objwatch pip install -e . ``` +## ⚙️ Configuration + +ObjWatch offers customizable logging formats and tracing options to suit various project requirements. + +### Parameters + +- `targets` (list): Files, modules, classes, class members, class methods, functions, global variables, or Python objects to monitor. The specific syntax formats are as follows: + - Module objects: Pass the module instance directly + - Class objects: Pass the class definition directly + - Instance methods: Pass the method instance directly + - Function objects: Pass the function instance directly + - String format: + - Module: 'package.module' + - Class: 'package.module:ClassName' + - Class attribute: 'package.module:ClassName.attribute' + - Class method: 'package.module:ClassName.method()' + - Function: 'package.module:function()' + - Global variable: 'package.module::GLOBAL_VAR' + + Example demonstrating mixed use of objects and strings: + ```python + from package.models import User + from package.utils import format_str + + with objwatch.ObjWatch([ + User, # Directly monitor class object + format_str, # Directly monitor function object + 'package.config::DEBUG_MODE' # String format global variable + ]): + main() + ``` +- `exclude_targets` (list, optional): Files or modules to exclude from monitoring. +- `with_locals` (bool, optional): Enable tracing and logging of local variables within functions during their execution. +- `with_globals` (bool, optional): Enable tracing and logging of global variables across function calls. When you input the global variables in the `targets` list, you need to enable this option. +- `output` (str, optional): File path for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. +- `output_json` (str, optional): JSON file path for writing structured logs. If specified, tracing information will be saved in a nested JSON format for easy analysis. +- `level` (str, optional): Logging level (e.g., `logging.DEBUG`, `logging.INFO`, `force` etc.). To ensure logs are captured even if the logger is disabled or removed by external libraries, you can set `level` to "force", which will bypass standard logging handlers and use `print()` to output log messages directly to the console, ensuring that critical debugging information is not lost. +- `simple` (bool, optional): Defaults to True, disable simple logging mode with the format `"[{time}] [{level}] objwatch: {msg}"`. +- `wrapper` (ABCWrapper, optional): Custom wrapper to extend tracing and logging functionality. +- `framework` (str, optional): The multi-process framework module to use. +- `indexes` (list, optional): The indexes to track in a multi-process environment. + ## 🚀 Getting Started ### Basic Usage @@ -205,47 +229,47 @@ Stopping ObjWatch tracing. -## ⚙️ Configuration +## ✨ Features -ObjWatch offers customizable logging formats and tracing options to suit various project requirements. +- **🎯 Flexible Target Monitoring**: Supports multiple target selection modes such as file paths, modules, classes, class members, class methods, functions, and global variables. +- **🌳 Nested Structure Tracing**: Visualize and monitor nested function calls and object interactions with clear, hierarchical logging. +- **📝 Enhanced Logging Support**: Utilize Python's built-in `logging` module for structured, customizable log outputs, including support for simple and detailed formats. +- **📋 Logging Message Types**: ObjWatch categorizes log messages into various types to provide detailed insights into code execution. The primary types include: + + - **`run`**: Function/method execution start + - **`end`**: Function/method execution end + - **`upd`**: Variable creation + - **`apd`**: Element addition to data structures + - **`pop`**: Element removal from data structures + + These classifications help developers efficiently trace and debug their code by understanding the flow and state changes within their applications. -### Parameters +- **📊 Structured Log Format**: ObjWatch uses a consistent log format for easy parsing and analysis: -- `targets` (list): Files, modules, classes, class members, class methods, functions, global variables, or Python objects to monitor. The specific syntax formats are as follows: - - Module objects: Pass the module instance directly - - Class objects: Pass the class definition directly - - Instance methods: Pass the method instance directly - - Function objects: Pass the function instance directly - - String format: - - Module: 'package.module' - - Class: 'package.module:ClassName' - - Class attribute: 'package.module:ClassName.attribute' - - Class method: 'package.module:ClassName.method()' - - Function: 'package.module:function()' - - Global variable: 'package.module::GLOBAL_VAR' + **Standard log structure**: - Example demonstrating mixed use of objects and strings: ```python - from package.models import User - from package.utils import format_str + f"{lineno:>5} {' '*call_depth}{event_type} {object_string} {message_string}" + ``` - with objwatch.ObjWatch([ - User, # Directly monitor class object - format_str, # Directly monitor function object - 'package.config::DEBUG_MODE' # String format global variable - ]): - main() + **Multi-process log structure**: + + ```python + f"[#{process_id}] {lineno:>5} {' '*call_depth}{event_type} {object_string} {message_string}" ``` -- `exclude_targets` (list, optional): Files or modules to exclude from monitoring. -- `framework` (str, optional): The multi-process framework module to use. -- `indexes` (list, optional): The indexes to track in a multi-process environment. -- `output` (str, optional): Path to a file for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. -- `output_json` (str, optional): Path to the JSON file for writing structured logs. If specified, tracing information will be saved in a nested JSON format for easy analysis. -- `level` (str, optional): Logging level (e.g., `logging.DEBUG`, `logging.INFO`, `force` etc.). To ensure logs are captured even if the logger is disabled or removed by external libraries, you can set `level` to "force", which will bypass standard logging handlers and use `print()` to output log messages directly to the console, ensuring that critical debugging information is not lost. -- `simple` (bool, optional): Defaults to True, disable simple logging mode with the format `"[{time}] [{level}] objwatch: {msg}"`. -- `wrapper` (ABCWrapper, optional): Custom wrapper to extend tracing and logging functionality. -- `with_locals` (bool, optional): Enable tracing and logging of local variables within functions during their execution. -- `with_globals` (bool, optional): Enable tracing and logging of global variables across function calls. When you input the global variables in the `targets` list, you need to enable this option. + + Where: + + - `lineno`: Line number (right-aligned, 5 characters) + - `call_depth`: Call stack depth (indented with 2 spaces per level) + - `event_type`: Event type (run, end, upd, apd, pop) + - `object_string`: Object identifier (e.g., `SampleClass.value`) + - `message_string`: Event-specific message (e.g., `None -> 10`) + - `process_id`: Process identifier in multi-process environments + +- **🔥 Multi-Process Support**: Seamlessly trace distributed applications running across multiple processes/GPUs, ensuring comprehensive monitoring in high-performance environments. +- **🔌 Custom Wrapper Extensions**: Extend ObjWatch's functionality with custom wrappers, allowing tailored tracing and logging to fit specific project needs. +- **🎛️ Context Manager & API Integration**: Integrate ObjWatch effortlessly into your projects using context managers or API functions without relying on command-line interfaces. ## 🪁 Advanced Usage diff --git a/README_zh.md b/README_zh.md index 2097295..8d2e0ff 100644 --- a/README_zh.md +++ b/README_zh.md @@ -21,24 +21,6 @@ ObjWatch 是一款面向对象的 Python 调试库，支持对模块、类、成 [ObjWatch Log Viewer](tools/vscode_extension) 扩展插件已在 [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=aeeeeeep.objwatch-log-viewer) 推出，通过智能语法高亮、层级结构识别和灵活的折叠功能，大幅提升 ObjWatch 日志易读性。 -## ✨ 功能 - -- **🎯 灵活的目标监控**：支持多种目标选择模式，如文件路径，模块，类，类成员，类方法，函数，全局变量。 -- **🌳 嵌套结构追踪**：通过清晰的层次化日志，直观地可视化和监控嵌套的函数调用和对象交互。 -- **📝 增强的日志支持**：利用 Python 内建的 `logging` 模块进行结构化、可定制的日志输出，支持简单和详细模式。 -- **📋 日志消息类型**：ObjWatch 将日志消息分类，以便提供详细的代码执行信息。主要类型包括： - - - **`run`**：表示函数或类方法的执行开始。 - - **`end`**：表示函数或类方法的执行结束。 - - **`upd`**：表示新变量的创建。 - - **`apd`**：表示向数据结构中添加元素。 - - **`pop`**：表示从数据结构中移除元素。 - - 这些分类帮助开发者高效地追踪和调试代码，了解程序中的执行流和状态变化。 -- **🔥 多进程支持**：无缝追踪分布式程序，支持跨多个进程/GPU 运行，确保高性能环境中的全面监控。 -- **🔌 自定义包装器扩展**：通过自定义包装器扩展功能，使其能够根据项目需求进行定制化的追踪和日志记录。 -- **🎛️ 上下文管理器和 API 集成**：通过上下文管理器或 API 函数轻松集成，无需依赖命令行界面。 - ## 📦 安装 可通过 [PyPI](https://pypi.org/project/objwatch) 安装。使用 `pip` 安装： @@ -55,6 +37,48 @@ cd objwatch pip install -e . ``` +## ⚙️ 配置 + +ObjWatch 提供可定制的日志格式和追踪选项，适应不同项目需求。 + +### 参数 + +- `targets` (列表) ：要监控的文件路径、模块、类、类成员、类方法、函数、全局变量或 Python 对象。具体语法格式如下： + - 模块对象：直接传入模块实例 + - 类对象：直接传入类定义 + - 实例方法：直接传入方法实例 + - 函数对象：直接传入函数实例 + - 字符串格式： + - 模块：'package.module' + - 类：'package.module:ClassName' + - 类属性：'package.module:ClassName.attribute' + - 类方法：'package.module:ClassName.method()' + - 函数：'package.module:function()' + - 全局变量：'package.module::GLOBAL_VAR' + + 示例演示混合使用对象和字符串： + ```python + from package.models import User + from package.utils import format_str + + with objwatch.ObjWatch([ + User, # 直接监控类对象 + format_str, # 直接监控函数对象 + 'package.config::DEBUG_MODE' # 字符串格式全局变量 + ]): + main() + ``` +- `exclude_targets` (列表，可选) ：要排除监控的文件或模块。 +- `with_locals` (布尔值，可选) ：启用在函数执行期间对局部变量的追踪和日志记录。 +- `with_globals` (布尔值，可选) ：启用跨函数调用的全局变量追踪和日志记录。当你输入的 `targets` 列表中包含全局变量时，需要同时启用此选项。 +- `output` (字符串，可选) ：写入日志的文件路径，必须以 '.objwatch' 结尾，用于 ObjWatch Log Viewer 扩展插件。 +- `output_json` (字符串，可选) ：用于写入结构化日志的 JSON 文件路径。如果指定，将以嵌套的 JSON 格式保存追踪信息，便于后续分析工作。 +- `level` (字符串，可选) ：日志级别 (例如 `logging.DEBUG`，`logging.INFO`，`force` 等) 。为确保即使 logger 被外部库禁用或删除，日志仍然有效，可以设置 `level` 为 `"force"`，这将绕过标准的日志处理器，直接使用 `print()` 将日志消息输出到控制台，确保关键的调试信息不会丢失。 +- `simple` (布尔值，可选) ：默认值为 True，禁用简化日志模式，格式为 `"[{time}] [{level}] objwatch: {msg}"`。 +- `wrapper` (ABCWrapper，可选) ：自定义包装器，用于扩展追踪和日志记录功能，详见下文。 +- `framework` (字符串，可选)：需要使用的多进程框架模块。 +- `indexes` (列表，可选)：需要在多进程环境中跟踪的 ids。 + ## 🚀 快速开始 ### 基本用法 @@ -203,47 +227,47 @@ Stopping ObjWatch tracing. -## ⚙️ 配置 +## ✨ 功能 -ObjWatch 提供可定制的日志格式和追踪选项，适应不同项目需求。 +- **🎯 灵活的目标监控**：支持多种目标选择模式，如文件路径，模块，类，类成员，类方法，函数，全局变量。 +- **🌳 嵌套结构追踪**：通过清晰的层次化日志，直观地可视化和监控嵌套的函数调用和对象交互。 +- **📝 增强的日志支持**：利用 Python 内建的 `logging` 模块进行结构化、可定制的日志输出，支持简单和详细模式。 +- **📋 日志消息类型**：ObjWatch 将日志消息分类，以便提供详细的代码执行信息。主要类型包括： -### 参数 + - **`run`**：表示函数或类方法的执行开始。 + - **`end`**：表示函数或类方法的执行结束。 + - **`upd`**：表示新变量的创建。 + - **`apd`**：表示向数据结构中添加元素。 + - **`pop`**：表示从数据结构中移除元素。 -- `targets` (列表) ：要监控的文件路径、模块、类、类成员、类方法、函数、全局变量或 Python 对象。具体语法格式如下： - - 模块对象：直接传入模块实例 - - 类对象：直接传入类定义 - - 实例方法：直接传入方法实例 - - 函数对象：直接传入函数实例 - - 字符串格式： - - 模块：'package.module' - - 类：'package.module:ClassName' - - 类属性：'package.module:ClassName.attribute' - - 类方法：'package.module:ClassName.method()' - - 函数：'package.module:function()' - - 全局变量：'package.module::GLOBAL_VAR' + 这些分类帮助开发者高效地追踪和调试代码，了解程序中的执行流和状态变化。 + +- **📊 结构化日志格式**：ObjWatch 使用一致的日志格式，便于解析和分析： + + **标准日志结构**： - 示例演示混合使用对象和字符串： ```python - from package.models import User - from package.utils import format_str + f"{lineno:>5} {' '*call_depth}{event_type} {object_string} {message_string}" + ``` - with objwatch.ObjWatch([ - User, # 直接监控类对象 - format_str, # 直接监控函数对象 - 'package.config::DEBUG_MODE' # 字符串格式全局变量 - ]): - main() + **多进程日志结构**： + + ```python + f"[#{process_id}] {lineno:>5} {' '*call_depth}{event_type} {object_string} {message_string}" ``` -- `exclude_targets` (列表，可选) ：要排除监控的文件或模块。 -- `framework` (字符串，可选)：需要使用的多进程框架模块。 -- `indexes` (列表，可选)：需要在多进程环境中跟踪的 ids。 -- `output` (字符串，可选) ：写入日志的文件路径，必须以 '.objwatch' 结尾，用于 ObjWatch Log Viewer 扩展插件。 -- `output_json` (字符串，可选) ：用于写入结构化日志的 JSON 文件路径。如果指定，将以嵌套的 JSON 格式保存追踪信息，便于后续分析工作。 -- `level` (字符串，可选) ：日志级别 (例如 `logging.DEBUG`，`logging.INFO`，`force` 等) 。为确保即使 logger 被外部库禁用或删除，日志仍然有效，可以设置 `level` 为 `"force"`，这将绕过标准的日志处理器，直接使用 `print()` 将日志消息输出到控制台，确保关键的调试信息不会丢失。 -- `simple` (布尔值，可选) ：默认值为 True，禁用简化日志模式，格式为 `"[{time}] [{level}] objwatch: {msg}"`。 -- `wrapper` (ABCWrapper，可选) ：自定义包装器，用于扩展追踪和日志记录功能，详见下文。 -- `with_locals` (布尔值，可选) ：启用在函数执行期间对局部变量的追踪和日志记录。 -- `with_globals` (布尔值，可选) ：启用跨函数调用的全局变量追踪和日志记录。当你输入的 `targets` 列表中包含全局变量时，需要同时启用此选项。 + + 其中： + + - `lineno`：行号（右对齐，5个字符） + - `call_depth`：调用栈深度（每级缩进2个空格） + - `event_type`：事件类型（run, end, upd, apd, pop） + - `object_string`：对象标识符（如 `SampleClass.value`） + - `message_string`：事件特定消息（如 `None -> 10`） + - `process_id`：多进程环境中的进程标识符 + +- **🔥 多进程支持**：无缝追踪分布式程序，支持跨多个进程/GPU 运行，确保高性能环境中的全面监控。 +- **🔌 自定义包装器扩展**：通过自定义包装器扩展功能，使其能够根据项目需求进行定制化的追踪和日志记录。 +- **🎛️ 上下文管理器和 API 集成**：通过上下文管理器或 API 函数轻松集成，无需依赖命令行界面。 ## 🪁 高级用法 diff --git a/docs/source/index.rst b/docs/source/index.rst index 2ed7a82..83077de 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,25 +21,6 @@ ObjWatch is a robust Python library designed to streamline the debugging and mon ObjWatch may impact your application's performance. It is recommended to use it solely in debugging environments. -✨ Features -=========== - -- **🎯 Flexible Target Monitoring**: Supports multiple target selection modes such as file paths, modules, classes, class members, class methods, functions, and global variables. -- **🌳 Nested Structure Tracing**: Visualize and monitor nested function calls and object interactions with clear, hierarchical logging. -- **📝 Enhanced Logging Support**: Utilize Python's built-in `logging` module for structured, customizable log outputs, including support for simple and detailed formats. -- **📋 Logging Message Types**: ObjWatch categorizes log messages into various types to provide detailed insights into code execution. The primary types include: - - - **`run`**: Function/method execution start - - **`end`**: Function/method execution end - - **`upd`**: Variable creation - - **`apd`**: Element addition to data structures - - **`pop`**: Element removal from data structures - - These classifications help developers efficiently trace and debug their code by understanding the flow and state changes within their applications. -- **🔥 Multi-Process Support**: Seamlessly trace distributed applications running across multiple processes/GPUs, ensuring comprehensive monitoring in high-performance environments. -- **🔌 Custom Wrapper Extensions**: Extend ObjWatch's functionality with custom wrappers, allowing tailored tracing and logging to fit specific project needs. -- **🎛️ Context Manager & API Integration**: Integrate ObjWatch effortlessly into your projects using context managers or API functions without relying on command-line interfaces. - 📦 Installation =============== @@ -57,6 +38,51 @@ Alternatively, you can clone the latest repository and install from source: cd objwatch pip install -e . +⚙️ Configuration +================ + +ObjWatch offers customizable logging formats and tracing options to suit various project requirements. Utilize the `simple` parameter to toggle between detailed and simplified logging outputs. + +Parameters +---------- + +- `targets` (list): Files, modules, classes, class members, class methods, functions, global variables, or Python objects to monitor. The specific syntax formats are as follows: + - Module objects: Pass the module instance directly + - Class objects: Pass the class definition directly + - Instance methods: Pass the method instance directly + - Function objects: Pass the function instance directly + - String format: + - Module: 'package.module' + - Class: 'package.module:ClassName' + - Class attribute: 'package.module:ClassName.attribute' + - Class method: 'package.module:ClassName.method()' + - Function: 'package.module:function()' + - Global variable: 'package.module::GLOBAL_VAR' + + Example demonstrating mixed use of objects and strings: + + .. code-block:: python + + from package.models import User + from package.utils import format_str + + with objwatch.ObjWatch([ + User, # Directly monitor class object + format_str, # Directly monitor function object + 'package.config::DEBUG_MODE' # String format global variable + ]): + main() +- `exclude_targets` (list, optional): Files or modules to exclude from monitoring. +- `with_locals` (bool, optional): Enable tracing and logging of local variables within functions during their execution. +- `with_globals` (bool, optional): Enable tracing and logging of global variables across function calls. When you input the global variables in the `targets` list, you need to enable this option. +- `output` (str, optional): File path for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. +- `output_json` (str, optional): JSON file path for writing structured logs. If specified, tracing information will be saved in a nested JSON format for easy analysis. +- `level` (str, optional): Logging level (e.g., `logging.DEBUG`, `logging.INFO`, `force` etc.). To ensure logs are captured even if the logger is disabled or removed by external libraries, you can set `level` to "force", which will bypass standard logging handlers and use `print()` to output log messages directly to the console, ensuring that critical debugging information is not lost. +- `simple` (bool, optional): Defaults to True, disable simple logging mode with the format `"[{time}] [{level}] objwatch: {msg}"`. +- `wrapper` (ABCWrapper, optional): Custom wrapper to extend tracing and logging functionality. +- `framework` (str, optional): The multi-process framework module to use. +- `indexes` (list, optional): The indexes to track in a multi-process environment. + 🚀 Getting Started ================== @@ -211,50 +237,48 @@ When running the above script, ObjWatch will generate logs similar to the follow 35 end __main__.main -> None Stopping ObjWatch tracing. -⚙️ Configuration -================ +✨ Features +=========== -ObjWatch offers customizable logging formats and tracing options to suit various project requirements. Utilize the `simple` parameter to toggle between detailed and simplified logging outputs. +- **🎯 Flexible Target Monitoring**: Supports multiple target selection modes such as file paths, modules, classes, class members, class methods, functions, and global variables. +- **🌳 Nested Structure Tracing**: Visualize and monitor nested function calls and object interactions with clear, hierarchical logging. +- **📝 Enhanced Logging Support**: Utilize Python's built-in `logging` module for structured, customizable log outputs, including support for simple and detailed formats. +- **📋 Logging Message Types**: ObjWatch categorizes log messages into various types to provide detailed insights into code execution. The primary types include: + + - **`run`**: Function/method execution start + - **`end`**: Function/method execution end + - **`upd`**: Variable creation + - **`apd`**: Element addition to data structures + - **`pop`**: Element removal from data structures + + These classifications help developers efficiently trace and debug their code by understanding the flow and state changes within their applications. -Parameters ----------- +- **📊 Structured Log Format**: ObjWatch uses a consistent log format for easy parsing and analysis: -- `targets` (list): Files, modules, classes, class members, class methods, functions, global variables, or Python objects to monitor. The specific syntax formats are as follows: - - Module objects: Pass the module instance directly - - Class objects: Pass the class definition directly - - Instance methods: Pass the method instance directly - - Function objects: Pass the function instance directly - - String format: - - Module: 'package.module' - - Class: 'package.module:ClassName' - - Class attribute: 'package.module:ClassName.attribute' - - Class method: 'package.module:ClassName.method()' - - Function: 'package.module:function()' - - Global variable: 'package.module::GLOBAL_VAR' + **Standard log structure**: - Example demonstrating mixed use of objects and strings: + ```python + f"{lineno:>5} {' '*call_depth}{event_type} {object_string} {message_string}" + ``` - .. code-block:: python + **Multi-process log structure**: - from package.models import User - from package.utils import format_str + ```python + f"[#{process_id}] {lineno:>5} {' '*call_depth}{event_type} {object_string} {message_string}" + ``` - with objwatch.ObjWatch([ - User, # Directly monitor class object - format_str, # Directly monitor function object - 'package.config::DEBUG_MODE' # String format global variable - ]): - main() -- `exclude_targets` (list, optional): Files or modules to exclude from monitoring. -- `framework` (str, optional): The multi-process framework module to use. -- `indexes` (list, optional): The indexes to track in a multi-process environment. -- `output` (str, optional): Path to a file for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. -- `output_json` (str, optional): Path to the JSON file for writing structured logs. If specified, tracing information will be saved in a nested JSON format for easy analysis. -- `level` (str, optional): Logging level (e.g., `logging.DEBUG`, `logging.INFO`, `force` etc.). To ensure logs are captured even if the logger is disabled or removed by external libraries, you can set `level` to "force", which will bypass standard logging handlers and use `print()` to output log messages directly to the console, ensuring that critical debugging information is not lost. -- `simple` (bool, optional): Defaults to True, disable simple logging mode with the format `"[{time}] [{level}] objwatch: {msg}"`. -- `wrapper` (ABCWrapper, optional): Custom wrapper to extend tracing and logging functionality. -- `with_locals` (bool, optional): Enable tracing and logging of local variables within functions during their execution. -- `with_globals` (bool, optional): Enable tracing and logging of global variables across function calls. When you input the global variables in the `targets` list, you need to enable this option. + Where: + + - `lineno`: Line number (right-aligned, 5 characters) + - `call_depth`: Call stack depth (indented with 2 spaces per level) + - `event_type`: Event type (run, end, upd, apd, pop) + - `object_string`: Object identifier (e.g., `SampleClass.value`) + - `message_string`: Event-specific message (e.g., `None -> 10`) + - `process_id`: Process identifier in multi-process environments + +- **🔥 Multi-Process Support**: Seamlessly trace distributed applications running across multiple processes/GPUs, ensuring comprehensive monitoring in high-performance environments. +- **🔌 Custom Wrapper Extensions**: Extend ObjWatch's functionality with custom wrappers, allowing tailored tracing and logging to fit specific project needs. +- **🎛️ Context Manager & API Integration**: Integrate ObjWatch effortlessly into your projects using context managers or API functions without relying on command-line interfaces. 🪁 Advanced Usage ================= diff --git a/objwatch/config.py b/objwatch/config.py index 0b72209..ab4b7e9 100644 --- a/objwatch/config.py +++ b/objwatch/config.py @@ -15,28 +15,28 @@ class ObjWatchConfig: Args: targets (List[Union[str, ModuleType]]): Files or modules to monitor. exclude_targets (Optional[List[Union[str, ModuleType]]]): Files or modules to exclude from monitoring. - framework (Optional[str]): The multi-process framework module to use. - indexes (Optional[List[int]]): The indexes to track in a multi-process environment. - output (Optional[str]): Path to a file for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. - output_json (Optional[str]): Path to the JSON file for writing structured logs. + with_locals (bool): Enable tracing and logging of local variables within functions. + with_globals (bool): Enable tracing and logging of global variables across function calls. + output (Optional[str]): File path for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. + output_json (Optional[str]): JSON file path for writing structured logs. level (int): Logging level (e.g., logging.DEBUG, logging.INFO). simple (bool): Defaults to True, disable simple logging mode with the format "[{time}] [{level}] objwatch: {msg}". wrapper (Optional[ABCWrapper]): Custom wrapper to extend tracing and logging functionality. - with_locals (bool): Enable tracing and logging of local variables within functions. - with_globals (bool): Enable tracing and logging of global variables across function calls. + framework (Optional[str]): The multi-process framework module to use. + indexes (Optional[List[int]]): The indexes to track in a multi-process environment. """ targets: List[Union[str, ModuleType]] exclude_targets: Optional[List[Union[str, ModuleType]]] = None - framework: Optional[str] = None - indexes: Optional[List[int]] = None + with_locals: bool = False + with_globals: bool = False output: Optional[str] = None output_json: Optional[str] = None level: int = logging.DEBUG simple: bool = True wrapper: Optional[Any] = None - with_locals: bool = False - with_globals: bool = False + framework: Optional[str] = None + indexes: Optional[List[int]] = None def __post_init__(self) -> None: """ diff --git a/objwatch/core.py b/objwatch/core.py index 0ed10ea..aadfcad 100644 --- a/objwatch/core.py +++ b/objwatch/core.py @@ -21,15 +21,15 @@ def __init__( self, targets: List[Union[str, ModuleType]], exclude_targets: Optional[List[Union[str, ModuleType]]] = None, - framework: Optional[str] = None, - indexes: Optional[List[int]] = None, + with_locals: bool = False, + with_globals: bool = False, output: Optional[str] = None, output_json: Optional[str] = None, level: int = logging.DEBUG, simple: bool = True, wrapper: Optional[ABCWrapper] = None, - with_locals: bool = False, - with_globals: bool = False, + framework: Optional[str] = None, + indexes: Optional[List[int]] = None, ) -> None: """ Initialize the ObjWatch instance with configuration parameters. @@ -37,15 +37,15 @@ def __init__( Args: targets (List[Union[str, ModuleType]]): Files or modules to monitor. exclude_targets (Optional[List[Union[str, ModuleType]]]): Files or modules to exclude from monitoring. - framework (Optional[str]): The multi-process framework module to use. - indexes (Optional[List[int]]): The indexes to track in a multi-process environment. - output (Optional[str]): Path to a file for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. - output_json (Optional[str]): Path to the JSON file for writing structured logs. + with_locals (bool): Enable tracing and logging of local variables within functions. + with_globals (bool): Enable tracing and logging of global variables across function calls. + output (Optional[str]): File path for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. + output_json (Optional[str]): JSON file path for writing structured logs. level (int): Logging level (e.g., logging.DEBUG, logging.INFO). simple (bool): Defaults to True, disable simple logging mode with the format "[{time}] [{level}] objwatch: {msg}". wrapper (Optional[ABCWrapper]): Custom wrapper to extend tracing and logging functionality. - with_locals (bool): Enable tracing and logging of local variables within functions. - with_globals (bool): Enable tracing and logging of global variables across function calls. + framework (Optional[str]): The multi-process framework module to use. + indexes (Optional[List[int]]): The indexes to track in a multi-process environment. """ # Create configuration parameters for ObjWatch config = ObjWatchConfig(**{k: v for k, v in locals().items() if k != 'self'}) @@ -96,15 +96,15 @@ def __exit__(self, exc_type: Optional[type], exc_val: Optional[BaseException], e def watch( targets: List[Union[str, ModuleType]], exclude_targets: Optional[List[Union[str, ModuleType]]] = None, - framework: Optional[str] = None, - indexes: Optional[List[int]] = None, + with_locals: bool = False, + with_globals: bool = False, output: Optional[str] = None, output_json: Optional[str] = None, level: int = logging.DEBUG, simple: bool = True, wrapper: Optional[ABCWrapper] = None, - with_locals: bool = False, - with_globals: bool = False, + framework: Optional[str] = None, + indexes: Optional[List[int]] = None, ) -> ObjWatch: """ Initialize and start an ObjWatch instance. @@ -112,15 +112,15 @@ def watch( Args: targets (List[Union[str, ModuleType]]): Files or modules to monitor. exclude_targets (Optional[List[Union[str, ModuleType]]]): Files or modules to exclude from monitoring. - framework (Optional[str]): The multi-process framework module to use. - indexes (Optional[List[int]]): The indexes to track in a multi-process environment. - output (Optional[str]): Path to a file for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. - output_json (Optional[str]): Path to the JSON file for writing structured logs. + with_locals (bool): Enable tracing and logging of local variables within functions. + with_globals (bool): Enable tracing and logging of global variables across function calls. + output (Optional[str]): File path for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. + output_json (Optional[str]): JSON file path for writing structured logs. level (int): Logging level (e.g., logging.DEBUG, logging.INFO). simple (bool): Defaults to True, disable simple logging mode with the format "[{time}] [{level}] objwatch: {msg}". wrapper (Optional[ABCWrapper]): Custom wrapper to extend tracing and logging functionality. - with_locals (bool): Enable tracing and logging of local variables within functions. - with_globals (bool): Enable tracing and logging of global variables across function calls. + framework (Optional[str]): The multi-process framework module to use. + indexes (Optional[List[int]]): The indexes to track in a multi-process environment. Returns: ObjWatch: The initialized and started ObjWatch instance. diff --git a/objwatch/utils/logger.py b/objwatch/utils/logger.py index aaed1f8..0758a92 100644 --- a/objwatch/utils/logger.py +++ b/objwatch/utils/logger.py @@ -17,7 +17,7 @@ def create_logger( Args: name (str): Name of the logger. - output (Optional[str]): Path to a file for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. + output (Optional[str]): File path for writing logs, must end with '.objwatch' for ObjWatch Log Viewer extension. level (Union[int, str]): Logging level (e.g., logging.DEBUG, logging.INFO, "force"). simple (bool): Defaults to True, disable simple logging mode with the format "[{time}] [{level}] objwatch: {msg}". """ diff --git a/pyproject.toml b/pyproject.toml index fa4d4d8..8101a2c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,7 +10,7 @@ authors = [ { name = "aeeeeeep", email = "aeeeeeep@proton.me" } ] readme = "README.md" -requires-python = ">=3.8,<3.15" +requires-python = ">=3.8,<3.16" dependencies = [ "psutil" ] @@ -22,7 +22,8 @@ classifiers = [ "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", - "Programming Language :: Python :: 3.14" + "Programming Language :: Python :: 3.14", + "Programming Language :: Python :: 3.15" ] [project.urls]