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

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()

x_ipe/tracing/middleware.py

@@ -0,0 +1,197 @@
+"""
+FEATURE-023: Application Action Tracing - Middleware
+
+Flask middleware for automatic request tracing.
+
+Creates TraceContext for each request when tracing is active,
+then writes the trace log file after the request completes.
+"""
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from flask import Flask, request, g
+from typing import List
+
+from .context import TraceContext
+from .writer import TraceLogWriter
+
+
+# APIs to ignore (to avoid infinite loops and noise)
+IGNORED_API_PREFIXES = (
+    '/api/tracing/',      # Tracing APIs themselves
+    '/static/',           # Static files
+    '/socket.io/',        # WebSocket
+)
+
+
+def init_tracing_middleware(app: Flask) -> None:
+    """
+    Initialize tracing middleware for a Flask app.
+    
+    Registers before_request and after_request hooks that:
+    - Check if tracing is active
+    - Start TraceContext before each request
+    - End TraceContext and write log file after each request
+    
+    Args:
+        app: Flask application instance
+    """
+    
+    @app.before_request
+    def start_trace():
+        """Start trace context if tracing is active."""
+        # Skip hardcoded ignored paths (system paths)
+        if request.path.startswith(IGNORED_API_PREFIXES):
+            return
+        
+        # Check if tracing is active and get config
+        project_root = app.config.get('PROJECT_ROOT', '.')
+        active, ignored_apis = _get_tracing_config(project_root)
+        
+        if not active:
+            return
+        
+        # Skip user-configured ignored APIs
+        if _is_path_ignored(request.path, ignored_apis):
+            return
+        
+        # Start trace context
+        api_name = f"{request.method} {request.path}"
+        TraceContext.start_trace(api_name)
+        g.trace_start_time = time.perf_counter()
+    
+    @app.after_request
+    def end_trace(response):
+        """End trace context and write log file."""
+        # Check if we started a trace
+        if not hasattr(g, 'trace_start_time'):
+            return response
+        
+        # End the trace
+        buffer = TraceContext.end_trace()
+        if buffer is None:
+            return response
+        
+        # Determine status from response
+        status = "SUCCESS" if response.status_code < 400 else "ERROR"
+        
+        # Get log path from config
+        project_root = app.config.get('PROJECT_ROOT', '.')
+        log_path = _get_trace_log_path(project_root)
+        
+        # Write trace to file
+        writer = TraceLogWriter(log_path)
+        writer.write(buffer, status)
+        
+        return response
+    
+    @app.teardown_request
+    def cleanup_trace(exception=None):
+        """Clean up trace context on error."""
+        if exception is not None:
+            buffer = TraceContext.end_trace()
+            if buffer is not None:
+                project_root = app.config.get('PROJECT_ROOT', '.')
+                log_path = _get_trace_log_path(project_root)
+                writer = TraceLogWriter(log_path)
+                writer.write(buffer, "ERROR")
+
+
+def _get_tracing_config(project_root: str) -> tuple:
+    """
+    Get tracing configuration including active status and ignored APIs.
+    
+    Reads from tools.json to check tracing_enabled, tracing_stop_at,
+    and tracing_ignored_apis.
+    
+    Args:
+        project_root: Path to project root
+        
+    Returns:
+        Tuple of (is_active: bool, ignored_apis: List[str])
+    """
+    import json
+    
+    tools_path = Path(project_root) / "x-ipe-docs" / "config" / "tools.json"
+    if not tools_path.exists():
+        return False, []
+    
+    try:
+        with open(tools_path) as f:
+            config = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return False, []
+    
+    ignored_apis = config.get("tracing_ignored_apis", [])
+    
+    # Check if explicitly enabled
+    if config.get("tracing_enabled", False):
+        return True, ignored_apis
+    
+    # Check if stop_at is in the future
+    stop_at = config.get("tracing_stop_at")
+    if stop_at:
+        try:
+            # Keep timezone-aware for proper comparison
+            stop_time = datetime.fromisoformat(
+                stop_at.replace("Z", "+00:00")
+            )
+            if datetime.now(timezone.utc) < stop_time:
+                return True, ignored_apis
+        except (ValueError, AttributeError):
+            pass
+    
+    return False, ignored_apis
+
+
+def _is_path_ignored(path: str, ignored_apis: List[str]) -> bool:
+    """
+    Check if a request path matches any user-configured ignored API patterns.
+    
+    Supports exact matches and prefix matches (patterns ending with *).
+    
+    Args:
+        path: Request path (e.g., "/api/project/structure")
+        ignored_apis: List of API patterns to ignore
+        
+    Returns:
+        True if path should be ignored
+    """
+    for pattern in ignored_apis:
+        if pattern.endswith('*'):
+            # Prefix match
+            if path.startswith(pattern[:-1]):
+                return True
+        else:
+            # Exact match
+            if path == pattern:
+                return True
+    return False
+
+
+def _get_trace_log_path(project_root: str) -> str:
+    """
+    Get the trace log directory path.
+    
+    Reads from tools.json or uses default.
+    
+    Args:
+        project_root: Path to project root
+        
+    Returns:
+        Absolute path to trace log directory
+    """
+    import json
+    
+    tools_path = Path(project_root) / "x-ipe-docs" / "config" / "tools.json"
+    log_path = "instance/traces/"
+    
+    if tools_path.exists():
+        try:
+            with open(tools_path) as f:
+                config = json.load(f)
+                log_path = config.get("tracing_log_path", log_path)
+        except (json.JSONDecodeError, IOError):
+            pass
+    
+    return str(Path(project_root) / log_path)