goldcast-cl-logger 0.2.8__tar.gz

goldcast_cl_logger-0.2.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Content Lab
+
+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. 

goldcast_cl_logger-0.2.8/PKG-INFO

@@ -0,0 +1,336 @@
+Metadata-Version: 2.3
+Name: goldcast-cl-logger
+Version: 0.2.8
+Summary: A lightweight, flexible logging library for Content Lab projects with distributed tracing support
+License: MIT
+Author: Goldcast
+Author-email: engineering@goldcast.io
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Provides-Extra: http
+Requires-Dist: requests (>=2.31.0,<3.0.0) ; extra == "http"
+Project-URL: Bug Tracker, https://github.com/goldcast/content-lab-backend/issues
+Project-URL: Documentation, https://github.com/goldcast/content-lab-backend/tree/main/libraries/cl-logger
+Project-URL: Repository, https://github.com/goldcast/content-lab-backend
+Project-URL: Source Code, https://github.com/goldcast/content-lab-backend/tree/main/libraries/cl-logger
+Description-Content-Type: text/markdown
+
+# goldcast-cl-logger
+
+A lightweight, flexible logging library for Content Lab projects with distributed tracing support.
+
+## Installation
+
+```bash
+# Install from GitHub Packages (recommended)
+pip install goldcast-cl-logger
+
+# Install with HTTP extras for traced requests
+pip install goldcast-cl-logger[http]
+
+# Add to requirements.txt
+goldcast-cl-logger==0.2.8
+
+# Add to pyproject.toml (Poetry)
+[[tool.poetry.source]]
+name = "github"
+url = "https://ghcr.io/goldcast"
+
+[tool.poetry.dependencies]
+goldcast-cl-logger = { version = "^0.2.8", source = "github" }
+```
+
+## Features
+
+- **Simple API**: Easy to use with minimal configuration
+- **JSON Logging by Default**: Structured JSON logging for better observability
+- **Distributed Tracing**: Built-in support for trace ID propagation
+- **Sentry Integration**: Compatible with Sentry's distributed tracing
+- **Environment Configuration**: Control logging format via environment variables
+- **Extra Context**: Add custom fields to log entries
+- **File Logging**: Optional file output support
+- **Zero Dependencies**: Uses only Python standard library (requests is optional)
+- **HTTP & SQS Propagation**: Automatic trace ID propagation for external calls
+
+## Quick Start
+
+```python
+from cl_logger import get_logger
+
+# Get a logger instance
+logger = get_logger(__name__)
+
+# Basic logging (JSON by default)
+logger.info("Application started")
+logger.error("Something went wrong")
+
+# With extra context
+logger.info("User action", extra={"user_id": 123, "action": "login"})
+
+# Exception logging with traceback
+try:
+    risky_operation()
+except Exception as e:
+    logger.exception("Operation failed", extra={"operation": "risky_operation"})
+```
+
+## Distributed Tracing
+
+### Automatic Trace ID Propagation
+
+The logger automatically includes trace IDs in all log entries when used with the provided middleware:
+
+```python
+# Django middleware automatically creates/extracts trace IDs
+# In settings.py:
+MIDDLEWARE = [
+    # ...
+    'content_lab_backend.middleware.logging_middleware.RequestLoggingMiddleware',
+    # ...
+]
+```
+
+### Manual Trace Context
+
+```python
+from cl_logger import TraceContext, get_trace_id
+
+# Create a new trace context
+with TraceContext() as ctx:
+    logger.info("Starting operation")
+    # trace_id is automatically included in logs
+    current_trace_id = get_trace_id()
+```
+
+### HTTP Request Propagation
+
+```python
+from cl_logger import http_utils
+
+# Use traced HTTP client for automatic trace propagation
+response = http_utils.get("https://api.example.com/data")
+response = http_utils.post("https://api.example.com/users", json={"name": "John"})
+
+# Or use a traced session
+session = http_utils.TracedSession()
+response = session.get("https://api.example.com/data")
+```
+
+### SQS Message Propagation
+
+```python
+import boto3
+from cl_logger import sqs_utils
+
+# Wrap SQS client for automatic trace propagation
+sqs = boto3.client('sqs')
+traced_sqs = sqs_utils.TracedSQSClient(sqs)
+
+# Send message with trace ID
+traced_sqs.send_message(
+    QueueUrl='https://sqs.region.amazonaws.com/account/queue',
+    MessageBody='Hello World'
+)
+
+# Process incoming SQS message with trace context
+def handle_message(message):
+    logger.info("Processing message")
+    # trace_id from message is automatically set
+
+sqs_utils.process_sqs_message(sqs_message, handle_message)
+```
+
+## Configuration
+
+### Environment Variables
+
+- `CL_JSON_LOGGING`: Set to `"false"` to disable JSON logging (default: `"true"`)
+
+### Programmatic Configuration
+
+```python
+from cl_logger import CLLogger
+
+# Create logger with specific settings
+logger = CLLogger(
+    name="my_app",
+    level="DEBUG",
+    json_logging=True,  # Default
+    log_to_file="app.log"
+)
+
+# Toggle to normal logging at runtime
+logger.set_json_logging(False)
+
+# Change log level
+logger.set_level("WARNING")
+```
+
+## Output Examples
+
+### JSON Logging (Default)
+```json
+{
+  "timestamp": "2024-01-15T10:30:45.123Z",
+  "level": "INFO",
+  "logger": "my_app",
+  "message": "User action",
+  "module": "views",
+  "function": "login",
+  "line": 42,
+  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
+  "user_id": 123,
+  "action": "login"
+}
+```
+
+### Normal Logging
+```
+2024-01-15 10:30:45,123 - my_app - INFO - [550e8400-e29b-41d4-a716-446655440000] - User action | user_id=123 | action=login
+```
+
+## Django Integration
+
+### Settings Configuration
+
+In your Django settings:
+
+```python
+# settings.py
+import os
+from cl_logger import get_logger
+
+# Logger for settings module
+logger = get_logger(__name__)
+
+# JSON logging is enabled by default
+# To disable: export CL_JSON_LOGGING=false
+
+# Middleware configuration
+MIDDLEWARE = [
+    # ...
+    'content_lab_backend.middleware.logging_middleware.RequestLoggingMiddleware',
+    # ...
+]
+```
+
+### Usage in Views
+
+```python
+# views.py
+from cl_logger import get_logger, get_trace_id
+
+logger = get_logger(__name__)
+
+def my_view(request):
+    # Trace ID is automatically available from middleware
+    logger.info("View accessed", extra={
+        "user_id": request.user.id,
+        "method": request.method,
+        "path": request.path
+    })
+    
+    # Access trace ID if needed
+    trace_id = get_trace_id()
+    # or
+    trace_id = request.trace_id
+```
+
+## Advanced Usage
+
+### Custom Logger Class
+
+```python
+from cl_logger import CLLogger
+
+class AppLogger(CLLogger):
+    def log_request(self, request_id, method, path, status, duration):
+        self.info("API Request", extra={
+            "request_id": request_id,
+            "method": method,
+            "path": path,
+            "status": status,
+            "duration_ms": duration
+        })
+
+# Use custom logger
+logger = AppLogger("api")
+logger.log_request("abc123", "GET", "/api/users", 200, 45.2)
+```
+
+### Adding Trace Metadata
+
+```python
+from cl_logger import add_trace_metadata, get_trace_metadata
+
+# Add metadata to current trace
+add_trace_metadata("user_id", 123)
+add_trace_metadata("tenant", "acme-corp")
+
+# Metadata is automatically included in logs
+logger.info("Processing request")
+# Output includes: {..., "trace_metadata": {"user_id": 123, "tenant": "acme-corp"}}
+```
+
+## Best Practices
+
+1. **Use Module Names**: Always use `__name__` for logger names
+   ```python
+   logger = get_logger(__name__)
+   ```
+
+2. **Structured Context**: Use `extra` parameter for structured data
+   ```python
+   logger.info("User action", extra={"user_id": 123, "action": "login"})
+   ```
+
+3. **Consistent Field Names**: Use consistent names for common fields
+   - `user_id` for user identifiers
+   - `request_id` or `trace_id` for request tracking
+   - `duration_ms` for time measurements
+   - `status` for operation results
+
+4. **Let Middleware Handle Traces**: The middleware automatically manages trace IDs for HTTP requests
+
+5. **Use Traced Clients for External Calls**: Use the provided utilities for external calls to maintain trace continuity
+
+## Production Deployment
+
+For production environments:
+
+1. JSON logging is enabled by default (recommended)
+2. Trace IDs are automatically propagated to Sentry
+3. Use structured logging for better searchability and alerting
+4. Configure your log aggregation service to parse JSON logs
+
+## Troubleshooting
+
+### Logs not appearing
+
+1. Check the log level - by default, DEBUG messages are not shown
+2. Ensure the logger is properly initialized: `logger = get_logger(__name__)`
+
+### Trace IDs not propagating
+
+1. Ensure middleware is properly configured
+2. Use `http_utils` for HTTP requests or `sqs_utils` for SQS messages
+3. Check that trace context is active: `get_trace_id()` should return a value
+
+### Performance considerations
+
+- The logger is lightweight and adds minimal overhead
+- Trace context uses Python's contextvars for efficient async support
+- Extra fields are only processed when actually logging
+
+## License
+
+MIT License - see LICENSE file for details. 

goldcast_cl_logger-0.2.8/README.md

@@ -0,0 +1,310 @@
+# goldcast-cl-logger
+
+A lightweight, flexible logging library for Content Lab projects with distributed tracing support.
+
+## Installation
+
+```bash
+# Install from GitHub Packages (recommended)
+pip install goldcast-cl-logger
+
+# Install with HTTP extras for traced requests
+pip install goldcast-cl-logger[http]
+
+# Add to requirements.txt
+goldcast-cl-logger==0.2.8
+
+# Add to pyproject.toml (Poetry)
+[[tool.poetry.source]]
+name = "github"
+url = "https://ghcr.io/goldcast"
+
+[tool.poetry.dependencies]
+goldcast-cl-logger = { version = "^0.2.8", source = "github" }
+```
+
+## Features
+
+- **Simple API**: Easy to use with minimal configuration
+- **JSON Logging by Default**: Structured JSON logging for better observability
+- **Distributed Tracing**: Built-in support for trace ID propagation
+- **Sentry Integration**: Compatible with Sentry's distributed tracing
+- **Environment Configuration**: Control logging format via environment variables
+- **Extra Context**: Add custom fields to log entries
+- **File Logging**: Optional file output support
+- **Zero Dependencies**: Uses only Python standard library (requests is optional)
+- **HTTP & SQS Propagation**: Automatic trace ID propagation for external calls
+
+## Quick Start
+
+```python
+from cl_logger import get_logger
+
+# Get a logger instance
+logger = get_logger(__name__)
+
+# Basic logging (JSON by default)
+logger.info("Application started")
+logger.error("Something went wrong")
+
+# With extra context
+logger.info("User action", extra={"user_id": 123, "action": "login"})
+
+# Exception logging with traceback
+try:
+    risky_operation()
+except Exception as e:
+    logger.exception("Operation failed", extra={"operation": "risky_operation"})
+```
+
+## Distributed Tracing
+
+### Automatic Trace ID Propagation
+
+The logger automatically includes trace IDs in all log entries when used with the provided middleware:
+
+```python
+# Django middleware automatically creates/extracts trace IDs
+# In settings.py:
+MIDDLEWARE = [
+    # ...
+    'content_lab_backend.middleware.logging_middleware.RequestLoggingMiddleware',
+    # ...
+]
+```
+
+### Manual Trace Context
+
+```python
+from cl_logger import TraceContext, get_trace_id
+
+# Create a new trace context
+with TraceContext() as ctx:
+    logger.info("Starting operation")
+    # trace_id is automatically included in logs
+    current_trace_id = get_trace_id()
+```
+
+### HTTP Request Propagation
+
+```python
+from cl_logger import http_utils
+
+# Use traced HTTP client for automatic trace propagation
+response = http_utils.get("https://api.example.com/data")
+response = http_utils.post("https://api.example.com/users", json={"name": "John"})
+
+# Or use a traced session
+session = http_utils.TracedSession()
+response = session.get("https://api.example.com/data")
+```
+
+### SQS Message Propagation
+
+```python
+import boto3
+from cl_logger import sqs_utils
+
+# Wrap SQS client for automatic trace propagation
+sqs = boto3.client('sqs')
+traced_sqs = sqs_utils.TracedSQSClient(sqs)
+
+# Send message with trace ID
+traced_sqs.send_message(
+    QueueUrl='https://sqs.region.amazonaws.com/account/queue',
+    MessageBody='Hello World'
+)
+
+# Process incoming SQS message with trace context
+def handle_message(message):
+    logger.info("Processing message")
+    # trace_id from message is automatically set
+
+sqs_utils.process_sqs_message(sqs_message, handle_message)
+```
+
+## Configuration
+
+### Environment Variables
+
+- `CL_JSON_LOGGING`: Set to `"false"` to disable JSON logging (default: `"true"`)
+
+### Programmatic Configuration
+
+```python
+from cl_logger import CLLogger
+
+# Create logger with specific settings
+logger = CLLogger(
+    name="my_app",
+    level="DEBUG",
+    json_logging=True,  # Default
+    log_to_file="app.log"
+)
+
+# Toggle to normal logging at runtime
+logger.set_json_logging(False)
+
+# Change log level
+logger.set_level("WARNING")
+```
+
+## Output Examples
+
+### JSON Logging (Default)
+```json
+{
+  "timestamp": "2024-01-15T10:30:45.123Z",
+  "level": "INFO",
+  "logger": "my_app",
+  "message": "User action",
+  "module": "views",
+  "function": "login",
+  "line": 42,
+  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
+  "user_id": 123,
+  "action": "login"
+}
+```
+
+### Normal Logging
+```
+2024-01-15 10:30:45,123 - my_app - INFO - [550e8400-e29b-41d4-a716-446655440000] - User action | user_id=123 | action=login
+```
+
+## Django Integration
+
+### Settings Configuration
+
+In your Django settings:
+
+```python
+# settings.py
+import os
+from cl_logger import get_logger
+
+# Logger for settings module
+logger = get_logger(__name__)
+
+# JSON logging is enabled by default
+# To disable: export CL_JSON_LOGGING=false
+
+# Middleware configuration
+MIDDLEWARE = [
+    # ...
+    'content_lab_backend.middleware.logging_middleware.RequestLoggingMiddleware',
+    # ...
+]
+```
+
+### Usage in Views
+
+```python
+# views.py
+from cl_logger import get_logger, get_trace_id
+
+logger = get_logger(__name__)
+
+def my_view(request):
+    # Trace ID is automatically available from middleware
+    logger.info("View accessed", extra={
+        "user_id": request.user.id,
+        "method": request.method,
+        "path": request.path
+    })
+    
+    # Access trace ID if needed
+    trace_id = get_trace_id()
+    # or
+    trace_id = request.trace_id
+```
+
+## Advanced Usage
+
+### Custom Logger Class
+
+```python
+from cl_logger import CLLogger
+
+class AppLogger(CLLogger):
+    def log_request(self, request_id, method, path, status, duration):
+        self.info("API Request", extra={
+            "request_id": request_id,
+            "method": method,
+            "path": path,
+            "status": status,
+            "duration_ms": duration
+        })
+
+# Use custom logger
+logger = AppLogger("api")
+logger.log_request("abc123", "GET", "/api/users", 200, 45.2)
+```
+
+### Adding Trace Metadata
+
+```python
+from cl_logger import add_trace_metadata, get_trace_metadata
+
+# Add metadata to current trace
+add_trace_metadata("user_id", 123)
+add_trace_metadata("tenant", "acme-corp")
+
+# Metadata is automatically included in logs
+logger.info("Processing request")
+# Output includes: {..., "trace_metadata": {"user_id": 123, "tenant": "acme-corp"}}
+```
+
+## Best Practices
+
+1. **Use Module Names**: Always use `__name__` for logger names
+   ```python
+   logger = get_logger(__name__)
+   ```
+
+2. **Structured Context**: Use `extra` parameter for structured data
+   ```python
+   logger.info("User action", extra={"user_id": 123, "action": "login"})
+   ```
+
+3. **Consistent Field Names**: Use consistent names for common fields
+   - `user_id` for user identifiers
+   - `request_id` or `trace_id` for request tracking
+   - `duration_ms` for time measurements
+   - `status` for operation results
+
+4. **Let Middleware Handle Traces**: The middleware automatically manages trace IDs for HTTP requests
+
+5. **Use Traced Clients for External Calls**: Use the provided utilities for external calls to maintain trace continuity
+
+## Production Deployment
+
+For production environments:
+
+1. JSON logging is enabled by default (recommended)
+2. Trace IDs are automatically propagated to Sentry
+3. Use structured logging for better searchability and alerting
+4. Configure your log aggregation service to parse JSON logs
+
+## Troubleshooting
+
+### Logs not appearing
+
+1. Check the log level - by default, DEBUG messages are not shown
+2. Ensure the logger is properly initialized: `logger = get_logger(__name__)`
+
+### Trace IDs not propagating
+
+1. Ensure middleware is properly configured
+2. Use `http_utils` for HTTP requests or `sqs_utils` for SQS messages
+3. Check that trace context is active: `get_trace_id()` should return a value
+
+### Performance considerations
+
+- The logger is lightweight and adds minimal overhead
+- Trace context uses Python's contextvars for efficient async support
+- Extra fields are only processed when actually logging
+
+## License
+
+MIT License - see LICENSE file for details. 

goldcast_cl_logger-0.2.8/cl_logger/__init__.py

@@ -0,0 +1,49 @@
+"""
+CL Logger - A lightweight logging library for Content Lab projects with distributed tracing support
+"""
+
+import logging
+
+from . import http_utils, sqs_utils
+from .logger import CLLogger, get_logger
+from .trace_context import (
+    SENTRY_TRACE_HEADER,
+    TRACE_ID_HEADER,
+    TraceContext,
+    add_trace_metadata,
+    generate_trace_id,
+    get_trace_id,
+    get_trace_metadata,
+    set_trace_id,
+    set_trace_metadata,
+)
+
+# Re-export logging level constants for convenience
+DEBUG = logging.DEBUG
+INFO = logging.INFO
+WARNING = logging.WARNING
+ERROR = logging.ERROR
+CRITICAL = logging.CRITICAL
+
+__version__ = "0.2.1"
+__all__ = [
+    "CLLogger",
+    "get_logger",
+    "TraceContext",
+    "get_trace_id",
+    "set_trace_id",
+    "generate_trace_id",
+    "get_trace_metadata",
+    "set_trace_metadata",
+    "add_trace_metadata",
+    "TRACE_ID_HEADER",
+    "SENTRY_TRACE_HEADER",
+    "http_utils",
+    "sqs_utils",
+    # Logging levels
+    "DEBUG",
+    "INFO",
+    "WARNING",
+    "ERROR",
+    "CRITICAL",
+]

goldcast_cl_logger-0.2.8/cl_logger/http_utils.py

@@ -0,0 +1,121 @@
+"""
+HTTP utilities for trace ID propagation
+"""
+from typing import Any, Dict, Optional
+from urllib.parse import urlparse
+
+import requests
+
+from .logger import get_logger
+from .trace_context import SENTRY_TRACE_HEADER, TRACE_ID_HEADER, get_trace_id
+
+logger = get_logger(__name__)
+
+
+def add_trace_headers(headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+    """
+    Add trace ID headers to existing headers dict.
+
+    Args:
+        headers: Existing headers dict (optional)
+
+    Returns:
+        Headers dict with trace ID headers added
+    """
+    if headers is None:
+        headers = {}
+    else:
+        headers = headers.copy()
+
+    trace_id = get_trace_id()
+    if trace_id:
+        headers[TRACE_ID_HEADER] = trace_id
+        # Add Sentry trace format if needed
+        # Format: {trace_id}-{span_id}-{sampled}
+        headers[SENTRY_TRACE_HEADER] = f"{trace_id}-{trace_id[:16]}-1"
+
+    return headers
+
+
+class TracedSession(requests.Session):
+    """
+    A requests Session that automatically adds trace headers to all requests.
+    """
+
+    def request(self, method, url, **kwargs):
+        """Override request to add trace headers"""
+        kwargs["headers"] = add_trace_headers(kwargs.get("headers"))
+
+        trace_id = get_trace_id()
+        logger.debug(
+            "Making HTTP request",
+            extra={
+                "method": method,
+                "url": url,
+                "trace_id": trace_id,
+                "host": urlparse(url).netloc,
+            },
+        )
+
+        return super().request(method, url, **kwargs)
+
+
+def traced_request(method: str, url: str, **kwargs) -> requests.Response:
+    """
+    Make an HTTP request with trace headers automatically added.
+
+    This is a drop-in replacement for requests.request() that adds trace headers.
+
+    Args:
+        method: HTTP method (GET, POST, etc.)
+        url: URL to request
+        **kwargs: Additional arguments passed to requests.request()
+
+    Returns:
+        requests.Response object
+    """
+    kwargs["headers"] = add_trace_headers(kwargs.get("headers"))
+
+    trace_id = get_trace_id()
+    logger.debug(
+        "Making traced HTTP request",
+        extra={
+            "method": method,
+            "url": url,
+            "trace_id": trace_id,
+            "host": urlparse(url).netloc,
+        },
+    )
+
+    return requests.request(method, url, **kwargs)
+
+
+# Convenience methods that mirror requests API
+def get(url: str, **kwargs) -> requests.Response:
+    """GET request with trace headers"""
+    return traced_request("GET", url, **kwargs)
+
+
+def post(url: str, **kwargs) -> requests.Response:
+    """POST request with trace headers"""
+    return traced_request("POST", url, **kwargs)
+
+
+def put(url: str, **kwargs) -> requests.Response:
+    """PUT request with trace headers"""
+    return traced_request("PUT", url, **kwargs)
+
+
+def patch(url: str, **kwargs) -> requests.Response:
+    """PATCH request with trace headers"""
+    return traced_request("PATCH", url, **kwargs)
+
+
+def delete(url: str, **kwargs) -> requests.Response:
+    """DELETE request with trace headers"""
+    return traced_request("DELETE", url, **kwargs)
+
+
+def head(url: str, **kwargs) -> requests.Response:
+    """HEAD request with trace headers"""
+    return traced_request("HEAD", url, **kwargs)

goldcast_cl_logger-0.2.8/cl_logger/logger.py

@@ -0,0 +1,206 @@
+"""
+Core logging functionality for CL Logger
+"""
+
+import json
+import logging
+import os
+import sys
+from datetime import datetime
+from typing import Any, Dict, Optional, Union
+
+from .trace_context import get_trace_id, get_trace_metadata
+
+
+class JsonFormatter(logging.Formatter):
+    """Custom JSON formatter for structured logging with trace support"""
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_data = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+
+        # Add trace ID if available
+        trace_id = get_trace_id()
+        if trace_id:
+            log_data["trace_id"] = trace_id
+
+        # Add trace metadata if available
+        trace_metadata = get_trace_metadata()
+        if trace_metadata:
+            log_data["trace_metadata"] = trace_metadata
+
+        # Add extra fields if present
+        if hasattr(record, "extra_fields"):
+            log_data.update(record.extra_fields)
+
+        # Add exception info if present
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        return json.dumps(log_data)
+
+
+class CLLogger:
+    """
+    A flexible logger that can switch between normal and JSON logging.
+
+    Example:
+        logger = CLLogger("my_app")
+        logger.info("Application started")
+
+        # With extra context
+        logger.info("User action", extra={"user_id": 123, "action": "login"})
+
+        # Switch to normal logging
+        logger.set_json_logging(False)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        level: Union[str, int] = logging.INFO,
+        json_logging: Optional[bool] = None,
+        log_to_file: Optional[str] = None,
+    ):
+        """
+        Initialize the logger.
+
+        Args:
+            name: Logger name (typically __name__)
+            level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+            json_logging: Enable JSON logging (if None, checks CL_JSON_LOGGING env var, defaults to True)
+            log_to_file: Optional file path for logging to file
+        """
+        self.logger = logging.getLogger(name)
+        self.logger.setLevel(level)
+        self.logger.handlers = []  # Clear any existing handlers
+
+        # Check environment variable if json_logging not explicitly set
+        # Default to True (JSON logging) if not specified
+        if json_logging is None:
+            json_logging = os.getenv("CL_JSON_LOGGING", "true").lower() != "false"
+
+        self.json_logging = json_logging
+        self._setup_handlers(log_to_file)
+
+    def _setup_handlers(self, log_to_file: Optional[str] = None):
+        """Set up logging handlers based on configuration"""
+        # Console handler
+        console_handler = logging.StreamHandler(sys.stdout)
+
+        if self.json_logging:
+            console_handler.setFormatter(JsonFormatter())
+        else:
+            # Standard format for human-readable logs (includes trace ID)
+            formatter = logging.Formatter(
+                "%(asctime)s - %(name)s - %(levelname)s - [%(trace_id)s] - %(message)s"
+            )
+            console_handler.setFormatter(formatter)
+
+        self.logger.addHandler(console_handler)
+
+        # File handler if specified
+        if log_to_file:
+            file_handler = logging.FileHandler(log_to_file)
+            if self.json_logging:
+                file_handler.setFormatter(JsonFormatter())
+            else:
+                file_formatter = logging.Formatter(
+                    "%(asctime)s - %(name)s - %(levelname)s - %(funcName)s:%(lineno)d - [%(trace_id)s] - %(message)s"
+                )
+                file_handler.setFormatter(file_formatter)
+            self.logger.addHandler(file_handler)
+
+    def set_json_logging(self, enabled: bool):
+        """Toggle between JSON and normal logging"""
+        self.json_logging = enabled
+        # Recreate handlers with new format
+        handlers = self.logger.handlers.copy()
+        log_to_file = None
+        for handler in handlers:
+            if isinstance(handler, logging.FileHandler):
+                log_to_file = handler.baseFilename
+        self.logger.handlers = []
+        self._setup_handlers(log_to_file)
+
+    def set_level(self, level: Union[str, int]):
+        """Change the logging level"""
+        self.logger.setLevel(level)
+
+    def _log_with_extra(
+        self, level: int, msg: str, extra: Optional[Dict[str, Any]] = None, **kwargs
+    ):
+        """Internal method to log with extra fields and trace context"""
+        # Add trace_id to the record for normal formatter
+        if not self.json_logging:
+            kwargs.setdefault("extra", {})
+            kwargs["extra"]["trace_id"] = get_trace_id() or "no-trace"
+
+        if extra and self.json_logging:
+            # Store extra fields in the record for JSON formatter
+            kwargs["extra"] = {"extra_fields": extra}
+        elif extra:
+            # For normal logging, append extra fields to message
+            extra_str = " | ".join(f"{k}={v}" for k, v in extra.items())
+            msg = f"{msg} | {extra_str}"
+
+        self.logger.log(level, msg, **kwargs)
+
+    def debug(self, msg: str, extra: Optional[Dict[str, Any]] = None, **kwargs):
+        """Log debug message"""
+        self._log_with_extra(logging.DEBUG, msg, extra, **kwargs)
+
+    def info(self, msg: str, extra: Optional[Dict[str, Any]] = None, **kwargs):
+        """Log info message"""
+        self._log_with_extra(logging.INFO, msg, extra, **kwargs)
+
+    def warning(self, msg: str, extra: Optional[Dict[str, Any]] = None, **kwargs):
+        """Log warning message"""
+        self._log_with_extra(logging.WARNING, msg, extra, **kwargs)
+
+    def warn(self, msg: str, extra: Optional[Dict[str, Any]] = None, **kwargs):
+        """Log warning message (deprecated alias for warning)"""
+        self.warning(msg, extra, **kwargs)
+
+    def error(self, msg: str, extra: Optional[Dict[str, Any]] = None, **kwargs):
+        """Log error message"""
+        self._log_with_extra(logging.ERROR, msg, extra, **kwargs)
+
+    def critical(self, msg: str, extra: Optional[Dict[str, Any]] = None, **kwargs):
+        """Log critical message"""
+        self._log_with_extra(logging.CRITICAL, msg, extra, **kwargs)
+
+    def exception(self, msg: str, extra: Optional[Dict[str, Any]] = None, **kwargs):
+        """Log exception with traceback"""
+        kwargs["exc_info"] = True
+        self._log_with_extra(logging.ERROR, msg, extra, **kwargs)
+
+
+# Singleton pattern for easy access
+_loggers: Dict[str, CLLogger] = {}
+
+
+def get_logger(name: str, **kwargs) -> CLLogger:
+    """
+    Get or create a logger instance.
+
+    This function maintains a singleton pattern, returning the same logger
+    instance for a given name.
+
+    Args:
+        name: Logger name (typically __name__)
+        **kwargs: Additional arguments passed to CLLogger constructor
+
+    Returns:
+        CLLogger instance
+    """
+    if name not in _loggers:
+        _loggers[name] = CLLogger(name, **kwargs)
+    return _loggers[name]

goldcast_cl_logger-0.2.8/cl_logger/sqs_utils.py

@@ -0,0 +1,178 @@
+"""
+SQS utilities for trace ID propagation
+"""
+import json
+from typing import Any, Dict, List, Optional
+
+from .logger import get_logger
+from .trace_context import TRACE_ID_HEADER, get_trace_id, set_trace_id
+
+logger = get_logger(__name__)
+
+
+def add_trace_to_message_attributes(
+    message_attributes: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Add trace ID to SQS message attributes.
+
+    Args:
+        message_attributes: Existing message attributes (optional)
+
+    Returns:
+        Message attributes with trace ID added
+    """
+    if message_attributes is None:
+        message_attributes = {}
+    else:
+        message_attributes = message_attributes.copy()
+
+    trace_id = get_trace_id()
+    if trace_id:
+        message_attributes[TRACE_ID_HEADER] = {
+            "StringValue": trace_id,
+            "DataType": "String",
+        }
+
+    return message_attributes
+
+
+def extract_trace_from_message_attributes(
+    message_attributes: Optional[Dict[str, Any]]
+) -> Optional[str]:
+    """
+    Extract trace ID from SQS message attributes.
+
+    Args:
+        message_attributes: Message attributes from SQS message
+
+    Returns:
+        Trace ID if found, None otherwise
+    """
+    if not message_attributes:
+        return None
+
+    trace_attr = message_attributes.get(TRACE_ID_HEADER)
+    if trace_attr and isinstance(trace_attr, dict):
+        return trace_attr.get("StringValue")
+
+    return None
+
+
+def send_message_with_trace(sqs_client, **kwargs) -> Dict[str, Any]:
+    """
+    Send an SQS message with trace ID automatically added.
+
+    This wraps the boto3 SQS client's send_message method.
+
+    Args:
+        sqs_client: boto3 SQS client
+        **kwargs: Arguments for send_message
+
+    Returns:
+        Response from send_message
+    """
+    # Add trace ID to message attributes
+    kwargs["MessageAttributes"] = add_trace_to_message_attributes(
+        kwargs.get("MessageAttributes")
+    )
+
+    trace_id = get_trace_id()
+    logger.debug(
+        "Sending SQS message",
+        extra={
+            "queue_url": kwargs.get("QueueUrl"),
+            "trace_id": trace_id,
+            "message_attributes": list(kwargs.get("MessageAttributes", {}).keys()),
+        },
+    )
+
+    return sqs_client.send_message(**kwargs)
+
+
+def send_message_batch_with_trace(sqs_client, **kwargs) -> Dict[str, Any]:
+    """
+    Send a batch of SQS messages with trace ID automatically added to each.
+
+    This wraps the boto3 SQS client's send_message_batch method.
+
+    Args:
+        sqs_client: boto3 SQS client
+        **kwargs: Arguments for send_message_batch
+
+    Returns:
+        Response from send_message_batch
+    """
+    # Add trace ID to each message in the batch
+    entries = kwargs.get("Entries", [])
+    for entry in entries:
+        entry["MessageAttributes"] = add_trace_to_message_attributes(
+            entry.get("MessageAttributes")
+        )
+
+    trace_id = get_trace_id()
+    logger.debug(
+        "Sending SQS message batch",
+        extra={
+            "queue_url": kwargs.get("QueueUrl"),
+            "trace_id": trace_id,
+            "batch_size": len(entries),
+        },
+    )
+
+    return sqs_client.send_message_batch(**kwargs)
+
+
+def process_sqs_message(message: Dict[str, Any], handler_func, *args, **kwargs):
+    """
+    Process an SQS message with trace context.
+
+    This extracts the trace ID from the message and sets it in the context
+    before calling the handler function.
+
+    Args:
+        message: SQS message dict
+        handler_func: Function to process the message
+        *args, **kwargs: Arguments passed to handler_func
+
+    Returns:
+        Result from handler_func
+    """
+    # Extract trace ID from message attributes
+    trace_id = extract_trace_from_message_attributes(message.get("MessageAttributes"))
+
+    if trace_id:
+        logger.debug(
+            "Processing SQS message with trace",
+            extra={"trace_id": trace_id, "message_id": message.get("MessageId")},
+        )
+        set_trace_id(trace_id)
+    else:
+        logger.debug(
+            "Processing SQS message without trace",
+            extra={"message_id": message.get("MessageId")},
+        )
+
+    # Call the handler function
+    return handler_func(message, *args, **kwargs)
+
+
+class TracedSQSClient:
+    """
+    A wrapper around boto3 SQS client that automatically adds trace IDs to messages.
+    """
+
+    def __init__(self, sqs_client):
+        self.sqs_client = sqs_client
+
+    def send_message(self, **kwargs) -> Dict[str, Any]:
+        """Send message with trace ID"""
+        return send_message_with_trace(self.sqs_client, **kwargs)
+
+    def send_message_batch(self, **kwargs) -> Dict[str, Any]:
+        """Send message batch with trace IDs"""
+        return send_message_batch_with_trace(self.sqs_client, **kwargs)
+
+    def __getattr__(self, name):
+        """Delegate other methods to the wrapped client"""
+        return getattr(self.sqs_client, name)

goldcast_cl_logger-0.2.8/cl_logger/trace_context.py

@@ -0,0 +1,71 @@
+"""
+Trace context management for distributed tracing
+"""
+import contextvars
+import uuid
+from typing import Any, Dict, Optional
+
+# Context variable to store the current trace ID
+_trace_id_var: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "trace_id", default=None
+)
+
+# Context variable to store additional trace metadata
+_trace_metadata_var: contextvars.ContextVar[Dict[str, Any]] = contextvars.ContextVar(
+    "trace_metadata", default={}
+)
+
+TRACE_ID_HEADER = "X-Trace-Id"
+SENTRY_TRACE_HEADER = "sentry-trace"
+
+
+def generate_trace_id() -> str:
+    """Generate a new trace ID"""
+    return str(uuid.uuid4())
+
+
+def get_trace_id() -> Optional[str]:
+    """Get the current trace ID from context"""
+    return _trace_id_var.get()
+
+
+def set_trace_id(trace_id: str) -> None:
+    """Set the trace ID in context"""
+    _trace_id_var.set(trace_id)
+
+
+def get_trace_metadata() -> Dict[str, Any]:
+    """Get additional trace metadata"""
+    return _trace_metadata_var.get().copy()
+
+
+def set_trace_metadata(metadata: Dict[str, Any]) -> None:
+    """Set additional trace metadata"""
+    _trace_metadata_var.set(metadata)
+
+
+def add_trace_metadata(key: str, value: Any) -> None:
+    """Add a single metadata item to trace context"""
+    metadata = get_trace_metadata()
+    metadata[key] = value
+    set_trace_metadata(metadata)
+
+
+class TraceContext:
+    """Context manager for trace ID handling"""
+
+    def __init__(self, trace_id: Optional[str] = None):
+        self.trace_id = trace_id or generate_trace_id()
+        self.token = None
+        self.metadata_token = None
+
+    def __enter__(self):
+        self.token = _trace_id_var.set(self.trace_id)
+        self.metadata_token = _trace_metadata_var.set({})
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.token:
+            _trace_id_var.reset(self.token)
+        if self.metadata_token:
+            _trace_metadata_var.reset(self.metadata_token)

goldcast_cl_logger-0.2.8/pyproject.toml

@@ -0,0 +1,38 @@
+[tool.poetry]
+name = "goldcast-cl-logger"
+version = "0.2.8"
+description = "A lightweight, flexible logging library for Content Lab projects with distributed tracing support"
+authors = ["Goldcast <engineering@goldcast.io>"]
+readme = "README.md"
+packages = [{include = "cl_logger"}]
+license = "MIT"
+repository = "https://github.com/goldcast/content-lab-backend"
+documentation = "https://github.com/goldcast/content-lab-backend/tree/main/libraries/cl-logger"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Logging"
+]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+requests = { version = "^2.31.0", optional = true }
+
+[tool.poetry.extras]
+http = ["requests"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/goldcast/content-lab-backend/issues"
+"Source Code" = "https://github.com/goldcast/content-lab-backend/tree/main/libraries/cl-logger"
+
+[tool.poetry.scripts]