logcore 0.1.2__py3-none-any.whl

logcore-0.1.2.dist-info/METADATA

@@ -0,0 +1,433 @@
+Metadata-Version: 2.4
+Name: logcore
+Version: 0.1.2
+Summary: A production-ready structured logging library for Python
+Author-email: LogForge Contributors <contributors@logforge.dev>
+Maintainer-email: LogForge Contributors <contributors@logforge.dev>
+License: MIT License
+        
+        Copyright (c) 2025 LogForge Contributors
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/SarkarRana/logforge
+Project-URL: Bug Reports, https://github.com/SarkarRana/logforge/issues
+Project-URL: Source, https://github.com/SarkarRana/logforge
+Project-URL: Documentation, https://github.com/SarkarRana/logforge#readme
+Keywords: logging,structured-logging,json,observability,microservices
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: colors
+Requires-Dist: colorama>=0.4.0; extra == "colors"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "docs"
+Dynamic: license-file
+
+# LogForge 🔥
+
+[![PyPI version](https://badge.fury.io/py/logcore.svg)](https://badge.fury.io/py/logcore)
+[![Python versions](https://img.shields.io/pypi/pyversions/logcore.svg)](https://pypi.org/project/logcore/)
+[![CI](https://github.com/SarkarRana/logforge/actions/workflows/ci.yml/badge.svg)](https://github.com/SarkarRana/logforge/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SarkarRana/logforge/blob/main/LICENSE)
+
+**A production-ready logging library for Python**
+
+LogForge provides a simple, structured, and extensible logging solution that works seamlessly for both small scripts and large microservices. It's designed as a drop-in alternative to Python's built-in logging with a focus on developer experience, observability, and production readiness.
+
+## ✨ Features
+
+- **🚀 Simple API**: Single entrypoint with intuitive configuration
+- **📊 Structured Logging**: JSON and human-readable output formats
+- **🔗 Correlation IDs**: Built-in request tracing support
+- **⏱️ Built-in Timing**: Context managers for performance monitoring
+- **🛡️ Security**: Automatic redaction of sensitive fields
+- **📁 File Rotation**: Configurable log rotation and archival
+- **🎨 Colorized Output**: Beautiful console logging with colors
+- **⚡ Async Support**: Safe for asyncio applications
+- **🧵 Thread-safe**: Concurrent logging without issues
+- **🌍 Environment Configuration**: Configure via environment variables
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install logcore
+```
+
+For colored output support:
+
+```bash
+pip install logforge[colors]
+```
+
+### Basic Usage
+
+```python
+from logforge import get_logger
+
+# Create a logger
+log = get_logger("myapp", level="INFO", json=True)
+
+# Simple logging
+log.info("Application started")
+log.error("Something went wrong")
+
+# Structured logging with extra fields
+log.info("User login", user="alice", role="admin", success=True)
+
+# Exception logging with automatic traceback
+try:
+    1 / 0
+except Exception:
+    log.exception("Division failed")
+```
+
+## 📖 Documentation
+
+### Configuration Options
+
+LogForge can be configured through code or environment variables:
+
+```python
+from logforge import get_logger
+
+log = get_logger(
+    name="myapp",              # Logger name
+    level="INFO",              # DEBUG, INFO, WARNING, ERROR, CRITICAL
+    json=True,                 # JSON output (False for human-readable)
+    file="/path/to/app.log",   # Optional file logging
+    correlation_id="req-123",  # Optional correlation ID
+    max_file_size=10*1024*1024, # 10MB file size limit
+    backup_count=5,            # Keep 5 backup files
+    redact_fields={"password", "secret"}  # Fields to redact
+)
+```
+
+### Environment Variables
+
+Set configuration via environment variables:
+
+```bash
+export LOGFORGE_LEVEL=DEBUG
+export LOGFORGE_JSON=true
+export LOGFORGE_FILE=/var/log/app.log
+export LOGFORGE_CORRELATION_ID=req-abc-123
+export LOGFORGE_REDACT_FIELDS=password,token,secret
+```
+
+### Output Formats
+
+#### JSON Format
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:45.123456",
+  "level": "INFO",
+  "logger": "myapp",
+  "message": "User login",
+  "correlation_id": "req-123",
+  "user": "alice",
+  "success": true
+}
+```
+
+#### Human-Readable Format
+
+```
+2025-01-15 10:30:45.123 INFO     myapp [cid=req-123]: User login user=alice success=true
+```
+
+### Advanced Features
+
+#### Correlation IDs for Request Tracing
+
+```python
+from logforge import get_logger
+
+log = get_logger("api")
+
+# Set correlation ID for the entire request context
+with log.with_correlation_id("req-abc-123"):
+    log.info("Processing request")
+    process_request()
+    log.info("Request completed")
+```
+
+#### Performance Timing
+
+```python
+# Measure execution time automatically
+with log.time("database_query", level="DEBUG"):
+    result = expensive_database_operation()
+
+# Outputs:
+# Starting database_query
+# Completed database_query duration_ms=234.56
+```
+
+#### Exception Handling
+
+```python
+try:
+    risky_operation()
+except Exception as e:
+    log.exception("Operation failed", operation="risky_operation", user_id=123)
+    # Automatically includes full traceback
+```
+
+#### Sensitive Data Redaction
+
+```python
+# Configure fields to automatically redact
+log = get_logger("secure", redact_fields={"password", "token", "ssn"})
+
+log.info("User data", username="alice", password="secret123", role="admin")
+# Output: ... username=alice password=[REDACTED] role=admin
+```
+
+#### File Logging with Rotation
+
+```python
+log = get_logger(
+    "myapp",
+    file="/var/log/myapp.log",
+    max_file_size=10 * 1024 * 1024,  # 10MB
+    backup_count=5                    # Keep 5 old files
+)
+```
+
+Files are automatically rotated:
+
+- `myapp.log` (current)
+- `myapp.log.1` (previous)
+- `myapp.log.2` (older)
+- etc.
+
+### Async Support
+
+LogForge is fully compatible with asyncio:
+
+```python
+import asyncio
+from logforge import get_logger
+
+async def main():
+    log = get_logger("async_app")
+
+    # Correlation IDs work across await boundaries
+    with log.with_correlation_id():
+        log.info("Starting async operation")
+        await some_async_task()
+        log.info("Async operation completed")
+
+    # Async timing context manager
+    async with log.time("async_operation"):
+        await another_async_task()
+
+asyncio.run(main())
+```
+
+### Integration with Web Frameworks
+
+#### Flask Example
+
+```python
+from flask import Flask, request, g
+from logforge import get_logger
+import uuid
+
+app = Flask(__name__)
+log = get_logger("webapp")
+
+@app.before_request
+def before_request():
+    g.correlation_id = request.headers.get('X-Correlation-ID', str(uuid.uuid4()))
+
+@app.after_request
+def after_request(response):
+    with log.with_correlation_id(g.correlation_id):
+        log.info(
+            "Request completed",
+            method=request.method,
+            path=request.path,
+            status_code=response.status_code,
+            duration_ms=...  # Add timing logic
+        )
+    return response
+
+@app.route('/users/<user_id>')
+def get_user(user_id):
+    with log.with_correlation_id(g.correlation_id):
+        log.info("Fetching user", user_id=user_id)
+        # ... your logic here
+```
+
+#### FastAPI Example
+
+```python
+from fastapi import FastAPI, Request
+from logforge import get_logger
+import time
+import uuid
+
+app = FastAPI()
+log = get_logger("api")
+
+@app.middleware("http")
+async def logging_middleware(request: Request, call_next):
+    correlation_id = request.headers.get("x-correlation-id", str(uuid.uuid4()))
+    start_time = time.time()
+
+    with log.with_correlation_id(correlation_id):
+        log.info("Request started", method=request.method, url=str(request.url))
+
+        response = await call_next(request)
+
+        duration = (time.time() - start_time) * 1000
+        log.info(
+            "Request completed",
+            status_code=response.status_code,
+            duration_ms=round(duration, 2)
+        )
+
+    response.headers["x-correlation-id"] = correlation_id
+    return response
+```
+
+## 🆚 Comparison with Other Libraries
+
+### vs. Built-in `logging`
+
+| Feature            | LogForge                  | Built-in logging             |
+| ------------------ | ------------------------- | ---------------------------- |
+| Setup complexity   | ⭐⭐⭐⭐⭐ Single line    | ⭐⭐ Complex setup           |
+| Structured logging | ⭐⭐⭐⭐⭐ Built-in       | ⭐⭐ Manual implementation   |
+| JSON output        | ⭐⭐⭐⭐⭐ Automatic      | ⭐⭐ Custom formatter needed |
+| Correlation IDs    | ⭐⭐⭐⭐⭐ Built-in       | ⭐ Custom context needed     |
+| Security           | ⭐⭐⭐⭐⭐ Auto-redaction | ⭐ Manual filtering          |
+| Colors             | ⭐⭐⭐⭐⭐ Auto-detected  | ⭐⭐ Third-party needed      |
+
+### vs. `loguru`
+
+| Feature          | LogForge                    | Loguru                         |
+| ---------------- | --------------------------- | ------------------------------ |
+| Production focus | ⭐⭐⭐⭐⭐ Enterprise-ready | ⭐⭐⭐⭐ Great for development |
+| Correlation IDs  | ⭐⭐⭐⭐⭐ Built-in context | ⭐⭐ Manual binding            |
+| Security         | ⭐⭐⭐⭐⭐ Auto-redaction   | ⭐⭐ Manual filtering          |
+| Async support    | ⭐⭐⭐⭐⭐ Context-aware    | ⭐⭐⭐ Basic support           |
+| Performance      | ⭐⭐⭐⭐ Good               | ⭐⭐⭐⭐⭐ Excellent           |
+| Ecosystem        | ⭐⭐⭐⭐⭐ Standard logging | ⭐⭐⭐ Custom approach         |
+
+## 🛠️ Development
+
+### Setup
+
+```bash
+git clone https://github.com/logforge/logforge.git
+cd logforge
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=logforge
+
+# Run specific test categories
+pytest -m "not slow"          # Skip slow tests
+pytest -m integration         # Run integration tests only
+```
+
+### Code Quality
+
+```bash
+# Format code
+black logforge tests
+isort logforge tests
+
+# Lint
+flake8 logforge tests
+
+# Type checking
+mypy logforge
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## 🎯 Roadmap
+
+- [ ] **Performance Optimizations**: Async batching, lazy formatting
+- [ ] **Integrations**: OpenTelemetry, Sentry, DataDog
+- [ ] **Advanced Features**: Log sampling, rate limiting
+- [ ] **Cloud Native**: Kubernetes-friendly output formats
+- [ ] **Monitoring**: Health checks and metrics endpoints
+
+## 💖 Support
+
+If you find LogForge useful, please consider:
+
+- ⭐ Starring the repository
+- 🐛 Reporting bugs and issues
+- 💡 Suggesting new features
+- 📖 Improving documentation
+- 💻 Contributing code
+
+---
+
+**Built with ❤️ for the Python community**

logcore-0.1.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+logcore-0.1.2.dist-info/licenses/LICENSE,sha256=3KBLf0BLAuWowqqVRuMAEVjazAW7Ch5QEDAdRdE1JUg,1078
+logforge/__init__.py,sha256=kmTvxuXQSxQ17DI0-DCMxWJ2-I0MwY5nIN10pif1wkE,128
+logforge/config.py,sha256=DLoCvwF7I1sa_fdns16Sq2MBU6eNopYOxYqud0BXppI,3336
+logforge/formatters.py,sha256=uPOmi22oac_ZYa51TQbmXmTITbsbix2P5wECXWa1AF0,5507
+logforge/handlers.py,sha256=WTxTvxn4hw0FTekUXRPZ0lD9T4vPftrrLxnaAmTX7PM,1726
+logforge/logger.py,sha256=yFkRaRsAoDxjDkAypR0jidjpxr2J9p3-Smmr3MnhfF8,4899
+logforge/utils.py,sha256=B5u6HxNCiWew7QAoRywuaMjwRjBDnDcVx-H0jkeOwqk,4354
+logcore-0.1.2.dist-info/METADATA,sha256=y-cSuLzKvWZew4D-dF7cRXribF29bf5-cPJhKl86PFA,13194
+logcore-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+logcore-0.1.2.dist-info/top_level.txt,sha256=1VZVvxZgyeINaGnJ-sWATfeY6mFec4MoylvU3nYdKt8,9
+logcore-0.1.2.dist-info/RECORD,,

logcore-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

logcore-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LogForge Contributors
+
+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.

logcore-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+logforge

logforge/__init__.py

@@ -0,0 +1,6 @@
+"""LogForge - Production logging for Python."""
+
+from .logger import get_logger
+
+__version__ = "0.1.0"
+__all__ = ["get_logger"]

logforge/config.py

@@ -0,0 +1,104 @@
+"""Configuration management for LogForge."""
+
+import os
+from enum import Enum
+from typing import Any, Dict, Optional, Set
+from dataclasses import dataclass
+
+
+class LogLevel(Enum):
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    WARN = "WARN"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+    
+    @classmethod
+    def from_string(cls, level: str) -> "LogLevel":
+        level = level.upper()
+        if level == "WARN":
+            return cls.WARNING
+        return cls(level)
+
+
+@dataclass
+class LogForgeConfig:
+    name: str
+    level: LogLevel = LogLevel.INFO
+    json: bool = False
+    file: Optional[str] = None
+    correlation_id: Optional[str] = None
+    max_file_size: int = 10 * 1024 * 1024
+    backup_count: int = 5
+    redact_fields: Set[str] = None
+    
+    def __post_init__(self):
+        if self.redact_fields is None:
+            self.redact_fields = {
+                "password", "passwd", "secret", "token", "key", "api_key",
+                "access_token", "auth", "authorization", "credential",
+                "private_key", "cert", "certificate"
+            }
+
+
+def get_config_from_env() -> Dict[str, Any]:
+    config = {}
+    
+    if level := os.getenv("LOGFORGE_LEVEL"):
+        try:
+            config["level"] = LogLevel.from_string(level)
+        except ValueError:
+            pass
+    
+    if json_env := os.getenv("LOGFORGE_JSON"):
+        config["json"] = json_env.lower() in ("true", "1", "yes", "on")
+    
+    if file_path := os.getenv("LOGFORGE_FILE"):
+        config["file"] = file_path
+    
+    if correlation_id := os.getenv("LOGFORGE_CORRELATION_ID"):
+        config["correlation_id"] = correlation_id
+    
+    if max_size := os.getenv("LOGFORGE_MAX_FILE_SIZE"):
+        try:
+            config["max_file_size"] = int(max_size)
+        except ValueError:
+            pass
+    
+    if backup_count := os.getenv("LOGFORGE_BACKUP_COUNT"):
+        try:
+            config["backup_count"] = int(backup_count)
+        except ValueError:
+            pass
+    
+    if redact_fields := os.getenv("LOGFORGE_REDACT_FIELDS"):
+        config["redact_fields"] = set(field.strip() for field in redact_fields.split(","))
+    
+    return config
+
+
+def create_config(
+    name: str,
+    level: Optional[str] = None,
+    json: Optional[bool] = None,
+    file: Optional[str] = None,
+    correlation_id: Optional[str] = None,
+    max_file_size: Optional[int] = None,
+    backup_count: Optional[int] = None,
+    redact_fields: Optional[Set[str]] = None,
+) -> LogForgeConfig:
+    env_config = get_config_from_env()
+    
+    config_dict = {
+        "name": name,
+        "level": LogLevel.from_string(level) if level else env_config.get("level", LogLevel.INFO),
+        "json": json if json is not None else env_config.get("json", False),
+        "file": file if file is not None else env_config.get("file"),
+        "correlation_id": correlation_id if correlation_id is not None else env_config.get("correlation_id"),
+        "max_file_size": max_file_size if max_file_size is not None else env_config.get("max_file_size", 10 * 1024 * 1024),
+        "backup_count": backup_count if backup_count is not None else env_config.get("backup_count", 5),
+        "redact_fields": redact_fields if redact_fields is not None else env_config.get("redact_fields"),
+    }
+    
+    return LogForgeConfig(**config_dict)

logforge/formatters.py

@@ -0,0 +1,164 @@
+"""Formatters for LogForge logging output."""
+
+import json
+import logging
+import re
+import sys
+from datetime import datetime
+from typing import Any, Dict, Set
+
+try:
+    import colorama
+    from colorama import Fore, Style
+    colorama.init()
+    HAS_COLORS = True
+except ImportError:
+    HAS_COLORS = False
+    
+    class Fore:
+        RED = YELLOW = GREEN = BLUE = CYAN = MAGENTA = WHITE = ""
+    
+    class Style:
+        RESET_ALL = BRIGHT = ""
+
+
+class RedactingFormatter:
+    """Base formatter with redaction."""
+    
+    def __init__(self, redact_fields: Set[str] = None):
+        self.redact_fields = redact_fields or set()
+        self.redact_pattern = self._build_pattern()
+    
+    def _build_pattern(self):
+        if not self.redact_fields:
+            return None
+        
+        fields = "|".join(re.escape(field) for field in self.redact_fields)
+        pattern = rf'("{fields}"|{fields})(\s*[:=]\s*)("[^"]*"|[^\s,\]}}]+)'
+        return re.compile(pattern, re.IGNORECASE)
+    
+    def _redact_text(self, text: str) -> str:
+        if not self.redact_pattern:
+            return text
+        
+        def replace(match):
+            key = match.group(1)
+            sep = match.group(2)
+            return f'{key}{sep}"[REDACTED]"'
+        
+        return self.redact_pattern.sub(replace, text)
+    
+    def _redact_dict(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        if not self.redact_fields:
+            return data
+        
+        result = {}
+        redact_keys = {field.lower() for field in self.redact_fields}
+        
+        for key, value in data.items():
+            if key.lower() in redact_keys:
+                result[key] = "[REDACTED]"
+            elif isinstance(value, dict):
+                result[key] = self._redact_dict(value)
+            else:
+                result[key] = value
+        
+        return result
+
+
+class JSONFormatter(RedactingFormatter, logging.Formatter):
+    """JSON formatter for structured logging."""
+    
+    def __init__(self, redact_fields: Set[str] = None):
+        super().__init__(redact_fields=redact_fields)
+        logging.Formatter.__init__(self)
+    
+    def format(self, record: logging.LogRecord) -> str:
+        entry = {
+            "timestamp": datetime.fromtimestamp(record.created).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        
+        if hasattr(record, "correlation_id") and record.correlation_id:
+            entry["correlation_id"] = record.correlation_id
+        
+        skip_fields = {
+            "name", "msg", "args", "levelname", "levelno", "pathname",
+            "filename", "module", "lineno", "funcName", "created",
+            "msecs", "relativeCreated", "thread", "threadName",
+            "processName", "process", "message", "correlation_id"
+        }
+        
+        for key, value in record.__dict__.items():
+            if key not in skip_fields:
+                entry[key] = value
+        
+        if record.exc_info and record.exc_info != True:
+            entry["exception"] = self.formatException(record.exc_info)
+        
+        entry = self._redact_dict(entry)
+        return json.dumps(entry, default=str, ensure_ascii=False)
+
+
+class TextFormatter(RedactingFormatter, logging.Formatter):
+    """Text formatter with colors."""
+    
+    COLORS = {
+        "DEBUG": Fore.CYAN,
+        "INFO": Fore.GREEN,
+        "WARNING": Fore.YELLOW,
+        "ERROR": Fore.RED,
+        "CRITICAL": Fore.RED + Style.BRIGHT,
+    }
+    
+    def __init__(self, redact_fields: Set[str] = None, use_colors: bool = None):
+        super().__init__(redact_fields=redact_fields)
+        
+        if use_colors is None:
+            use_colors = HAS_COLORS and hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
+        
+        self.use_colors = use_colors
+        logging.Formatter.__init__(self)
+    
+    def format(self, record: logging.LogRecord) -> str:
+        timestamp = datetime.fromtimestamp(record.created).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+        
+        level = record.levelname
+        if self.use_colors:
+            color = self.COLORS.get(level, "")
+            level = f"{color}{level:8}{Style.RESET_ALL}"
+        else:
+            level = f"{level:8}"
+        
+        message = record.getMessage()
+        
+        correlation_part = ""
+        if hasattr(record, "correlation_id") and record.correlation_id:
+            correlation_part = f" [cid={record.correlation_id}]"
+        
+        skip_fields = {
+            "name", "msg", "args", "levelname", "levelno", "pathname",
+            "filename", "module", "lineno", "funcName", "created",
+            "msecs", "relativeCreated", "thread", "threadName",
+            "processName", "process", "message", "correlation_id"
+        }
+        
+        extras = []
+        redact_keys = {field.lower() for field in self.redact_fields}
+        
+        for key, value in record.__dict__.items():
+            if key not in skip_fields:
+                if key.lower() in redact_keys:
+                    value = "[REDACTED]"
+                extras.append(f"{key}={value}")
+        
+        extra_part = " " + " ".join(extras) if extras else ""
+        
+        formatted = f"{timestamp} {level} {record.name}{correlation_part}: {message}{extra_part}"
+        
+        if record.exc_info and record.exc_info != True:
+            formatted += "\n" + self.formatException(record.exc_info)
+        
+        return self._redact_text(formatted)

logforge/handlers.py

@@ -0,0 +1,55 @@
+"""Custom handlers for LogForge."""
+
+import logging
+import logging.handlers
+import sys
+from pathlib import Path
+from typing import Optional
+
+from .formatters import JSONFormatter, TextFormatter
+from .config import LogForgeConfig
+
+
+class ConsoleHandler:
+    def __init__(self, config: LogForgeConfig):
+        self.config = config
+        self.handler = logging.StreamHandler(sys.stderr)
+        formatter = JSONFormatter(redact_fields=config.redact_fields) if config.json else TextFormatter(redact_fields=config.redact_fields)
+        self.handler.setFormatter(formatter)
+    
+    def get_handler(self) -> logging.Handler:
+        return self.handler
+
+
+class FileHandler:
+    def __init__(self, config: LogForgeConfig, file_path: str):
+        self.config = config
+        
+        file_path = Path(file_path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        self.handler = logging.handlers.RotatingFileHandler(
+            filename=str(file_path),
+            maxBytes=config.max_file_size,
+            backupCount=config.backup_count,
+            encoding="utf-8"
+        )
+        
+        formatter = JSONFormatter(redact_fields=config.redact_fields) if config.json else TextFormatter(redact_fields=config.redact_fields)
+        self.handler.setFormatter(formatter)
+    
+    def get_handler(self) -> logging.Handler:
+        return self.handler
+
+
+def create_handlers(config: LogForgeConfig) -> list[logging.Handler]:
+    handlers = []
+    
+    console_handler = ConsoleHandler(config)
+    handlers.append(console_handler.get_handler())
+    
+    if config.file:
+        file_handler = FileHandler(config, config.file)
+        handlers.append(file_handler.get_handler())
+    
+    return handlers

logforge/logger.py

@@ -0,0 +1,152 @@
+"""Core logging functionality for LogForge."""
+
+import logging
+import sys
+import threading
+from typing import Any, Dict, Optional, Set, Union
+
+from .config import LogForgeConfig, LogLevel, create_config
+from .handlers import create_handlers
+from .utils import (
+    Timer, AsyncTimer, correlation_id_context, get_correlation_id,
+    set_correlation_id, safe_str, is_async_context
+)
+
+
+_logger_lock = threading.RLock()
+_loggers: Dict[str, "LogForgeLogger"] = {}
+
+
+class LogForgeLogger:
+    def __init__(self, config: LogForgeConfig):
+        self.config = config
+        
+        self._logger = logging.getLogger(f"logforge.{config.name}")
+        self._logger.setLevel(getattr(logging, config.level.value))
+        
+        self._logger.handlers.clear()
+        
+        handlers = create_handlers(config)
+        for handler in handlers:
+            handler.setLevel(getattr(logging, config.level.value))
+            self._logger.addHandler(handler)
+        
+        if config.correlation_id:
+            set_correlation_id(config.correlation_id)
+    
+    def _log(self, level: str, message: str, *args, **kwargs):
+        exc_info = kwargs.pop('exc_info', False)
+        
+        numeric_level = getattr(logging, level.upper(), logging.INFO)
+        
+        if not self._logger.isEnabledFor(numeric_level):
+            return
+        
+        record = self._logger.makeRecord(
+            self._logger.name,
+            numeric_level,
+            "(unknown file)",
+            0,
+            message,
+            args,
+            exc_info=exc_info,
+        )
+        
+        correlation_id = get_correlation_id()
+        if correlation_id:
+            record.correlation_id = correlation_id
+        
+        for key, value in kwargs.items():
+            if not hasattr(record, key):
+                setattr(record, key, safe_str(value))
+        
+        self._logger.handle(record)
+    
+    def debug(self, message: str, *args, **kwargs):
+        self._log("DEBUG", message, *args, **kwargs)
+    
+    def info(self, message: str, *args, **kwargs):
+        self._log("INFO", message, *args, **kwargs)
+    
+    def warning(self, message: str, *args, **kwargs):
+        self._log("WARNING", message, *args, **kwargs)
+    
+    def warn(self, message: str, *args, **kwargs):
+        self.warning(message, *args, **kwargs)
+    
+    def error(self, message: str, *args, **kwargs):
+        self._log("ERROR", message, *args, **kwargs)
+    
+    def critical(self, message: str, *args, **kwargs):
+        self._log("CRITICAL", message, *args, **kwargs)
+    
+    def exception(self, message: str, *args, **kwargs):
+        kwargs['exc_info'] = True
+        self.error(message, *args, **kwargs)
+    
+    def time(self, operation_name: str, level: str = "INFO", **kwargs) -> Union[Timer, AsyncTimer]:
+        if is_async_context():
+            return AsyncTimer(self, operation_name, level, **kwargs)
+        else:
+            return Timer(self, operation_name, level, **kwargs)
+    
+    def with_correlation_id(self, correlation_id: Optional[str] = None):
+        return correlation_id_context(correlation_id)
+    
+    def set_level(self, level: Union[str, LogLevel]):
+        if isinstance(level, str):
+            level = LogLevel.from_string(level)
+        
+        self.config.level = level
+        numeric_level = getattr(logging, level.value)
+        
+        self._logger.setLevel(numeric_level)
+        for handler in self._logger.handlers:
+            handler.setLevel(numeric_level)
+    
+    def get_level(self) -> LogLevel:
+        return self.config.level
+    
+    def is_enabled_for(self, level: Union[str, LogLevel]) -> bool:
+        if isinstance(level, str):
+            level = LogLevel.from_string(level)
+        
+        numeric_level = getattr(logging, level.value)
+        return self._logger.isEnabledFor(numeric_level)
+
+
+def get_logger(
+    name: str,
+    level: Optional[str] = None,
+    json: Optional[bool] = None,
+    file: Optional[str] = None,
+    correlation_id: Optional[str] = None,
+    max_file_size: Optional[int] = None,
+    backup_count: Optional[int] = None,
+    redact_fields: Optional[Set[str]] = None,
+) -> LogForgeLogger:
+    with _logger_lock:
+        if name in _loggers:
+            existing_logger = _loggers[name]
+            
+            if all(param is None for param in [
+                level, json, file, correlation_id, max_file_size,
+                backup_count, redact_fields
+            ]):
+                return existing_logger
+        
+        config = create_config(
+            name=name,
+            level=level,
+            json=json,
+            file=file,
+            correlation_id=correlation_id,
+            max_file_size=max_file_size,
+            backup_count=backup_count,
+            redact_fields=redact_fields,
+        )
+        
+        logger = LogForgeLogger(config)
+        _loggers[name] = logger
+        
+        return logger

logforge/utils.py

@@ -0,0 +1,153 @@
+"""Utilities for LogForge."""
+
+import asyncio
+import contextvars
+import time
+import uuid
+from contextlib import contextmanager
+from typing import Any, Generator, Optional
+
+
+correlation_context: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    'correlation_id', default=None
+)
+
+
+def generate_correlation_id() -> str:
+    return str(uuid.uuid4())
+
+
+def set_correlation_id(correlation_id: Optional[str] = None) -> str:
+    if correlation_id is None:
+        correlation_id = generate_correlation_id()
+    
+    correlation_context.set(correlation_id)
+    return correlation_id
+
+
+def get_correlation_id() -> Optional[str]:
+    return correlation_context.get()
+
+
+@contextmanager
+def correlation_id_context(correlation_id: Optional[str] = None) -> Generator[str, None, None]:
+    if correlation_id is None:
+        correlation_id = generate_correlation_id()
+    
+    token = correlation_context.set(correlation_id)
+    try:
+        yield correlation_id
+    finally:
+        correlation_context.reset(token)
+
+
+class Timer:
+    def __init__(self, logger, operation_name: str, level: str = "INFO", **kwargs):
+        self.logger = logger
+        self.operation_name = operation_name
+        self.level = level.upper()
+        self.extra_fields = kwargs
+        self.start_time = None
+        self.end_time = None
+    
+    def __enter__(self):
+        self.start_time = time.perf_counter()
+        self.logger._log(
+            self.level,
+            f"Starting {self.operation_name}",
+            **self.extra_fields
+        )
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.end_time = time.perf_counter()
+        duration = self.end_time - self.start_time
+        
+        if exc_type is not None:
+            self.logger._log(
+                "ERROR",
+                f"Failed {self.operation_name}",
+                duration_ms=round(duration * 1000, 2),
+                exception=str(exc_val) if exc_val else None,
+                **self.extra_fields
+            )
+        else:
+            self.logger._log(
+                self.level,
+                f"Completed {self.operation_name}",
+                duration_ms=round(duration * 1000, 2),
+                **self.extra_fields
+            )
+    
+    @property
+    def elapsed(self) -> Optional[float]:
+        if self.start_time is None:
+            return None
+        
+        end_time = self.end_time or time.perf_counter()
+        return end_time - self.start_time
+
+
+class AsyncTimer:
+    def __init__(self, logger, operation_name: str, level: str = "INFO", **kwargs):
+        self.logger = logger
+        self.operation_name = operation_name
+        self.level = level.upper()
+        self.extra_fields = kwargs
+        self.start_time = None
+        self.end_time = None
+    
+    async def __aenter__(self):
+        self.start_time = time.perf_counter()
+        self.logger._log(
+            self.level,
+            f"Starting {self.operation_name}",
+            **self.extra_fields
+        )
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        self.end_time = time.perf_counter()
+        duration = self.end_time - self.start_time
+        
+        if exc_type is not None:
+            self.logger._log(
+                "ERROR",
+                f"Failed {self.operation_name}",
+                duration_ms=round(duration * 1000, 2),
+                exception=str(exc_val) if exc_val else None,
+                **self.extra_fields
+            )
+        else:
+            self.logger._log(
+                self.level,
+                f"Completed {self.operation_name}",
+                duration_ms=round(duration * 1000, 2),
+                **self.extra_fields
+            )
+    
+    @property
+    def elapsed(self) -> Optional[float]:
+        if self.start_time is None:
+            return None
+        
+        end_time = self.end_time or time.perf_counter()
+        return end_time - self.start_time
+
+
+def is_async_context() -> bool:
+    try:
+        asyncio.current_task()
+        return True
+    except RuntimeError:
+        return False
+
+
+def safe_str(obj: Any, max_length: int = 1000) -> str:
+    try:
+        text = str(obj)
+        if len(text) > max_length:
+            return text[:max_length] + "..."
+        return text
+    except Exception:
+        return f"<{type(obj).__name__} object>"