aws-lambda-powertools 3.7.1a7__py3-none-any.whl → 3.8.1a0__py3-none-any.whl

aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -136,9 +136,8 @@ class OpenAPIValidationMiddleware(BaseMiddlewareHandler):
             return self._handle_response(route=route, response=response)
 
     def _handle_response(self, *, route: Route, response: Response):
-        # Check if we have a return type defined
-        if route.dependant.return_param:
-            # Validate and serialize the response, including None
+        # Process the response body if it exists
+        if response.body and response.is_json():
             response.body = self._serialize_response(
                 field=route.dependant.return_param,
                 response_content=response.body,

aws_lambda_powertools/logging/buffer/__init__.py

@@ -0,0 +1,3 @@
+from aws_lambda_powertools.logging.buffer.config import LoggerBufferConfig
+
+__all__ = ["LoggerBufferConfig"]

aws_lambda_powertools/logging/buffer/cache.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from collections import deque
+from typing import Any
+
+
+class KeyBufferCache:
+    """
+    A cache implementation for a single key with size tracking and eviction support.
+
+    This class manages a buffer for a specific key, keeping track of the current size
+    and providing methods to add, remove, and manage cached items. It supports automatic
+    eviction tracking and size management.
+
+    Attributes
+    ----------
+    cache : deque
+        A double-ended queue storing the cached items.
+    current_size : int
+        The total size of all items currently in the cache.
+    has_evicted : bool
+        A flag indicating whether any items have been evicted from the cache.
+    """
+
+    def __init__(self):
+        """
+        Initialize a buffer cache for a specific key.
+        """
+        self.cache: deque = deque()
+        self.current_size: int = 0
+        self.has_evicted: bool = False
+
+    def add(self, item: Any) -> None:
+        """
+        Add an item to the cache.
+
+        Parameters
+        ----------
+        item : Any
+            The item to be stored in the cache.
+        """
+        item_size = len(str(item))
+        self.cache.append(item)
+        self.current_size += item_size
+
+    def remove_oldest(self) -> Any:
+        """
+        Remove and return the oldest item from the cache.
+
+        Returns
+        -------
+        Any
+            The removed item.
+        """
+        removed_item = self.cache.popleft()
+        self.current_size -= len(str(removed_item))
+        self.has_evicted = True
+        return removed_item
+
+    def get(self) -> list:
+        """
+        Retrieve items for this key.
+
+        Returns
+        -------
+        list
+            List of items in the cache.
+        """
+        return list(self.cache)
+
+    def clear(self) -> None:
+        """
+        Clear the cache for this key.
+        """
+        self.cache.clear()
+        self.current_size = 0
+        self.has_evicted = False
+
+
+class LoggerBufferCache:
+    """
+    A multi-key buffer cache with size-based eviction and management.
+
+    This class provides a flexible caching mechanism that manages multiple keys,
+    with each key having its own buffer cache. The total size of each key's cache
+    is limited, and older items are automatically evicted when the size limit is reached.
+
+    Key Features:
+    - Multiple key support
+    - Size-based eviction
+    - Tracking of evicted items
+    - Configurable maximum buffer size
+
+    Example
+    --------
+    >>> buffer_cache = LoggerBufferCache(max_size_bytes=1000)
+    >>> buffer_cache.add("logs", "First log message")
+    >>> buffer_cache.add("debug", "Debug information")
+    >>> buffer_cache.get("logs")
+    ['First log message']
+    >>> buffer_cache.get_current_size("logs")
+    16
+    """
+
+    def __init__(self, max_size_bytes: int):
+        """
+        Initialize the LoggerBufferCache.
+
+        Parameters
+        ----------
+        max_size_bytes : int
+            Maximum size of the cache in bytes for each key.
+        """
+        self.max_size_bytes: int = max_size_bytes
+        self.cache: dict[str, KeyBufferCache] = {}
+
+    def add(self, key: str, item: Any) -> None:
+        """
+        Add an item to the cache for a specific key.
+
+        Parameters
+        ----------
+        key : str
+            The key to store the item under.
+        item : Any
+            The item to be stored in the cache.
+
+        Returns
+        -------
+        bool
+            True if item was added, False otherwise.
+        """
+        # Check if item is larger than entire buffer
+        item_size = len(str(item))
+        if item_size > self.max_size_bytes:
+            raise BufferError("Cannot add item to the buffer")
+
+        # Create the key's cache if it doesn't exist
+        if key not in self.cache:
+            self.cache[key] = KeyBufferCache()
+
+        # Calculate the size after adding the new item
+        new_total_size = self.cache[key].current_size + item_size
+
+        # If adding the item would exceed max size, remove oldest items
+        while new_total_size > self.max_size_bytes and self.cache[key].cache:
+            self.cache[key].remove_oldest()
+            new_total_size = self.cache[key].current_size + item_size
+
+        self.cache[key].add(item)
+
+    def get(self, key: str) -> list:
+        """
+        Retrieve items for a specific key.
+
+        Parameters
+        ----------
+        key : str
+            The key to retrieve items for.
+
+        Returns
+        -------
+        list
+            List of items for the given key, or an empty list if the key doesn't exist.
+        """
+        return [] if key not in self.cache else self.cache[key].get()
+
+    def clear(self, key: str | None = None) -> None:
+        """
+        Clear the cache, either for a specific key or entirely.
+
+        Parameters
+        ----------
+        key : Optional[str], optional
+            The key to clear. If None, clears the entire cache.
+        """
+        if key:
+            if key in self.cache:
+                self.cache[key].clear()
+                del self.cache[key]
+        else:
+            self.cache.clear()
+
+    def has_items_evicted(self, key: str) -> bool:
+        """
+        Check if a specific key's cache has evicted items.
+
+        Parameters
+        ----------
+        key : str
+            The key to check for evicted items.
+
+        Returns
+        -------
+        bool
+            True if items have been evicted, False otherwise.
+        """
+        return False if key not in self.cache else self.cache[key].has_evicted
+
+    def get_current_size(self, key: str) -> int | None:
+        """
+        Get the current size of the buffer for a specific key.
+
+        Parameters
+        ----------
+        key : str
+            The key to get the current size for.
+
+        Returns
+        -------
+        int
+            The current size of the buffer for the key.
+            Returns 0 if the key does not exist.
+        """
+        return None if key not in self.cache else self.cache[key].current_size

aws_lambda_powertools/logging/buffer/config.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Literal
+
+
+class LoggerBufferConfig:
+    """
+    Configuration for log buffering behavior.
+    """
+
+    # Define class-level constant for valid log levels
+    VALID_LOG_LEVELS: list[str] = ["DEBUG", "INFO", "WARNING"]
+    LOG_LEVEL_BUFFER_VALUES = Literal["DEBUG", "INFO", "WARNING"]
+
+    def __init__(
+        self,
+        max_bytes: int = 20480,
+        buffer_at_verbosity: LOG_LEVEL_BUFFER_VALUES = "DEBUG",
+        flush_on_error_log: bool = True,
+    ):
+        """
+        Initialize logger buffer configuration.
+
+        Parameters
+        ----------
+        max_bytes : int, optional
+            Maximum size of the buffer in bytes
+        buffer_at_verbosity : str, optional
+            Minimum log level to buffer
+        flush_on_error_log : bool, optional
+            Whether to flush the buffer when an error occurs
+        """
+        self._validate_inputs(max_bytes, buffer_at_verbosity, flush_on_error_log)
+
+        self._max_bytes = max_bytes
+        self._buffer_at_verbosity = buffer_at_verbosity.upper()
+        self._flush_on_error_log = flush_on_error_log
+
+    def _validate_inputs(
+        self,
+        max_bytes: int,
+        buffer_at_verbosity: str,
+        flush_on_error_log: bool,
+    ) -> None:
+        """
+        Validate configuration inputs.
+
+        Parameters
+        ----------
+        Same as __init__ method parameters
+        """
+        if not isinstance(max_bytes, int) or max_bytes <= 0:
+            raise ValueError("Max size must be a positive integer")
+
+        if not isinstance(buffer_at_verbosity, str):
+            raise ValueError("Log level must be a string")
+
+        # Validate log level
+        if buffer_at_verbosity.upper() not in self.VALID_LOG_LEVELS:
+            raise ValueError(f"Invalid log level. Must be one of {self.VALID_LOG_LEVELS}")
+
+        if not isinstance(flush_on_error_log, bool):
+            raise ValueError("flush_on_error must be a boolean")
+
+    @property
+    def max_bytes(self) -> int:
+        """Maximum buffer size in bytes."""
+        return self._max_bytes
+
+    @property
+    def buffer_at_verbosity(self) -> str:
+        """Minimum log level to buffer."""
+        return self._buffer_at_verbosity
+
+    @property
+    def flush_on_error_log(self) -> bool:
+        """Flag to flush buffer on error."""
+        return self._flush_on_error_log

aws_lambda_powertools/logging/buffer/functions.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import sys
+import time
+from typing import TYPE_CHECKING, Any, Mapping
+
+if TYPE_CHECKING:
+    import logging
+
+
+def _create_buffer_record(
+    level: int,
+    msg: object,
+    args: object,
+    exc_info: logging._ExcInfoType = None,
+    stack_info: bool = False,
+    extra: Mapping[str, object] | None = None,
+) -> dict[str, Any]:
+    """
+    Create a structured log record for buffering to save in buffer.
+
+    Parameters
+    ----------
+    level : int
+        Logging level (e.g., logging.DEBUG, logging.INFO) indicating log severity.
+    msg : object
+        The log message to be recorded.
+    args : object
+        Additional arguments associated with the log message.
+    exc_info : logging._ExcInfoType, optional
+        Exception information to be included in the log record.
+        If None, no exception details will be captured.
+    stack_info : bool, default False
+        Flag to include stack trace information in the log record.
+    extra : Mapping[str, object], optional
+        Additional context or metadata to be attached to the log record.
+
+    Returns
+    -------
+    dict[str, Any]
+
+    Notes
+    -----
+    - Captures caller frame information for precise log source tracking
+    - Automatically handles exception context
+    """
+    # Retrieve the caller's frame information to capture precise log context
+    # Uses inspect.stack() with index 3 to get the original caller's details
+    caller_frame = sys._getframe(3)
+
+    # Get the current timestamp
+    timestamp = time.time()
+
+    # Dynamically replace exc_info with current system exception information
+    # This ensures the most recent exception is captured if available
+    if exc_info:
+        exc_info = sys.exc_info()
+
+    # Construct and return the og record dictionary
+    return {
+        "level": level,
+        "msg": msg,
+        "args": args,
+        "filename": caller_frame.f_code.co_filename,
+        "line": caller_frame.f_lineno,
+        "function": caller_frame.f_code.co_name,
+        "extra": extra,
+        "timestamp": timestamp,
+        "exc_info": exc_info,
+        "stack_info": stack_info,
+    }
+
+
+def _check_minimum_buffer_log_level(buffer_log_level, current_log_level):
+    """
+    Determine if the current log level meets or exceeds the buffer's minimum log level.
+
+    Compares log levels to decide whether a log message should be included in the buffer.
+
+    Parameters
+    ----------
+    buffer_log_level : str
+        Minimum log level configured for the buffer.
+        Must be one of: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'.
+    current_log_level : str
+        Log level of the current log message.
+        Must be one of: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'.
+
+    Returns
+    -------
+    bool
+        True if the current log level is lower (more verbose) than the buffer's
+        minimum log level, indicating the message should be buffered.
+        False if the current log level is higher (less verbose) and should not be buffered.
+
+    Notes
+    -----
+    - Log levels are compared based on their numeric severity
+    - Conversion to uppercase ensures case-insensitive comparisons
+
+    Examples
+    --------
+    >>> _check_minimum_buffer_log_level('INFO', 'DEBUG')
+    True
+    >>> _check_minimum_buffer_log_level('ERROR', 'WARNING')
+    False
+    """
+    # Predefined log level mapping with numeric severity values
+    # Lower values indicate more verbose logging levels
+    log_levels = {
+        "DEBUG": 10,
+        "INFO": 20,
+        "WARNING": 30,
+        "ERROR": 40,
+        "CRITICAL": 50,
+    }
+
+    # Normalize input log levels to uppercase for consistent comparison
+    # Retrieve corresponding numeric log level values
+    buffer_level_num = log_levels.get(buffer_log_level.upper())
+    current_level_num = log_levels.get(current_log_level.upper())
+
+    # Compare numeric levels
+    if buffer_level_num < current_level_num:
+        return True
+
+    return False

aws_lambda_powertools/logging/logger.py

@@ -16,12 +16,17 @@ import warnings
 from contextlib import contextmanager
 from typing import IO, TYPE_CHECKING, Any, Callable, Generator, Iterable, Mapping, TypeVar, cast, overload
 
+from aws_lambda_powertools.logging.buffer.cache import LoggerBufferCache
+from aws_lambda_powertools.logging.buffer.functions import _check_minimum_buffer_log_level, _create_buffer_record
 from aws_lambda_powertools.logging.constants import (
     LOGGER_ATTRIBUTE_HANDLER,
     LOGGER_ATTRIBUTE_POWERTOOLS_HANDLER,
     LOGGER_ATTRIBUTE_PRECONFIGURED,
 )
-from aws_lambda_powertools.logging.exceptions import InvalidLoggerSamplingRateError, OrphanedChildLoggerError
+from aws_lambda_powertools.logging.exceptions import (
+    InvalidLoggerSamplingRateError,
+    OrphanedChildLoggerError,
+)
 from aws_lambda_powertools.logging.filters import SuppressFilter
 from aws_lambda_powertools.logging.formatter import (
     RESERVED_FORMATTER_CUSTOM_KEYS,
@@ -32,14 +37,18 @@ from aws_lambda_powertools.logging.lambda_context import build_lambda_context_mo
 from aws_lambda_powertools.shared import constants
 from aws_lambda_powertools.shared.functions import (
     extract_event_from_common_models,
+    get_tracer_id,
     resolve_env_var_choice,
     resolve_truthy_env_var_choice,
 )
 from aws_lambda_powertools.utilities import jmespath_utils
+from aws_lambda_powertools.warnings import PowertoolsUserWarning
 
 if TYPE_CHECKING:
+    from aws_lambda_powertools.logging.buffer.config import LoggerBufferConfig
     from aws_lambda_powertools.shared.types import AnyCallableT
 
+
 logger = logging.getLogger(__name__)
 
 is_cold_start = True
@@ -100,6 +109,8 @@ class Logger:
         custom logging handler e.g. logging.FileHandler("file.log")
     log_uncaught_exceptions: bool, by default False
         logs uncaught exception using sys.excepthook
+    buffer_config: LoggerBufferConfig, optional
+        logger buffer configuration
 
         See: https://docs.python.org/3/library/sys.html#sys.excepthook
 
@@ -218,6 +229,7 @@ class Logger:
         utc: bool = False,
         use_rfc3339: bool = False,
         serialize_stacktrace: bool = True,
+        buffer_config: LoggerBufferConfig | None = None,
         **kwargs,
     ) -> None:
 
@@ -259,7 +271,17 @@ class Logger:
             "serialize_stacktrace": serialize_stacktrace,
         }
 
-        self._init_logger(formatter_options=formatter_options, log_level=level, **kwargs)
+        self._buffer_config = buffer_config
+        if self._buffer_config:
+            self._buffer_cache = LoggerBufferCache(max_size_bytes=self._buffer_config.max_bytes)
+
+        self._init_logger(
+            formatter_options=formatter_options,
+            log_level=level,
+            buffer_config=self._buffer_config,
+            buffer_cache=getattr(self, "_buffer_cache", None),
+            **kwargs,
+        )
 
         if self.log_uncaught_exceptions:
             logger.debug("Replacing exception hook")
@@ -303,6 +325,8 @@ class Logger:
         self,
         formatter_options: dict | None = None,
         log_level: str | int | None = None,
+        buffer_config: LoggerBufferConfig | None = None,
+        buffer_cache: LoggerBufferCache | None = None,
         **kwargs,
     ) -> None:
         """Configures new logger"""
@@ -315,9 +339,19 @@ class Logger:
         is_logger_preconfigured = getattr(self._logger, LOGGER_ATTRIBUTE_PRECONFIGURED, False)
         if self.child:
             self.setLevel(log_level)
+            if getattr(self._logger.parent, "powertools_buffer_config", None):
+                # Initializes a new, empty LoggerBufferCache for child logger
+                # Preserves parent's buffer configuration while resetting cache contents
+                self._buffer_config = self._logger.parent.powertools_buffer_config  # type: ignore[union-attr]
+                self._buffer_cache = LoggerBufferCache(self._logger.parent.powertools_buffer_config.max_bytes)  # type: ignore[union-attr]
             return
 
         if is_logger_preconfigured:
+            # Reuse existing buffer configuration from a previously configured logger
+            # Ensures consistent buffer settings across logger instances within the same service
+            # Enables buffer propagation and maintains a unified logging configuration
+            self._buffer_config = self._logger.powertools_buffer_config  # type: ignore[attr-defined]
+            self._buffer_cache = self._logger.powertools_buffer_cache  # type: ignore[attr-defined]
             return
 
         self.setLevel(log_level)
@@ -342,6 +376,8 @@ class Logger:
         logger.debug(f"Marking logger {self.service} as preconfigured")
         self._logger.init = True  # type: ignore[attr-defined]
         self._logger.powertools_handler = self.logger_handler  # type: ignore[attr-defined]
+        self._logger.powertools_buffer_config = buffer_config  # type: ignore[attr-defined]
+        self._logger.powertools_buffer_cache = buffer_cache  # type: ignore[attr-defined]
 
     def refresh_sample_rate_calculation(self) -> None:
         """
@@ -386,6 +422,7 @@ class Logger:
         log_event: bool | None = None,
         correlation_id_path: str | None = None,
         clear_state: bool | None = False,
+        flush_buffer_on_uncaught_error: bool = False,
     ) -> AnyCallableT: ...
 
     @overload
@@ -395,6 +432,7 @@ class Logger:
         log_event: bool | None = None,
         correlation_id_path: str | None = None,
         clear_state: bool | None = False,
+        flush_buffer_on_uncaught_error: bool = False,
     ) -> Callable[[AnyCallableT], AnyCallableT]: ...
 
     def inject_lambda_context(
@@ -403,6 +441,7 @@ class Logger:
         log_event: bool | None = None,
         correlation_id_path: str | None = None,
         clear_state: bool | None = False,
+        flush_buffer_on_uncaught_error: bool = False,
     ) -> Any:
         """Decorator to capture Lambda contextual info and inject into logger
 
@@ -459,6 +498,7 @@ class Logger:
                 log_event=log_event,
                 correlation_id_path=correlation_id_path,
                 clear_state=clear_state,
+                flush_buffer_on_uncaught_error=flush_buffer_on_uncaught_error,
             )
 
         log_event = resolve_truthy_env_var_choice(
@@ -491,11 +531,25 @@ class Logger:
             if self.sampling_rate and not cold_start:
                 self.refresh_sample_rate_calculation()
 
-            return lambda_handler(event, context, *args, **kwargs)
+            try:
+                # Execute the Lambda handler with provided event and context
+                return lambda_handler(event, context, *args, **kwargs)
+            except:
+                # Flush the log buffer if configured to do so on uncaught errors
+                # Ensures logging state is cleaned up even if an exception is raised
+                if flush_buffer_on_uncaught_error:
+                    logger.debug("Uncaught error detected, flushing log buffer before exit")
+                    self.flush_buffer()
+                # Re-raise any exceptions that occur during handler execution
+                raise
+            finally:
+                # Clear the cache after invocation is complete
+                if self._buffer_config:
+                    self._buffer_cache.clear()
 
         return decorate
 
-    def info(
+    def debug(
         self,
         msg: object,
         *args: object,
@@ -508,16 +562,37 @@ class Logger:
         extra = extra or {}
         extra = {**extra, **kwargs}
 
-        return self._logger.info(
-            msg,
-            *args,
+        # Logging workflow for logging.debug:
+        # 1. Buffer is completely disabled - log right away
+        # 2. DEBUG is the maximum level of buffer, so, can't bypass if enabled
+        # 3. Store in buffer for potential later processing
+
+        # MAINTAINABILITY_DECISION:
+        # Keeping this implementation to avoid complex code handling.
+        # Also for clarity over complexity
+
+        # Buffer is not active and we need to log immediately
+        if not self._buffer_config:
+            return self._logger.debug(
+                msg,
+                *args,
+                exc_info=exc_info,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                extra=extra,
+            )
+
+        # Store record in the buffer
+        self._add_log_record_to_buffer(
+            level=logging.DEBUG,
+            msg=msg,
+            args=args,
             exc_info=exc_info,
             stack_info=stack_info,
-            stacklevel=stacklevel,
             extra=extra,
         )
 
-    def error(
+    def info(
         self,
         msg: object,
         *args: object,
@@ -530,20 +605,52 @@ class Logger:
         extra = extra or {}
         extra = {**extra, **kwargs}
 
-        return self._logger.error(
-            msg,
-            *args,
+        # Logging workflow for logging.info:
+        # 1. Buffer is completely disabled - log right away
+        # 2. Log severity exceeds buffer's minimum threshold - bypass buffering
+        # 3. If neither condition met, store in buffer for potential later processing
+
+        # MAINTAINABILITY_DECISION:
+        # Keeping this implementation to avoid complex code handling.
+        # Also for clarity over complexity
+
+        # Buffer is not active and we need to log immediately
+        if not self._buffer_config:
+            return self._logger.info(
+                msg,
+                *args,
+                exc_info=exc_info,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                extra=extra,
+            )
+
+        # Bypass buffer when log severity meets or exceeds configured minimum
+        if _check_minimum_buffer_log_level(self._buffer_config.buffer_at_verbosity, "INFO"):
+            return self._logger.info(
+                msg,
+                *args,
+                exc_info=exc_info,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                extra=extra,
+            )
+
+        # Store record in the buffer
+        self._add_log_record_to_buffer(
+            level=logging.INFO,
+            msg=msg,
+            args=args,
             exc_info=exc_info,
             stack_info=stack_info,
-            stacklevel=stacklevel,
             extra=extra,
         )
 
-    def exception(
+    def warning(
         self,
         msg: object,
         *args: object,
-        exc_info: logging._ExcInfoType = True,
+        exc_info: logging._ExcInfoType = None,
         stack_info: bool = False,
         stacklevel: int = 2,
         extra: Mapping[str, object] | None = None,
@@ -552,16 +659,48 @@ class Logger:
         extra = extra or {}
         extra = {**extra, **kwargs}
 
-        return self._logger.exception(
-            msg,
-            *args,
+        # Logging workflow for logging.warning:
+        # 1. Buffer is completely disabled - log right away
+        # 2. Log severity exceeds buffer's minimum threshold - bypass buffering
+        # 3. If neither condition met, store in buffer for potential later processing
+
+        # MAINTAINABILITY_DECISION:
+        # Keeping this implementation to avoid complex code handling.
+        # Also for clarity over complexity
+
+        # Buffer is not active and we need to log immediately
+        if not self._buffer_config:
+            return self._logger.warning(
+                msg,
+                *args,
+                exc_info=exc_info,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                extra=extra,
+            )
+
+        # Bypass buffer when log severity meets or exceeds configured minimum
+        if _check_minimum_buffer_log_level(self._buffer_config.buffer_at_verbosity, "WARNING"):
+            return self._logger.warning(
+                msg,
+                *args,
+                exc_info=exc_info,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                extra=extra,
+            )
+
+        # Store record in the buffer
+        self._add_log_record_to_buffer(
+            level=logging.WARNING,
+            msg=msg,
+            args=args,
             exc_info=exc_info,
             stack_info=stack_info,
-            stacklevel=stacklevel,
             extra=extra,
         )
 
-    def critical(
+    def error(
         self,
         msg: object,
         *args: object,
@@ -574,7 +713,15 @@ class Logger:
         extra = extra or {}
         extra = {**extra, **kwargs}
 
-        return self._logger.critical(
+        # Workflow: Error Logging with automatic buffer flushing
+        # 1. Buffer configuration checked for immediate flush
+        # 2. If auto-flush enabled, trigger complete buffer processing
+        # 3. Error log is not "bufferable", so ensure error log is immediately available
+
+        if self._buffer_config and self._buffer_config.flush_on_error_log:
+            self.flush_buffer()
+
+        return self._logger.error(
             msg,
             *args,
             exc_info=exc_info,
@@ -583,7 +730,7 @@ class Logger:
             extra=extra,
         )
 
-    def warning(
+    def critical(
         self,
         msg: object,
         *args: object,
@@ -596,7 +743,15 @@ class Logger:
         extra = extra or {}
         extra = {**extra, **kwargs}
 
-        return self._logger.warning(
+        # Workflow: Error Logging with automatic buffer flushing
+        # 1. Buffer configuration checked for immediate flush
+        # 2. If auto-flush enabled, trigger complete buffer processing
+        # 3. Critical log is not "bufferable", so ensure error log is immediately available
+
+        if self._buffer_config and self._buffer_config.flush_on_error_log:
+            self.flush_buffer()
+
+        return self._logger.critical(
             msg,
             *args,
             exc_info=exc_info,
@@ -605,11 +760,11 @@ class Logger:
             extra=extra,
         )
 
-    def debug(
+    def exception(
         self,
         msg: object,
         *args: object,
-        exc_info: logging._ExcInfoType = None,
+        exc_info: logging._ExcInfoType = True,
         stack_info: bool = False,
         stacklevel: int = 2,
         extra: Mapping[str, object] | None = None,
@@ -618,7 +773,14 @@ class Logger:
         extra = extra or {}
         extra = {**extra, **kwargs}
 
-        return self._logger.debug(
+        # Workflow: Error Logging with automatic buffer flushing
+        # 1. Buffer configuration checked for immediate flush
+        # 2. If auto-flush enabled, trigger complete buffer processing
+        # 3. Exception log is not "bufferable", so ensure error log is immediately available
+        if self._buffer_config and self._buffer_config.flush_on_error_log:
+            self.flush_buffer()
+
+        return self._logger.exception(
             msg,
             *args,
             exc_info=exc_info,
@@ -887,6 +1049,161 @@ class Logger:
         # Powertools log level is set, we use this
         return powertools_log_level.upper()
 
+    # FUNCTIONS for Buffering log
+
+    def _create_and_flush_log_record(self, log_line: dict) -> None:
+        """
+        Create and immediately flush a log record to the configured logger.
+
+        Parameters
+        ----------
+        log_line : dict[str, Any]
+            Dictionary containing log record details with keys:
+            - 'level': Logging level
+            - 'filename': Source filename
+            - 'line': Line number
+            - 'msg': Log message
+            - 'function': Source function name
+            - 'extra': Additional context
+            - 'timestamp': Original log creation time
+
+        Notes
+        -----
+        Bypasses standard logging flow by directly creating and handling a log record.
+        Preserves original timestamp and source information.
+        """
+        record = self._logger.makeRecord(
+            name=self.name,
+            level=log_line["level"],
+            fn=log_line["filename"],
+            lno=log_line["line"],
+            msg=log_line["msg"],
+            args=(),
+            exc_info=log_line["exc_info"],
+            func=log_line["function"],
+            extra=log_line["extra"],
+        )
+        record.created = log_line["timestamp"]
+        self._logger.handle(record)
+
+    def _add_log_record_to_buffer(
+        self,
+        level: int,
+        msg: object,
+        args: object,
+        exc_info: logging._ExcInfoType = None,
+        stack_info: bool = False,
+        extra: Mapping[str, object] | None = None,
+    ) -> None:
+        """
+        Add log record to buffer with intelligent tracer ID handling.
+
+        Parameters
+        ----------
+        level : int
+            Logging level of the record.
+        msg : object
+            Log message to be recorded.
+        args : object
+            Additional arguments for the log message.
+        exc_info : logging._ExcInfoType, optional
+            Exception information for the log record.
+        stack_info : bool, optional
+            Whether to include stack information.
+        extra : Mapping[str, object], optional
+            Additional contextual information for the log record.
+
+        Raises
+        ------
+        InvalidBufferItem
+            If the log record cannot be added to the buffer.
+
+        Notes
+        -----
+        Handles special first invocation buffering and migration of log records
+        between different tracer contexts.
+        """
+        # Determine tracer ID, defaulting to first invoke marker
+        tracer_id = get_tracer_id()
+
+        if tracer_id and self._buffer_config:
+            log_record: dict[str, Any] = _create_buffer_record(
+                level=level,
+                msg=msg,
+                args=args,
+                exc_info=exc_info,
+                stack_info=stack_info,
+                extra=extra,
+            )
+            try:
+                self._buffer_cache.add(tracer_id, log_record)
+            except BufferError:
+                warnings.warn(
+                    message="Cannot add item to the buffer. "
+                    f"Item size exceeds total cache size {self._buffer_config.max_bytes} bytes",
+                    category=PowertoolsUserWarning,
+                    stacklevel=2,
+                )
+
+                # flush this log to avoid data loss
+                self._create_and_flush_log_record(log_record)
+
+    def flush_buffer(self) -> None:
+        """
+        Flush all buffered log records associated with current execution.
+
+        Notes
+        -----
+        Retrieves log records for current trace from buffer
+        Immediately processes and logs each record
+        Warning if some cache was evicted in that execution
+        Clears buffer after complete processing
+
+        Raises
+        ------
+        Any exceptions from underlying logging or buffer mechanisms
+        will be propagated to caller
+        """
+        tracer_id = get_tracer_id()
+
+        # Flushing log without a tracer id? Return
+        if not tracer_id:
+            return
+
+        # is buffer empty? return
+        buffer = self._buffer_cache.get(tracer_id)
+        if not buffer:
+            return
+
+        # Process log records
+        for log_line in buffer:
+            self._create_and_flush_log_record(log_line)
+
+        # Has items evicted?
+        if self._buffer_cache.has_items_evicted(tracer_id):
+            warnings.warn(
+                message="Some logs are not displayed because they were evicted from the buffer. "
+                "Increase buffer size to store more logs in the buffer",
+                category=PowertoolsUserWarning,
+                stacklevel=2,
+            )
+
+        # Clear the entire cache
+        self._buffer_cache.clear()
+
+    def clear_buffer(self) -> None:
+        """
+        Clear the internal buffer cache.
+
+        This method removes all items from the buffer cache, effectively resetting it to an empty state.
+
+        Returns
+        -------
+        None
+        """
+        if self._buffer_config:
+            self._buffer_cache.clear()
+
 
 def set_package_logger(
     level: str | int = logging.DEBUG,

aws_lambda_powertools/shared/functions.py

@@ -283,3 +283,8 @@ def abs_lambda_path(relative_path: str = "") -> str:
 
 def sanitize_xray_segment_name(name: str) -> str:
     return re.sub(constants.INVALID_XRAY_NAME_CHARACTERS, "", name)
+
+
+def get_tracer_id() -> str | None:
+    xray_trace_id = os.getenv(constants.XRAY_TRACE_ID_ENV)
+    return xray_trace_id.split(";")[0].replace("Root=", "") if xray_trace_id else None

aws_lambda_powertools/shared/version.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.7.1a7"
+VERSION = "3.8.1a0"

{aws_lambda_powertools-3.7.1a7.dist-info → aws_lambda_powertools-3.8.1a0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: aws_lambda_powertools
-Version: 3.7.1a7
+Version: 3.8.1a0
 Summary: Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverless best practices and increase developer velocity.
 License: MIT
 Keywords: aws_lambda_powertools,aws,tracing,logging,lambda,powertools,feature_flags,idempotency,middleware

{aws_lambda_powertools-3.7.1a7.dist-info → aws_lambda_powertools-3.8.1a0.dist-info}/RECORD

@@ -13,7 +13,7 @@ aws_lambda_powertools/event_handler/graphql_appsync/router.py,sha256=f6jFQ3ZbJz9
 aws_lambda_powertools/event_handler/lambda_function_url.py,sha256=aJtTUR9DD6UzFcpRfbUki7mm2BDozFmuECrTWXxLjng,2153
 aws_lambda_powertools/event_handler/middlewares/__init__.py,sha256=3R5XptoCT8owm4swcAEG0lsV_zbL4X-gU5nv8eJ0jQs,158
 aws_lambda_powertools/event_handler/middlewares/base.py,sha256=llr1_sGaAsyMY9Gn4zKUDxePQ5X7ClcqgjqPesg5FJw,3724
-aws_lambda_powertools/event_handler/middlewares/openapi_validation.py,sha256=DZqkFFtft6WbtzRBzM4nA3FFtEKw-pGIgPixSvOJLcs,15017
+aws_lambda_powertools/event_handler/middlewares/openapi_validation.py,sha256=zoHza0Vj_ij0wfobYX7SC46N4YYlMH9en3L3X9iK25g,14959
 aws_lambda_powertools/event_handler/middlewares/schema_validation.py,sha256=gEX0lgO8e7sxNQZwFbhK3ExQyb_b_Fw3l6k5SeZyHqk,5204
 aws_lambda_powertools/event_handler/openapi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 aws_lambda_powertools/event_handler/openapi/compat.py,sha256=elvYmcsKx9TjRnTAief8Xfpd5bgKADoM-9BlQ4Q37iY,10877
@@ -36,6 +36,10 @@ aws_lambda_powertools/event_handler/util.py,sha256=j7InZnSXymsWmp2Gj2emnVJjFcKo4
 aws_lambda_powertools/event_handler/vpc_lattice.py,sha256=rih7cVt4H9opHpYOUyuv2m3AdXS9Rxt-AH7ua51WwFs,3207
 aws_lambda_powertools/exceptions/__init__.py,sha256=bv7fiO8Cj5xbHOTlDpWpM3pIkbdSB74Nt_mHbzLzYDw,163
 aws_lambda_powertools/logging/__init__.py,sha256=G5MTkVqaQvpfa7k3fGkj4QN0KU6nFfP0_SLF_47G_VE,72
+aws_lambda_powertools/logging/buffer/__init__.py,sha256=2sdmJToRBp6QJI2VQuvgjuxsJkTMd4dL3TYp6dASiOQ,109
+aws_lambda_powertools/logging/buffer/cache.py,sha256=rh8XjDsfGEvXN8eRXHk8nAiN06rZEK1bcIZVuLshoHI,6058
+aws_lambda_powertools/logging/buffer/config.py,sha256=tKOlgGhkAY214Fskn6u-Xm9pdTTbo3XJSwSoSJfoIW4,2383
+aws_lambda_powertools/logging/buffer/functions.py,sha256=qgywGfLQpr4jYJFugJHDm_fXyxnTpJ3ppHFAI_7bpOM,3949
 aws_lambda_powertools/logging/constants.py,sha256=P0XgbCmG4NiP96kx0qxe6QUC3ShN12doSIXTkobX7C4,309
 aws_lambda_powertools/logging/correlation_paths.py,sha256=uHHrl03aWzpOsrGHZ-9E6PNoMFyKjv3APNMMkI1EN_c,411
 aws_lambda_powertools/logging/exceptions.py,sha256=Fe_jk8O9vgUSUHxxOkz6Ev521aXsgPkMgA9Hb1nBn6g,232
@@ -44,7 +48,7 @@ aws_lambda_powertools/logging/formatter.py,sha256=dmE6XXmkWVkYbWdy1Kg69TYJJ0yDXf
 aws_lambda_powertools/logging/formatters/__init__.py,sha256=OqddpJcWMqRYhx5SFy-SPqtt72tkRZbfpEi_oCC47eI,301
 aws_lambda_powertools/logging/formatters/datadog.py,sha256=NwaaBOp7jIlOAH158NzyvW-EwmWqqnYX9f7Uu_nIUYQ,3169
 aws_lambda_powertools/logging/lambda_context.py,sha256=VHst_6hxMpXgScoxNwaC61UXPTIdd3AEBHTPzb4esPc,1736
-aws_lambda_powertools/logging/logger.py,sha256=r9VACN9W72VMMqxbhbRYz9dREhX5pkk5hUf5MtS9u_8,35824
+aws_lambda_powertools/logging/logger.py,sha256=rRvHggw3XjAg3xJw6ngZZx3eMUQybSFCJ-rSX5ZnsPc,48342
 aws_lambda_powertools/logging/types.py,sha256=Zc95nGdZ2sJUEPdwR0uoArT_F-JSKfpS_LokdCVO0nQ,1263
 aws_lambda_powertools/logging/utils.py,sha256=NirAObjkkarN5fX2diHs0Ln_8KHLueviL-jCKhckIBM,4069
 aws_lambda_powertools/metrics/__init__.py,sha256=B5FpJS_VR7zivm2ylvUF8RHBthKz4aDk0VA5GpDn3Tk,592
@@ -77,13 +81,13 @@ aws_lambda_powertools/shared/cache_dict.py,sha256=X3Ykh-_Fb4Wkc5RGjaostC_FUvMyY_
 aws_lambda_powertools/shared/constants.py,sha256=lIEs2_5080qhCp7l_v_rdjXud5uF0Dlf-4VniDdIJCI,2737
 aws_lambda_powertools/shared/cookies.py,sha256=X2Bkcf7MAmV75PJFm07QGkL4n1psk4HIGpUxzrsjiJY,3868
 aws_lambda_powertools/shared/dynamodb_deserializer.py,sha256=tWw8MLXEitInnViFkt_xSBkXD_V1n1KcWbqBXBxwUlE,4054
-aws_lambda_powertools/shared/functions.py,sha256=kgHqBFvzhxxROzLL-NcrfKHWcPqr6GP38PeB1XfT8jQ,7442
+aws_lambda_powertools/shared/functions.py,sha256=N5VIND3xW-eZHqY2uPsBMtDbtMx64iklUKByeCh58rc,7625
 aws_lambda_powertools/shared/headers_serializer.py,sha256=1eRQ-FO6jNskTXWRa25OXI5Klu3yH6HAHjGGZULB8FE,5411
 aws_lambda_powertools/shared/json_encoder.py,sha256=JQeWNu-4M7_xI_hqYExrxsb3OcEH4uTxjfVE4Of8Nn8,666
 aws_lambda_powertools/shared/lazy_import.py,sha256=TbXQm2bcwXdZrYdBaJJXIswyLlumM85RJ_A_0w-h-GU,2019
 aws_lambda_powertools/shared/types.py,sha256=APkI38HbiTpSF19NSNii8Ydx73vmVUVotgEQ9jHruEI,124
 aws_lambda_powertools/shared/user_agent.py,sha256=DrCMFQuT4a4iIrpcWpAIjY37EFqR9-QxlxDGD-Nn9Gg,7081
-aws_lambda_powertools/shared/version.py,sha256=DheiIJQ50d2a_hoe9oSMHEVYeUiKw6fhfDbNFbI0aEE,84
+aws_lambda_powertools/shared/version.py,sha256=eez1WHK6RC3OddSRIYbCj803B2xulcLLJkJMRK4zCUQ,84
 aws_lambda_powertools/tracing/__init__.py,sha256=f4bMThOPBPWTPVcYqcAIErAJPerMsf3H_Z4gCXCsK9I,141
 aws_lambda_powertools/tracing/base.py,sha256=DbLD8OSK05KLdSV36oNA5wDSGv8KbcOD19qMUqoXh58,4513
 aws_lambda_powertools/tracing/extensions.py,sha256=APOfXOq-hRBKaK5WyfIyrd_6M1_9SWJZ3zxLA9jDZzU,492
@@ -251,7 +255,7 @@ aws_lambda_powertools/utilities/validation/envelopes.py,sha256=YD5HOFx6IClQgii0n
 aws_lambda_powertools/utilities/validation/exceptions.py,sha256=PKy_19zQMBJGCMMFl-sMkcm-cc0v3zZBn_bhGE4wKNo,2084
 aws_lambda_powertools/utilities/validation/validator.py,sha256=x_1qpuKJBuWpgNU-zCD3Di-vXrZfyUu7oA5RmjZjr84,10034
 aws_lambda_powertools/warnings/__init__.py,sha256=vqDVeZz8wGtD8WGYNSkQE7AHwqtIrPGRxuoJR_BBnSs,1193
-aws_lambda_powertools-3.7.1a7.dist-info/LICENSE,sha256=vMHS2eBgmwPUIMPb7LQ4p7ib_FPVQXarVjAasflrTwo,951
-aws_lambda_powertools-3.7.1a7.dist-info/METADATA,sha256=nC3pL-7Br5KiXmduzxGJesz9XyL81NDaynSCqh8CFaM,11151
-aws_lambda_powertools-3.7.1a7.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-aws_lambda_powertools-3.7.1a7.dist-info/RECORD,,
+aws_lambda_powertools-3.8.1a0.dist-info/LICENSE,sha256=vMHS2eBgmwPUIMPb7LQ4p7ib_FPVQXarVjAasflrTwo,951
+aws_lambda_powertools-3.8.1a0.dist-info/METADATA,sha256=oL3dXznPiEm3OE0yFIBoJYi4eqM8VPFjws170mcmOOk,11151
+aws_lambda_powertools-3.8.1a0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+aws_lambda_powertools-3.8.1a0.dist-info/RECORD,,