|
| 1 | +# -*- coding: utf-8 -*- |
| 2 | +""" |
| 3 | +Centralized Error Handling Utilities |
| 4 | +===================================== |
| 5 | +Provides consistent error logging, global exception handlers, and |
| 6 | +optional error snapshot integration for robust debugging. |
| 7 | +""" |
| 8 | + |
| 9 | +import asyncio |
| 10 | +import logging |
| 11 | +import threading |
| 12 | +from typing import Optional |
| 13 | + |
| 14 | +from .context import request_id_var, source_var |
| 15 | + |
| 16 | + |
| 17 | +def log_error( |
| 18 | + logger: logging.Logger, |
| 19 | + message: str, |
| 20 | + exception: Optional[BaseException] = None, |
| 21 | + *, |
| 22 | + save_snapshot: bool = False, |
| 23 | + req_id: str = "", |
| 24 | + exc_info: bool = True, |
| 25 | +) -> None: |
| 26 | + """ |
| 27 | + Centralized error logging with automatic stack trace capture. |
| 28 | +
|
| 29 | + This function ensures consistent error logging across the codebase: |
| 30 | + - Always includes exc_info for full stack traces |
| 31 | + - Optionally saves error snapshots for debugging |
| 32 | + - Integrates with request context for tracing |
| 33 | +
|
| 34 | + Args: |
| 35 | + logger: Logger instance to use |
| 36 | + message: Error message to log |
| 37 | + exception: Optional exception object (used for snapshot) |
| 38 | + save_snapshot: Whether to save an error snapshot (screenshot, DOM, etc.) |
| 39 | + req_id: Optional request ID override (uses context var if empty) |
| 40 | + exc_info: Whether to include exception info (default True) |
| 41 | +
|
| 42 | + Usage: |
| 43 | + try: |
| 44 | + risky_operation() |
| 45 | + except Exception as e: |
| 46 | + log_error(logger, f"Operation failed: {e}", e, save_snapshot=True) |
| 47 | + """ |
| 48 | + # Get request ID from context if not provided |
| 49 | + if not req_id: |
| 50 | + try: |
| 51 | + req_id = request_id_var.get() |
| 52 | + except LookupError: |
| 53 | + req_id = "unknown" |
| 54 | + |
| 55 | + # Log with exc_info for full stack trace |
| 56 | + logger.error(message, exc_info=exc_info) |
| 57 | + |
| 58 | + # Save error snapshot if requested |
| 59 | + if save_snapshot: |
| 60 | + try: |
| 61 | + # Lazy import to avoid circular dependencies |
| 62 | + from browser_utils.debug_utils import save_error_snapshot_enhanced |
| 63 | + |
| 64 | + # Generate error name from message (first 30 chars, sanitized) |
| 65 | + error_name = ( |
| 66 | + message[:30].replace(" ", "_").replace(":", "").replace("/", "_") |
| 67 | + ) |
| 68 | + # This is async, but we're in sync context - schedule it |
| 69 | + try: |
| 70 | + loop = asyncio.get_running_loop() |
| 71 | + loop.create_task( |
| 72 | + save_error_snapshot_enhanced( |
| 73 | + error_name=error_name, |
| 74 | + error_exception=exception |
| 75 | + if isinstance(exception, Exception) |
| 76 | + else None, |
| 77 | + error_stage="log_error", |
| 78 | + ) |
| 79 | + ) |
| 80 | + except RuntimeError: |
| 81 | + # No running event loop - can't save async snapshot |
| 82 | + logger.debug("Cannot save error snapshot: no running event loop") |
| 83 | + except ImportError: |
| 84 | + # debug_utils not available (e.g., in tests or standalone mode) |
| 85 | + pass |
| 86 | + except Exception as snapshot_err: |
| 87 | + # Don't let snapshot failures break the main error handling |
| 88 | + logger.debug(f"Failed to save error snapshot: {snapshot_err}") |
| 89 | + |
| 90 | + |
| 91 | +def _asyncio_exception_handler(loop: asyncio.AbstractEventLoop, context: dict) -> None: |
| 92 | + """ |
| 93 | + Global asyncio exception handler for uncaught exceptions in tasks. |
| 94 | +
|
| 95 | + This catches exceptions that would otherwise be silently ignored when: |
| 96 | + - A Task raises an exception but is never awaited |
| 97 | + - A callback raises an exception |
| 98 | +
|
| 99 | + Args: |
| 100 | + loop: The event loop that caught the exception |
| 101 | + context: Exception context dict with 'message', 'exception', etc. |
| 102 | + """ |
| 103 | + logger = logging.getLogger("AIStudioProxyServer") |
| 104 | + |
| 105 | + # Extract exception info |
| 106 | + exception = context.get("exception") |
| 107 | + message = context.get("message", "Unhandled exception in asyncio task") |
| 108 | + |
| 109 | + # Get additional context |
| 110 | + task = context.get("task") |
| 111 | + future = context.get("future") |
| 112 | + |
| 113 | + # Build detailed error message |
| 114 | + error_parts = [f"[ASYNCIO EXCEPTION] {message}"] |
| 115 | + |
| 116 | + if task is not None: |
| 117 | + error_parts.append( |
| 118 | + f"Task: {task.get_name() if hasattr(task, 'get_name') else repr(task)}" |
| 119 | + ) |
| 120 | + |
| 121 | + if future is not None and future is not task: |
| 122 | + error_parts.append(f"Future: {repr(future)}") |
| 123 | + |
| 124 | + # Get source from context if available |
| 125 | + try: |
| 126 | + source = source_var.get() |
| 127 | + error_parts.append(f"Source: {source}") |
| 128 | + except LookupError: |
| 129 | + pass |
| 130 | + |
| 131 | + try: |
| 132 | + req_id = request_id_var.get() |
| 133 | + if req_id.strip(): |
| 134 | + error_parts.append(f"Request ID: {req_id}") |
| 135 | + except LookupError: |
| 136 | + pass |
| 137 | + |
| 138 | + full_message = " | ".join(error_parts) |
| 139 | + |
| 140 | + if exception is not None: |
| 141 | + # Log with full traceback |
| 142 | + logger.error( |
| 143 | + full_message, exc_info=(type(exception), exception, exception.__traceback__) |
| 144 | + ) |
| 145 | + else: |
| 146 | + logger.error(full_message) |
| 147 | + |
| 148 | + |
| 149 | +def _threading_exception_handler(args: threading.ExceptHookArgs) -> None: |
| 150 | + """ |
| 151 | + Global threading exception handler for uncaught exceptions in threads. |
| 152 | +
|
| 153 | + Args: |
| 154 | + args: ExceptHookArgs containing exc_type, exc_value, exc_traceback, thread |
| 155 | + """ |
| 156 | + logger = logging.getLogger("AIStudioProxyServer") |
| 157 | + |
| 158 | + thread_name = args.thread.name if args.thread else "unknown" |
| 159 | + |
| 160 | + error_message = f"[THREAD EXCEPTION] Uncaught exception in thread '{thread_name}'" |
| 161 | + |
| 162 | + if args.exc_value is not None: |
| 163 | + logger.error( |
| 164 | + error_message, |
| 165 | + exc_info=(args.exc_type, args.exc_value, args.exc_traceback), |
| 166 | + ) |
| 167 | + else: |
| 168 | + logger.error(error_message) |
| 169 | + |
| 170 | + |
| 171 | +def setup_global_exception_handlers( |
| 172 | + *, install_asyncio: bool = True, install_threading: bool = True |
| 173 | +) -> None: |
| 174 | + """ |
| 175 | + Install global exception handlers for asyncio and threading. |
| 176 | +
|
| 177 | + This ensures that uncaught exceptions in background tasks and threads |
| 178 | + are properly logged instead of being silently ignored. |
| 179 | +
|
| 180 | + Should be called once during application startup. |
| 181 | +
|
| 182 | + Args: |
| 183 | + install_asyncio: Install asyncio exception handler |
| 184 | + install_threading: Install threading exception handler |
| 185 | +
|
| 186 | + Usage: |
| 187 | + # In application startup |
| 188 | + setup_global_exception_handlers() |
| 189 | + """ |
| 190 | + logger = logging.getLogger("AIStudioProxyServer") |
| 191 | + |
| 192 | + if install_asyncio: |
| 193 | + try: |
| 194 | + loop = asyncio.get_running_loop() |
| 195 | + loop.set_exception_handler(_asyncio_exception_handler) |
| 196 | + logger.debug("Installed asyncio global exception handler") |
| 197 | + except RuntimeError: |
| 198 | + # No running event loop yet - will be installed when loop starts |
| 199 | + # This is common during module import |
| 200 | + pass |
| 201 | + |
| 202 | + if install_threading: |
| 203 | + # Python 3.8+ |
| 204 | + if hasattr(threading, "excepthook"): |
| 205 | + threading.excepthook = _threading_exception_handler |
| 206 | + logger.debug("Installed threading global exception handler") |
| 207 | + |
| 208 | + |
| 209 | +def install_asyncio_handler_on_loop(loop: asyncio.AbstractEventLoop) -> None: |
| 210 | + """ |
| 211 | + Install the asyncio exception handler on a specific event loop. |
| 212 | +
|
| 213 | + Use this when you need to install the handler after the loop is created. |
| 214 | +
|
| 215 | + Args: |
| 216 | + loop: The event loop to install the handler on |
| 217 | + """ |
| 218 | + loop.set_exception_handler(_asyncio_exception_handler) |
0 commit comments