pyeztrace 0.0.1__tar.gz

pyeztrace-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jefferson Nelsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyeztrace-0.0.1/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: pyeztrace
+Version: 0.0.1
+Summary: A powerful, lightweight Python tracing and logging library
+Author: Jefferson Nelsson
+Author-email: Jefferson Nelsson <jefferson.nelsson@gmail.com>
+License-Expression: MIT
+Keywords: logging,tracing,monitoring,debugging,performance
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic-core>=2.33.2
+Requires-Dist: pydantic-settings>=2.9.1
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# PyEzTrace
+
+A powerful, lightweight Python tracing and logging library with hierarchical logging, context management, and performance metrics.
+
+**Note:** This was a fun, 3 hour experiment for one of my local projects. I'm happy to continue building this out if the community finds it useful and thinks it's a good idea!
+
+## Features
+
+- 🌳 **Hierarchical Logging**: Visualize nested operations with tree-style output
+- 🎨 **Multiple Formats**: Support for color, plain text, JSON, CSV, and logfmt outputs
+- 📊 **Performance Metrics**: Built-in timing and tracing capabilities
+- 🔄 **Context Management**: Thread-safe context propagation
+- 🔄 **Log Rotation**: Automatic log file management
+- 🎯 **Decorator-based Tracing**: Easy function and method tracing
+- 💪 **Thread-Safe**: Fully thread-safe implementation
+- 🚀 **High Performance**: Buffered logging and optimized output
+
+## Installation
+
+```bash
+pip install pyeztrace
+```
+
+## Quick Start
+
+```python
+from pyeztrace.setup import Setup
+Setup.initialize("MyApp") # Setup First! Make sure you initialize (optional) with your App Name before importing other modules. Default: EZTRACE
+
+from pyeztrace.tracer import trace
+from pyeztrace.custom_logging import Logging
+
+# Initialize the logging system
+log = Logging(log_format="color")  # or "json", "plain", "csv", "logfmt"
+
+# Use the tracer decorator
+@trace()
+def process_order(order_id):
+    with log.with_context(order_id=order_id):
+        log.log_info("Processing order")
+        validate_order(order_id)
+        process_payment(order_id)
+        log.log_info("Order processed successfully")
+
+@trace()
+def validate_order(order_id):
+    log.log_info("Validating order")
+    # Your validation logic here
+```
+
+Output example:
+```
+2025-05-13T10:00:00 - INFO - [MyApp] ├── process_order called...
+2025-05-13T10:00:00 - INFO - [MyApp] ├── Processing order Data: {order_id: "123"}
+2025-05-13T10:00:00 - INFO - [MyApp] ├────── validate_order called... 
+2025-05-13T10:00:00 - INFO - [MyApp] ├────── Validating order
+2025-05-13T10:00:00 - INFO - [MyApp] ├────── validate_order Ok. (took 0.50010 seconds)
+2025-05-13T10:00:01 - INFO - [MyApp] ├── Order processed successfully
+2025-05-13T10:00:01 - INFO - [MyApp] ├── process_order Ok. (took 1.23456 seconds)
+```
+
+## Features
+
+### 1. Tracing with Fine-grained Control
+
+```python
+@trace(
+    message="Custom trace message",  # Optional custom message
+    stack=True,  # Include stack trace on errors
+    modules_or_classes=[my_module],  # Trace specific modules
+    include=["specific_function_*"],  # Include only specific functions
+    exclude=["ignored_function_*"]  # Exclude specific functions
+)
+"""
+Decorator for parent function. Enables tracing for all child functions in the given modules or classes.
+If modules_or_classes is None, it will automatically patch the module where the parent function is defined.
+Accepts a single module/class or a list of modules/classes for cross-module tracing.
+Handles both sync and async parent functions.
+Supports selective tracing via include/exclude patterns (function names).
+"""
+def function():
+    # Your code here
+    pass
+```
+
+### 2. Context Management
+
+Thread-safe context propagation for structured logging:
+
+```python
+with log.with_context(user_id="123", action="login"):
+    log.log_info("User logged in")  # Will include context automatically
+    
+    with log.with_context(session="abc"):
+        # Nested context, inherits parent context
+        log.log_info("Session started")  # Includes both user_id and session
+```
+
+### 3. Multiple Output Formats
+
+```python
+# Color-coded console output with hierarchical visualization
+log = Logging(log_format="color")
+
+# JSON format for machine processing
+log = Logging(log_format="json")
+# Output: {"timestamp": "2025-05-13T10:00:00", "level": "INFO", "message": "Log message", "data": {"context": "value"}}
+
+# Plain text for simple logging
+log = Logging(log_format="plain")
+
+# CSV format for spreadsheet analysis
+log = Logging(log_format="csv")
+
+# logfmt for system logging
+log = Logging(log_format="logfmt")
+# Output: time=2025-05-13T10:00:00 level=INFO message="Log message" data.context=value
+```
+
+### 4. Async Support
+
+```python
+@trace()
+async def async_function():
+    await some_async_task()
+    log.log_info("Async operation completed")
+```
+
+### 5. Performance Metrics
+
+Automatic performance tracking is enabled with `show_metrics=True`:
+
+```python
+Setup.initialize("MyApp", show_metrics=True)
+
+@trace()
+def monitored_function():
+    # Function execution time will be automatically logged
+    pass
+
+# At program exit, prints performance summary:
+# === Tracing Performance Metrics Summary ===
+# Function                                    Calls    Total(s)      Avg(s)
+# --------------------------------------------------------------------
+# my_module.monitored_function                   10      1.23456      0.12346
+```
+
+### 6. Log Rotation
+
+Configure automatic log rotation based on file size:
+
+```python
+from pyeztrace.config import config
+
+config.max_size = 10 * 1024 * 1024  # 10MB
+config.backup_count = 5  # Keep 5 backup files
+config.log_dir = "logs"  # Custom log directory
+config.log_file = "app.log"  # Custom log filename
+```
+
+### 7. Error Handling and Debug Support
+
+```python
+# Different log levels
+log.log_debug("Debug information")
+log.log_info("Normal operation")
+log.log_warning("Warning message")
+log.log_error("Error occurred")
+
+try:
+    # Your code
+except Exception as e:
+    # Automatically log exception with stack trace
+    log.raise_exception_to_log(e, "Custom error message", stack=True)
+```
+
+### 8. Thread-Safe High-Volume Logging
+
+The logging system is designed for high-volume scenarios with thread-safe implementation:
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+
+@trace()
+def concurrent_operation(worker_id):
+    with log.with_context(worker_id=worker_id):
+        log.log_info("Worker started")
+        # ... work ...
+        log.log_info("Worker finished")
+
+with ThreadPoolExecutor(max_workers=5) as executor:
+    executor.map(concurrent_operation, range(5))
+```
+
+## Configuration
+
+All configuration options can be set via environment variables or code:
+
+```python
+# Via environment variables
+export EZTRACE_LOG_FORMAT="json"
+export EZTRACE_LOG_LEVEL="DEBUG"
+export EZTRACE_LOG_FILE="custom.log"
+export EZTRACE_MAX_SIZE="10485760"  # 10MB
+export EZTRACE_BACKUP_COUNT="5"
+
+# Via code
+from pyeztrace.config import config
+config.format = "json"
+config.log_level = "DEBUG"
+config.log_file = "custom.log"
+config.max_size = 10 * 1024 * 1024  # 10MB
+config.backup_count = 5
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pyeztrace-0.0.1/README.md

@@ -0,0 +1,222 @@
+# PyEzTrace
+
+A powerful, lightweight Python tracing and logging library with hierarchical logging, context management, and performance metrics.
+
+**Note:** This was a fun, 3 hour experiment for one of my local projects. I'm happy to continue building this out if the community finds it useful and thinks it's a good idea!
+
+## Features
+
+- 🌳 **Hierarchical Logging**: Visualize nested operations with tree-style output
+- 🎨 **Multiple Formats**: Support for color, plain text, JSON, CSV, and logfmt outputs
+- 📊 **Performance Metrics**: Built-in timing and tracing capabilities
+- 🔄 **Context Management**: Thread-safe context propagation
+- 🔄 **Log Rotation**: Automatic log file management
+- 🎯 **Decorator-based Tracing**: Easy function and method tracing
+- 💪 **Thread-Safe**: Fully thread-safe implementation
+- 🚀 **High Performance**: Buffered logging and optimized output
+
+## Installation
+
+```bash
+pip install pyeztrace
+```
+
+## Quick Start
+
+```python
+from pyeztrace.setup import Setup
+Setup.initialize("MyApp") # Setup First! Make sure you initialize (optional) with your App Name before importing other modules. Default: EZTRACE
+
+from pyeztrace.tracer import trace
+from pyeztrace.custom_logging import Logging
+
+# Initialize the logging system
+log = Logging(log_format="color")  # or "json", "plain", "csv", "logfmt"
+
+# Use the tracer decorator
+@trace()
+def process_order(order_id):
+    with log.with_context(order_id=order_id):
+        log.log_info("Processing order")
+        validate_order(order_id)
+        process_payment(order_id)
+        log.log_info("Order processed successfully")
+
+@trace()
+def validate_order(order_id):
+    log.log_info("Validating order")
+    # Your validation logic here
+```
+
+Output example:
+```
+2025-05-13T10:00:00 - INFO - [MyApp] ├── process_order called...
+2025-05-13T10:00:00 - INFO - [MyApp] ├── Processing order Data: {order_id: "123"}
+2025-05-13T10:00:00 - INFO - [MyApp] ├────── validate_order called... 
+2025-05-13T10:00:00 - INFO - [MyApp] ├────── Validating order
+2025-05-13T10:00:00 - INFO - [MyApp] ├────── validate_order Ok. (took 0.50010 seconds)
+2025-05-13T10:00:01 - INFO - [MyApp] ├── Order processed successfully
+2025-05-13T10:00:01 - INFO - [MyApp] ├── process_order Ok. (took 1.23456 seconds)
+```
+
+## Features
+
+### 1. Tracing with Fine-grained Control
+
+```python
+@trace(
+    message="Custom trace message",  # Optional custom message
+    stack=True,  # Include stack trace on errors
+    modules_or_classes=[my_module],  # Trace specific modules
+    include=["specific_function_*"],  # Include only specific functions
+    exclude=["ignored_function_*"]  # Exclude specific functions
+)
+"""
+Decorator for parent function. Enables tracing for all child functions in the given modules or classes.
+If modules_or_classes is None, it will automatically patch the module where the parent function is defined.
+Accepts a single module/class or a list of modules/classes for cross-module tracing.
+Handles both sync and async parent functions.
+Supports selective tracing via include/exclude patterns (function names).
+"""
+def function():
+    # Your code here
+    pass
+```
+
+### 2. Context Management
+
+Thread-safe context propagation for structured logging:
+
+```python
+with log.with_context(user_id="123", action="login"):
+    log.log_info("User logged in")  # Will include context automatically
+    
+    with log.with_context(session="abc"):
+        # Nested context, inherits parent context
+        log.log_info("Session started")  # Includes both user_id and session
+```
+
+### 3. Multiple Output Formats
+
+```python
+# Color-coded console output with hierarchical visualization
+log = Logging(log_format="color")
+
+# JSON format for machine processing
+log = Logging(log_format="json")
+# Output: {"timestamp": "2025-05-13T10:00:00", "level": "INFO", "message": "Log message", "data": {"context": "value"}}
+
+# Plain text for simple logging
+log = Logging(log_format="plain")
+
+# CSV format for spreadsheet analysis
+log = Logging(log_format="csv")
+
+# logfmt for system logging
+log = Logging(log_format="logfmt")
+# Output: time=2025-05-13T10:00:00 level=INFO message="Log message" data.context=value
+```
+
+### 4. Async Support
+
+```python
+@trace()
+async def async_function():
+    await some_async_task()
+    log.log_info("Async operation completed")
+```
+
+### 5. Performance Metrics
+
+Automatic performance tracking is enabled with `show_metrics=True`:
+
+```python
+Setup.initialize("MyApp", show_metrics=True)
+
+@trace()
+def monitored_function():
+    # Function execution time will be automatically logged
+    pass
+
+# At program exit, prints performance summary:
+# === Tracing Performance Metrics Summary ===
+# Function                                    Calls    Total(s)      Avg(s)
+# --------------------------------------------------------------------
+# my_module.monitored_function                   10      1.23456      0.12346
+```
+
+### 6. Log Rotation
+
+Configure automatic log rotation based on file size:
+
+```python
+from pyeztrace.config import config
+
+config.max_size = 10 * 1024 * 1024  # 10MB
+config.backup_count = 5  # Keep 5 backup files
+config.log_dir = "logs"  # Custom log directory
+config.log_file = "app.log"  # Custom log filename
+```
+
+### 7. Error Handling and Debug Support
+
+```python
+# Different log levels
+log.log_debug("Debug information")
+log.log_info("Normal operation")
+log.log_warning("Warning message")
+log.log_error("Error occurred")
+
+try:
+    # Your code
+except Exception as e:
+    # Automatically log exception with stack trace
+    log.raise_exception_to_log(e, "Custom error message", stack=True)
+```
+
+### 8. Thread-Safe High-Volume Logging
+
+The logging system is designed for high-volume scenarios with thread-safe implementation:
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+
+@trace()
+def concurrent_operation(worker_id):
+    with log.with_context(worker_id=worker_id):
+        log.log_info("Worker started")
+        # ... work ...
+        log.log_info("Worker finished")
+
+with ThreadPoolExecutor(max_workers=5) as executor:
+    executor.map(concurrent_operation, range(5))
+```
+
+## Configuration
+
+All configuration options can be set via environment variables or code:
+
+```python
+# Via environment variables
+export EZTRACE_LOG_FORMAT="json"
+export EZTRACE_LOG_LEVEL="DEBUG"
+export EZTRACE_LOG_FILE="custom.log"
+export EZTRACE_MAX_SIZE="10485760"  # 10MB
+export EZTRACE_BACKUP_COUNT="5"
+
+# Via code
+from pyeztrace.config import config
+config.format = "json"
+config.log_level = "DEBUG"
+config.log_file = "custom.log"
+config.max_size = 10 * 1024 * 1024  # 10MB
+config.backup_count = 5
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pyeztrace-0.0.1/pyeztrace/cli.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""Command-line interface for PyEzTrace log analysis."""
+
+import argparse
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+import re
+
+class LogAnalyzer:
+    def __init__(self, log_file: Path):
+        self.log_file = log_file
+        
+    def parse_logs(self, filter_level: Optional[str] = None, 
+                   since: Optional[datetime] = None,
+                   until: Optional[datetime] = None,
+                   context: Optional[dict] = None) -> List[dict]:
+        """Parse and filter log entries."""
+        entries = []
+        
+        with open(self.log_file, 'r') as f:
+            for line in f:
+                try:
+                    entry = self._parse_line(line.strip())
+                    if self._should_include(entry, filter_level, since, until, context):
+                        entries.append(entry)
+                except:
+                    continue  # Skip invalid lines
+                    
+        return entries
+    
+    def analyze_performance(self, function_name: Optional[str] = None) -> dict:
+        """Analyze performance metrics from logs."""
+        metrics = {}
+        entries = self.parse_logs()
+        
+        for entry in entries:
+            if 'duration' not in entry:
+                continue
+                
+            func = entry.get('function', 'unknown')
+            if function_name and func != function_name:
+                continue
+                
+            if func not in metrics:
+                metrics[func] = {
+                    'count': 0,
+                    'total_time': 0,
+                    'min_time': float('inf'),
+                    'max_time': 0,
+                }
+                
+            m = metrics[func]
+            duration = float(entry['duration'])
+            m['count'] += 1
+            m['total_time'] += duration
+            m['min_time'] = min(m['min_time'], duration)
+            m['max_time'] = max(m['max_time'], duration)
+            
+        # Calculate averages
+        for m in metrics.values():
+            m['avg_time'] = m['total_time'] / m['count']
+            
+        return metrics
+    
+    def find_errors(self, since: Optional[datetime] = None) -> List[dict]:
+        """Find error entries in logs."""
+        return self.parse_logs(filter_level="ERROR", since=since)
+    
+    def _parse_line(self, line: str) -> dict:
+        """Parse a single log line."""
+        try:
+            # Try JSON format first
+            return json.loads(line)
+        except:
+            # Fall back to parsing other formats
+            return self._parse_plain_format(line)
+    
+    def _parse_plain_format(self, line: str) -> dict:
+        """Parse plain text format."""
+        pattern = r'(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}) - (\w+) - \[([^\]]+)\](.*)'
+        match = re.match(pattern, line)
+        if not match:
+            raise ValueError("Invalid log format")
+            
+        timestamp, level, project, rest = match.groups()
+        return {
+            'timestamp': timestamp,
+            'level': level,
+            'project': project,
+            'message': rest.strip()
+        }
+    
+    def _should_include(self, entry: dict, 
+                       filter_level: Optional[str] = None,
+                       since: Optional[datetime] = None,
+                       until: Optional[datetime] = None,
+                       context: Optional[dict] = None) -> bool:
+        """Check if log entry matches filters."""
+        if filter_level and entry.get('level') != filter_level:
+            return False
+            
+        timestamp = datetime.fromisoformat(entry['timestamp'])
+        if since and timestamp < since:
+            return False
+        if until and timestamp > until:
+            return False
+            
+        if context:
+            entry_context = entry.get('data', {})
+            return all(entry_context.get(k) == v for k, v in context.items())
+            
+        return True
+
+def main():
+    parser = argparse.ArgumentParser(description="PyEzTrace Log Analyzer")
+    parser.add_argument('log_file', type=Path, help="Path to log file")
+    parser.add_argument('--level', choices=['DEBUG', 'INFO', 'WARNING', 'ERROR'],
+                      help="Filter by log level")
+    parser.add_argument('--since', type=str, help="Show logs since (YYYY-MM-DD[THH:MM:SS])")
+    parser.add_argument('--until', type=str, help="Show logs until (YYYY-MM-DD[THH:MM:SS])")
+    parser.add_argument('--context', type=str, help="Filter by context (key=value[,key=value])")
+    parser.add_argument('--analyze', action='store_true', help="Show performance metrics")
+    parser.add_argument('--function', type=str, help="Analyze specific function")
+    parser.add_argument('--errors', action='store_true', help="Show only errors")
+    parser.add_argument('--format', choices=['text', 'json'], default='text',
+                      help="Output format")
+    
+    args = parser.parse_args()
+    
+    # Parse datetime arguments
+    since = datetime.fromisoformat(args.since) if args.since else None
+    until = datetime.fromisoformat(args.until) if args.until else None
+    
+    # Parse context filters
+    context = {}
+    if args.context:
+        for pair in args.context.split(','):
+            key, value = pair.split('=')
+            context[key.strip()] = value.strip()
+    
+    analyzer = LogAnalyzer(args.log_file)
+    
+    if args.analyze:
+        metrics = analyzer.analyze_performance(args.function)
+        if args.format == 'json':
+            print(json.dumps(metrics, indent=2))
+        else:
+            for func, m in metrics.items():
+                print(f"\nFunction: {func}")
+                print(f"  Calls:     {m['count']}")
+                print(f"  Total:     {m['total_time']:.3f}s")
+                print(f"  Average:   {m['avg_time']:.3f}s")
+                print(f"  Min:       {m['min_time']:.3f}s")
+                print(f"  Max:       {m['max_time']:.3f}s")
+    
+    elif args.errors:
+        errors = analyzer.find_errors(since)
+        if args.format == 'json':
+            print(json.dumps(errors, indent=2))
+        else:
+            for error in errors:
+                print(f"\n{error['timestamp']} - {error['message']}")
+                if 'data' in error:
+                    print(f"Context: {json.dumps(error['data'], indent=2)}")
+    
+    else:
+        entries = analyzer.parse_logs(args.level, since, until, context)
+        if args.format == 'json':
+            print(json.dumps(entries, indent=2))
+        else:
+            for entry in entries:
+                print(f"{entry['timestamp']} - {entry['level']} - {entry['message']}")
+
+if __name__ == '__main__':
+    main()

pyeztrace-0.0.1/pyeztrace/config.py

@@ -0,0 +1,24 @@
+from pydantic_settings import BaseSettings
+from pydantic import ConfigDict
+from typing import Optional
+import os
+from pathlib import Path
+
+class LogConfig(BaseSettings):
+    """Configuration for the logging system."""
+    format: str = os.environ.get("EZTRACE_LOG_FORMAT", "color")
+    log_file: str = "app.log"
+    max_size: int = 10 * 1024 * 1024  # 10MB
+    backup_count: int = 5
+    log_dir: str = "logs"
+    log_level: str = "DEBUG"
+    
+    model_config = ConfigDict(env_prefix="EZTRACE_")
+
+    def get_log_path(self) -> Path:
+        """Get the full path to the log file."""
+        if os.path.isabs(self.log_file):
+            return Path(self.log_file)
+        return Path(self.log_dir) / self.log_file
+
+config = LogConfig()