refactor(logging): separate detailed failure logs from main stream

This refactoring separates comprehensive failure event logging into a dedicated file, preventing them from cluttering the main application logs.

- Establish a dedicated `failure_logger` for detailed, structured JSON logs written to `failures.log`. This logger does not propagate messages to the root logger.
- Modify `log_failure` to send complete failure context (including timestamp, error details, and request data) to the new `failure_logger`.
- Continue logging a concise summary of failures to the `rotator_library`'s main logger for high-level monitoring.
- Update the JSON formatter to directly handle pre-structured dictionary messages, simplifying log record creation.

src/rotator_library/failure_logger.py

@@ -2,57 +2,58 @@ import logging
 import json
 from logging.handlers import RotatingFileHandler
 import os
+from datetime import datetime
 
 def setup_failure_logger():
-    """Sets up a dedicated JSON logger for failed API calls."""
+    """Sets up a dedicated JSON logger for writing detailed failure logs to a file."""
     log_dir = "logs"
     if not os.path.exists(log_dir):
         os.makedirs(log_dir)
 
-    # Use the same named logger as the rest of the library
-    logger = logging.getLogger('rotator_library')
-    logger.setLevel(logging.INFO) # Set to INFO to capture all levels
-    
-    # Prevent logs from propagating to the root logger
+    # Create a logger specifically for failures.
+    # This logger will NOT propagate to the root logger.
+    logger = logging.getLogger('failure_logger')
+    logger.setLevel(logging.INFO)
     logger.propagate = False
 
-    # Use a rotating file handler to keep log files from growing too large
+    # Use a rotating file handler
     handler = RotatingFileHandler(
         os.path.join(log_dir, 'failures.log'),
         maxBytes=5*1024*1024,  # 5 MB
         backupCount=2
     )
 
-    # Custom JSON formatter
+    # Custom JSON formatter for structured logs
     class JsonFormatter(logging.Formatter):
         def format(self, record):
-            log_record = {
-                "timestamp": self.formatTime(record, self.datefmt),
-                "level": record.levelname,
-                "message": record.getMessage()
-            }
-            return json.dumps(log_record)
+            # The message is already a dict, so we just format it as a JSON string
+            return json.dumps(record.msg)
 
     handler.setFormatter(JsonFormatter())
     
-    # Add handler only if it hasn't been added before, and is not a NullHandler
-    if not any(isinstance(h, RotatingFileHandler) for h in logger.handlers):
+    # Add handler only if it hasn't been added before
+    if not logger.handlers:
         logger.addHandler(handler)
 
     return logger
 
-# Initialize the logger for failures
+# Initialize the dedicated logger for detailed failure logs
 failure_logger = setup_failure_logger()
 
+# Get the main library logger for concise, propagated messages
+main_lib_logger = logging.getLogger('rotator_library')
+
 def log_failure(api_key: str, model: str, attempt: int, error: Exception, request_data: dict):
-    """Logs a structured message for a failed API call."""
-    
-    # Try to get the raw response from the exception if it exists
+    """
+    Logs a detailed failure message to a file and a concise summary to the main logger.
+    """
+    # 1. Log the full, detailed error to the dedicated failures.log file
     raw_response = None
     if hasattr(error, 'response') and hasattr(error.response, 'text'):
         raw_response = error.response.text
 
-    log_data = {
+    detailed_log_data = {
+        "timestamp": datetime.utcnow().isoformat(),
         "api_key_ending": api_key[-4:],
         "model": model,
         "attempt_number": attempt,
@@ -61,4 +62,11 @@ def log_failure(api_key: str, model: str, attempt: int, error: Exception, reques
         "raw_response": raw_response,
         "request_data": request_data,
     }
-    failure_logger.error(log_data)
+    failure_logger.error(detailed_log_data)
+
+    # 2. Log a concise summary to the main library logger, which will propagate
+    summary_message = (
+        f"API call failed for model {model} with key ...{api_key[-4:]}. "
+        f"Error: {type(error).__name__}. See failures.log for details."
+    )
+    main_lib_logger.error(summary_message)