x-ipe 1.0.24__py3-none-any.whl → 1.0.25__py3-none-any.whl

x_ipe/tracing/buffer.py

@@ -0,0 +1,135 @@
+"""
+FEATURE-023: Application Action Tracing - Core
+
+TraceBuffer and TraceEntry for in-memory trace storage.
+
+Traces are collected in-memory during request execution and flushed
+to log files upon request completion.
+"""
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import List, Optional, Any
+import json
+
+
+@dataclass
+class TraceEntry:
+    """
+    Single trace log entry representing a function call event.
+    
+    Attributes:
+        timestamp: When the event occurred
+        trace_id: Unique identifier for the trace
+        level: Log level (INFO, DEBUG, ERROR)
+        direction: Arrow direction (→ for entry, ← for exit)
+        event_type: Type of event (start_function, return_function, exception)
+        function_name: Name of the traced function
+        data: Parameters, return value, or error details
+        duration_ms: Execution time in milliseconds (only for exit events)
+        depth: Nesting level (0 = root)
+    """
+    timestamp: datetime
+    trace_id: str
+    level: str
+    direction: str
+    event_type: str
+    function_name: str
+    data: dict
+    duration_ms: Optional[float] = None
+    depth: int = 0
+
+
+class TraceBuffer:
+    """
+    In-memory buffer for trace entries during request execution.
+    
+    Collects trace entries and formats them for log file output.
+    Enforces a maximum size limit to prevent memory exhaustion.
+    
+    Usage:
+        buffer = TraceBuffer("abc-123", "POST /api/orders")
+        buffer.add(TraceEntry(...))
+        log_content = buffer.to_log_string("SUCCESS", 150.0)
+    """
+    
+    MAX_SIZE = 10 * 1024 * 1024  # 10MB limit
+    
+    def __init__(self, trace_id: str, root_api: str):
+        """
+        Initialize TraceBuffer.
+        
+        Args:
+            trace_id: Unique identifier for this trace
+            root_api: The root API call (e.g., "POST /api/orders")
+        """
+        self.trace_id = trace_id
+        self.root_api = root_api
+        self.started_at = datetime.now(timezone.utc)
+        self.entries: List[TraceEntry] = []
+        self._size = 0
+    
+    def add(self, entry: TraceEntry) -> None:
+        """
+        Add a trace entry to the buffer.
+        
+        Silently drops entries if buffer size limit is exceeded.
+        
+        Args:
+            entry: TraceEntry to add
+        """
+        try:
+            entry_size = len(json.dumps(entry.data, default=str))
+        except (TypeError, ValueError):
+            entry_size = 100  # Fallback size estimate
+        
+        if self._size + entry_size > self.MAX_SIZE:
+            return  # Silently drop if buffer full
+        
+        self.entries.append(entry)
+        self._size += entry_size
+    
+    def to_log_string(self, status: str, total_ms: float) -> str:
+        """
+        Format the buffer as a log file string.
+        
+        Args:
+            status: Final status (SUCCESS, ERROR)
+            total_ms: Total execution time in milliseconds
+            
+        Returns:
+            Formatted log string ready for file output
+        """
+        lines = [
+            f"[TRACE-START] {self.trace_id} | {self.root_api} | {self.started_at.isoformat()}Z"
+        ]
+        
+        for entry in self.entries:
+            indent = "  " * (entry.depth + 1)
+            
+            try:
+                data_str = json.dumps(entry.data, default=str, ensure_ascii=False)
+            except (TypeError, ValueError):
+                data_str = str(entry.data)
+            
+            # Truncate very long data
+            if len(data_str) > 1000:
+                data_str = data_str[:997] + "..."
+            
+            if entry.duration_ms is not None:
+                line = (
+                    f"{indent}[{entry.level}] {entry.direction} {entry.event_type}: "
+                    f"{entry.function_name} | {data_str} | {entry.duration_ms:.0f}ms"
+                )
+            else:
+                line = (
+                    f"{indent}[{entry.level}] {entry.direction} {entry.event_type}: "
+                    f"{entry.function_name} | {data_str}"
+                )
+            
+            lines.append(line)
+        
+        lines.append(
+            f"[TRACE-END] {self.trace_id} | {total_ms:.0f}ms | {status}"
+        )
+        
+        return "\n".join(lines)

x_ipe/tracing/context.py

@@ -0,0 +1,125 @@
+"""
+FEATURE-023: Application Action Tracing - Core
+
+TraceContext for thread-safe context propagation using contextvars.
+
+Manages the active trace context across nested function calls,
+ensuring trace ID propagation and proper nesting depth tracking.
+"""
+from contextvars import ContextVar
+from typing import Optional, List
+import uuid
+
+from .buffer import TraceBuffer
+
+
+# Thread-safe context variable for the active trace
+_trace_context: ContextVar[Optional['TraceContext']] = ContextVar(
+    'trace_context', 
+    default=None
+)
+
+
+class TraceContext:
+    """
+    Thread-safe trace context manager.
+    
+    Uses Python's contextvars to maintain trace state across async
+    function calls. Tracks trace ID, buffer, and call depth.
+    
+    Usage:
+        # Start a new trace
+        ctx = TraceContext.start_trace("POST /api/orders")
+        
+        # Get current context (in nested calls)
+        ctx = TraceContext.get_current()
+        
+        # End trace and get buffer
+        buffer = TraceContext.end_trace()
+    """
+    
+    def __init__(self, trace_id: str, root_api: str):
+        """
+        Initialize TraceContext.
+        
+        Args:
+            trace_id: Unique identifier for this trace
+            root_api: The root API call (e.g., "POST /api/orders")
+        """
+        self.trace_id = trace_id
+        self.buffer = TraceBuffer(trace_id, root_api)
+        self.depth = 0
+        self._call_stack: List[str] = []
+    
+    @classmethod
+    def start_trace(cls, root_api: str) -> 'TraceContext':
+        """
+        Start a new trace.
+        
+        Generates a unique trace ID and creates a new context.
+        Sets the context as the active trace.
+        
+        Args:
+            root_api: The root API call (e.g., "POST /api/orders")
+            
+        Returns:
+            New TraceContext instance
+        """
+        # Generate short UUID for readability (first 13 chars)
+        trace_id = str(uuid.uuid4())[:13]
+        ctx = cls(trace_id, root_api)
+        _trace_context.set(ctx)
+        return ctx
+    
+    @classmethod
+    def get_current(cls) -> Optional['TraceContext']:
+        """
+        Get the current active trace context.
+        
+        Returns:
+            Active TraceContext or None if no trace is active
+        """
+        return _trace_context.get()
+    
+    @classmethod
+    def end_trace(cls) -> Optional[TraceBuffer]:
+        """
+        End the current trace and return the buffer.
+        
+        Clears the active context.
+        
+        Returns:
+            TraceBuffer containing all trace entries, or None if no active trace
+        """
+        ctx = _trace_context.get()
+        if ctx:
+            _trace_context.set(None)
+            return ctx.buffer
+        return None
+    
+    def push_call(self, func_name: str) -> int:
+        """
+        Push a function call onto the stack.
+        
+        Increments depth and tracks the function name.
+        
+        Args:
+            func_name: Name of the function being called
+            
+        Returns:
+            Depth level before increment (for logging)
+        """
+        self._call_stack.append(func_name)
+        depth = self.depth
+        self.depth += 1
+        return depth
+    
+    def pop_call(self) -> None:
+        """
+        Pop a function call from the stack.
+        
+        Decrements depth and removes the function from tracking.
+        """
+        if self._call_stack:
+            self._call_stack.pop()
+            self.depth -= 1

x_ipe/tracing/decorator.py

@@ -0,0 +1,288 @@
+"""
+FEATURE-023: Application Action Tracing - Core
+
+@x_ipe_tracing decorator for automatic function tracing.
+
+Provides a decorator that automatically logs function entry, exit,
+return values, and exceptions with execution timing.
+"""
+import functools
+import time
+import asyncio
+import inspect
+from datetime import datetime, timezone
+from typing import Callable, List, Optional, Any, Dict
+
+from .context import TraceContext
+from .buffer import TraceEntry
+from .redactor import Redactor
+
+
+def x_ipe_tracing(
+    level: str = "INFO",
+    redact: Optional[List[str]] = None
+) -> Callable:
+    """
+    Decorator for automatic function tracing.
+    
+    Logs function entry with parameters, exit with return value,
+    and any exceptions that occur. Automatically redacts sensitive data.
+    
+    Args:
+        level: Log level - "INFO", "DEBUG", or "SKIP"
+        redact: List of parameter names to redact (in addition to built-in patterns)
+    
+    Usage:
+        @x_ipe_tracing(level="INFO", redact=["password"])
+        def create_user(email: str, password: str) -> dict:
+            ...
+    
+    Returns:
+        Decorated function that traces execution
+    """
+    if level == "SKIP":
+        return lambda fn: fn  # No-op decorator
+    
+    redactor = Redactor(custom_fields=redact)
+    
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            ctx = TraceContext.get_current()
+            if not ctx:
+                return func(*args, **kwargs)  # No active trace
+            
+            return _trace_call(ctx, func, args, kwargs, level, redactor)
+        
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            ctx = TraceContext.get_current()
+            if not ctx:
+                return await func(*args, **kwargs)  # No active trace
+            
+            return await _trace_call_async(ctx, func, args, kwargs, level, redactor)
+        
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        return sync_wrapper
+    
+    return decorator
+
+
+def _extract_params(func: Callable, args: tuple, kwargs: dict) -> Dict[str, Any]:
+    """
+    Extract function parameters as a dictionary.
+    
+    Uses function signature to map positional args to parameter names.
+    
+    Args:
+        func: The function being called
+        args: Positional arguments
+        kwargs: Keyword arguments
+        
+    Returns:
+        Dictionary of parameter names to values
+    """
+    params = {}
+    
+    try:
+        sig = inspect.signature(func)
+        param_names = list(sig.parameters.keys())
+        
+        # Map positional args
+        for i, arg in enumerate(args):
+            if i < len(param_names):
+                # Skip 'self' and 'cls' parameters
+                param_name = param_names[i]
+                if param_name not in ('self', 'cls'):
+                    params[param_name] = arg
+            else:
+                params[f"arg_{i}"] = arg
+        
+        # Add keyword args
+        params.update(kwargs)
+    except (ValueError, TypeError):
+        # Fallback if signature introspection fails
+        for i, arg in enumerate(args):
+            params[f"arg_{i}"] = arg
+        params.update(kwargs)
+    
+    return params
+
+
+def _safe_serialize(value: Any) -> Any:
+    """
+    Safely serialize a value for logging.
+    
+    Handles circular references and non-serializable objects.
+    
+    Args:
+        value: Value to serialize
+        
+    Returns:
+        Serializable representation of the value
+    """
+    try:
+        # Try direct serialization
+        import json
+        json.dumps(value, default=str)
+        return value
+    except (TypeError, ValueError, RecursionError):
+        # Fallback for complex objects
+        return str(value)[:500]
+
+
+def _trace_call(
+    ctx: TraceContext,
+    func: Callable,
+    args: tuple,
+    kwargs: dict,
+    level: str,
+    redactor: Redactor
+) -> Any:
+    """
+    Trace a synchronous function call.
+    
+    Logs entry, executes the function, logs exit or exception.
+    """
+    func_name = func.__name__
+    depth = ctx.push_call(func_name)
+    
+    # Extract and redact parameters
+    params = _extract_params(func, args, kwargs)
+    redacted_params = redactor.redact(params)
+    
+    # Log entry
+    ctx.buffer.add(TraceEntry(
+        timestamp=datetime.now(timezone.utc),
+        trace_id=ctx.trace_id,
+        level=level,
+        direction="→",
+        event_type="start_function",
+        function_name=func_name,
+        data=_safe_serialize(redacted_params),
+        depth=depth
+    ))
+    
+    start = time.perf_counter()
+    try:
+        result = func(*args, **kwargs)
+        duration = (time.perf_counter() - start) * 1000
+        
+        # Redact and serialize return value
+        redacted_result = redactor.redact({"return": _safe_serialize(result)})
+        
+        # Log success
+        ctx.buffer.add(TraceEntry(
+            timestamp=datetime.now(timezone.utc),
+            trace_id=ctx.trace_id,
+            level=level,
+            direction="←",
+            event_type="return_function",
+            function_name=func_name,
+            data=redacted_result,
+            duration_ms=duration,
+            depth=depth
+        ))
+        return result
+        
+    except Exception as e:
+        duration = (time.perf_counter() - start) * 1000
+        
+        # Log error
+        ctx.buffer.add(TraceEntry(
+            timestamp=datetime.now(timezone.utc),
+            trace_id=ctx.trace_id,
+            level="ERROR",
+            direction="←",
+            event_type="exception",
+            function_name=func_name,
+            data={
+                "error": type(e).__name__,
+                "message": str(e)
+            },
+            duration_ms=duration,
+            depth=depth
+        ))
+        raise
+        
+    finally:
+        ctx.pop_call()
+
+
+async def _trace_call_async(
+    ctx: TraceContext,
+    func: Callable,
+    args: tuple,
+    kwargs: dict,
+    level: str,
+    redactor: Redactor
+) -> Any:
+    """
+    Trace an asynchronous function call.
+    
+    Logs entry, awaits the function, logs exit or exception.
+    """
+    func_name = func.__name__
+    depth = ctx.push_call(func_name)
+    
+    # Extract and redact parameters
+    params = _extract_params(func, args, kwargs)
+    redacted_params = redactor.redact(params)
+    
+    # Log entry
+    ctx.buffer.add(TraceEntry(
+        timestamp=datetime.now(timezone.utc),
+        trace_id=ctx.trace_id,
+        level=level,
+        direction="→",
+        event_type="start_function",
+        function_name=func_name,
+        data=_safe_serialize(redacted_params),
+        depth=depth
+    ))
+    
+    start = time.perf_counter()
+    try:
+        result = await func(*args, **kwargs)
+        duration = (time.perf_counter() - start) * 1000
+        
+        # Redact and serialize return value
+        redacted_result = redactor.redact({"return": _safe_serialize(result)})
+        
+        # Log success
+        ctx.buffer.add(TraceEntry(
+            timestamp=datetime.now(timezone.utc),
+            trace_id=ctx.trace_id,
+            level=level,
+            direction="←",
+            event_type="return_function",
+            function_name=func_name,
+            data=redacted_result,
+            duration_ms=duration,
+            depth=depth
+        ))
+        return result
+        
+    except Exception as e:
+        duration = (time.perf_counter() - start) * 1000
+        
+        # Log error
+        ctx.buffer.add(TraceEntry(
+            timestamp=datetime.now(timezone.utc),
+            trace_id=ctx.trace_id,
+            level="ERROR",
+            direction="←",
+            event_type="exception",
+            function_name=func_name,
+            data={
+                "error": type(e).__name__,
+                "message": str(e)
+            },
+            duration_ms=duration,
+            depth=depth
+        ))
+        raise
+        
+    finally:
+        ctx.pop_call()