Refactoring parameters name + child logger + tests

Author: leandrodamascena

aws_lambda_powertools/logging/buffer/config.py

@@ -14,35 +14,33 @@ class LoggerBufferConfig:
 
     def __init__(
         self,
-        max_size: int = 20480,
-        minimum_log_level: LOG_LEVEL_BUFFER_VALUES = "DEBUG",
-        flush_on_error: bool = True,
+        max_bytes: int = 20480,
+        buffer_at_verbosity: LOG_LEVEL_BUFFER_VALUES = "DEBUG",
+        flush_on_error_log: bool = True,
     ):
         """
         Initialize logger buffer configuration.
 
         Parameters
         ----------
-        max_size : int, optional
+        max_bytes : int, optional
             Maximum size of the buffer in bytes
-        minimum_log_level : str, optional
+        buffer_at_verbosity : str, optional
             Minimum log level to buffer
-        flush_on_error : bool, optional
+        flush_on_error_log : bool, optional
             Whether to flush the buffer when an error occurs
-        compress : bool, optional
-            Whether to compress buffered logs
         """
-        self._validate_inputs(max_size, minimum_log_level, flush_on_error)
+        self._validate_inputs(max_bytes, buffer_at_verbosity, flush_on_error_log)
 
-        self._max_size = max_size
-        self._minimum_log_level = minimum_log_level.upper()
-        self._flush_on_error = flush_on_error
+        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_size: int,
-        minimum_log_level: str,
-        flush_on_error: bool,
+        max_bytes: int,
+        buffer_at_verbosity: str,
+        flush_on_error_log: bool,
     ) -> None:
         """
         Validate configuration inputs.
@@ -51,30 +49,30 @@ def _validate_inputs(
         ----------
         Same as __init__ method parameters
         """
-        if not isinstance(max_size, int) or max_size <= 0:
+        if not isinstance(max_bytes, int) or max_bytes <= 0:
             raise ValueError("Max size must be a positive integer")
 
-        if not isinstance(minimum_log_level, str):
+        if not isinstance(buffer_at_verbosity, str):
             raise ValueError("Log level must be a string")
 
         # Validate log level
-        if minimum_log_level.upper() not in self.VALID_LOG_LEVELS:
+        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, bool):
+        if not isinstance(flush_on_error_log, bool):
             raise ValueError("flush_on_error must be a boolean")
 
     @property
-    def max_size(self) -> int:
+    def max_bytes(self) -> int:
         """Maximum buffer size in bytes."""
-        return self._max_size
+        return self._max_bytes
 
     @property
-    def minimum_log_level(self) -> str:
+    def buffer_at_verbosity(self) -> str:
         """Minimum log level to buffer."""
-        return self._minimum_log_level
+        return self._buffer_at_verbosity
 
     @property
-    def flush_on_error(self) -> bool:
+    def flush_on_error_log(self) -> bool:
         """Flag to flush buffer on error."""
-        return self._flush_on_error
+        return self._flush_on_error_log

aws_lambda_powertools/logging/logger.py

@@ -227,7 +227,7 @@ def __init__(
         utc: bool = False,
         use_rfc3339: bool = False,
         serialize_stacktrace: bool = True,
-        logger_buffer: LoggerBufferConfig | None = None,
+        buffer_config: LoggerBufferConfig | None = None,
         **kwargs,
     ) -> None:
 
@@ -269,9 +269,9 @@ def __init__(
             "serialize_stacktrace": serialize_stacktrace,
         }
 
-        self._buffer_config = logger_buffer
+        self._buffer_config = buffer_config
         if self._buffer_config:
-            self._buffer_cache = LoggerBufferCache(max_size_bytes=self._buffer_config.max_size)
+            self._buffer_cache = LoggerBufferCache(max_size_bytes=self._buffer_config.max_bytes)
 
         self._init_logger(
             formatter_options=formatter_options,
@@ -337,6 +337,11 @@ def _init_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:
@@ -619,7 +624,7 @@ def info(
             )
 
         # Bypass buffer when log severity meets or exceeds configured minimum
-        if _check_minimum_buffer_log_level(self._buffer_config.minimum_log_level, "INFO"):
+        if _check_minimum_buffer_log_level(self._buffer_config.buffer_at_verbosity, "INFO"):
             return self._logger.info(
                 msg,
                 *args,
@@ -673,7 +678,7 @@ def warning(
             )
 
         # Bypass buffer when log severity meets or exceeds configured minimum
-        if _check_minimum_buffer_log_level(self._buffer_config.minimum_log_level, "WARNING"):
+        if _check_minimum_buffer_log_level(self._buffer_config.buffer_at_verbosity, "WARNING"):
             return self._logger.warning(
                 msg,
                 *args,
@@ -711,7 +716,7 @@ def error(
         # 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:
+        if self._buffer_config and self._buffer_config.flush_on_error_log:
             self.flush_buffer()
 
         return self._logger.error(
@@ -741,7 +746,7 @@ def critical(
         # 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:
+        if self._buffer_config and self._buffer_config.flush_on_error_log:
             self.flush_buffer()
 
         return self._logger.critical(
@@ -770,7 +775,7 @@ def exception(
         # 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:
+        if self._buffer_config and self._buffer_config.flush_on_error_log:
             self.flush_buffer()
 
         return self._logger.exception(
@@ -1133,7 +1138,7 @@ def _add_log_record_to_buffer(
             except BufferError:
                 warnings.warn(
                     message="Cannot add item to the buffer. "
-                    f"Item size exceeds total cache size {self._buffer_config.max_size} bytes",
+                    f"Item size exceeds total cache size {self._buffer_config.max_bytes} bytes",
                     category=PowertoolsUserWarning,
                     stacklevel=2,
                 )

docs/core/logger.md

@@ -11,6 +11,7 @@ Logger provides an opinionated logger with output structured as JSON.
 * Log Lambda event when instructed (disabled by default)
 * Log sampling enables DEBUG log level for a percentage of requests (disabled by default)
 * Append additional keys to structured log at any point in time
+* Buffering logs for a specific request or invocation, and flushing them automatically on error or manually as needed.
 
 ## Getting started
 
@@ -530,11 +531,13 @@ Log buffering enables you to buffer logs for a specific request or invocation. E
 
 When configuring log buffering, you have options to fine-tune how logs are captured, stored, and emitted. You can configure the following parameters in the `LoggerBufferConfig` constructor:
 
-| Parameter           | Description                                     | Configuration                |
-|-------------------- |------------------------------------------------ |----------------------------- |
-| `max_size`          | Maximum size of the log buffer in bytes         | `int` (default: 20480 bytes) |
-| `minimum_log_level` | Minimum log level to buffer                     | `DEBUG`, `INFO`, `WARNING`   |
-| `flush_on_error`    | Automatically flush buffer when an error occurs | `True` (default), `False`    |
+| Parameter             | Description                                     | Configuration                |
+|---------------------- |------------------------------------------------ |----------------------------- |
+| `max_bytes`           | Maximum size of the log buffer in bytes         | `int` (default: 20480 bytes) |
+| `buffer_at_verbosity` | Minimum log level to buffer                     | `DEBUG`, `INFO`, `WARNING`   |
+| `flush_on_error_log`  | Automatically flush buffer when an error occurs | `True` (default), `False`    |
+
+!!! note "When `flush_on_error_log` is enabled, it automatically flushes for `logger.exception()`, `logger.error()`, and `logger.critical()` statements."
 
 === "working_with_buffering_logs_different_levels.py"
 
@@ -550,6 +553,8 @@ When configuring log buffering, you have options to fine-tune how logs are captu
     --8<-- "examples/logger/src/working_with_buffering_logs_disable_on_error.py"
     ```
 
+    1. Disabling `flush_on_error_log` will not flush the buffer when logging an error. This is useful when you want to control when the buffer is flushed by calling the `logger.flush_buffer()` method.
+
 #### Flushing on exceptions
 
 Use the `@logger.inject_lambda_context` decorator to automatically flush buffered logs when an exception is raised in your Lambda function. The `flush_buffer_on_uncaught_error` parameter captures and flush all buffered logs records before the Lambda execution terminates.
@@ -567,6 +572,8 @@ If you are using log buffering, we recommend sharing the same log instance acros
 !!! note "Buffer Inheritance"
     Loggers created with the same `service_name` automatically inherit the buffer configuration from the first initialized logger with a buffer configuration.
 
+    Child loggers instances inherit their parent's buffer configuration but maintain a separate buffer.
+
 === "working_with_buffering_logs_creating_instance.py"
 
     ```python hl_lines="2 5"

examples/logger/src/getting_started_with_buffering_logs.py

@@ -2,8 +2,8 @@
 from aws_lambda_powertools.logging.buffer import LoggerBufferConfig
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-logger_buffer_config = LoggerBufferConfig(max_size=20480, flush_on_error=True)
-logger = Logger(level="INFO", logger_buffer=logger_buffer_config)
+logger_buffer_config = LoggerBufferConfig(max_bytes=20480, flush_on_error_log=True)
+logger = Logger(level="INFO", buffer_config=logger_buffer_config)
 
 
 def lambda_handler(event: dict, context: LambdaContext):

examples/logger/src/working_with_buffering_logs_creating_instance.py

@@ -1,5 +1,5 @@
 from aws_lambda_powertools import Logger
 from aws_lambda_powertools.logging.buffer import LoggerBufferConfig
 
-logger_buffer_config = LoggerBufferConfig(max_size=20480, minimum_log_level="WARNING")
-logger = Logger(level="INFO", logger_buffer=logger_buffer_config)
+logger_buffer_config = LoggerBufferConfig(max_bytes=20480, buffer_at_verbosity="WARNING")
+logger = Logger(level="INFO", buffer_config=logger_buffer_config)

examples/logger/src/working_with_buffering_logs_different_levels.py

@@ -2,8 +2,8 @@
 from aws_lambda_powertools.logging.buffer import LoggerBufferConfig
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-logger_buffer_config = LoggerBufferConfig(minimum_log_level="WARNING")  # (1)!
-logger = Logger(level="INFO", logger_buffer=logger_buffer_config)
+logger_buffer_config = LoggerBufferConfig(buffer_at_verbosity="WARNING")  # (1)!
+logger = Logger(level="INFO", buffer_config=logger_buffer_config)
 
 
 def lambda_handler(event: dict, context: LambdaContext):

examples/logger/src/working_with_buffering_logs_disable_on_error.py

@@ -2,8 +2,8 @@
 from aws_lambda_powertools.logging.buffer import LoggerBufferConfig
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-logger_buffer_config = LoggerBufferConfig(max_size=20480, flush_on_error=False)
-logger = Logger(level="INFO", logger_buffer=logger_buffer_config)
+logger_buffer_config = LoggerBufferConfig(flush_on_error_log=False)  # (1)!
+logger = Logger(level="INFO", buffer_config=logger_buffer_config)
 
 
 class MyException(Exception):

examples/logger/src/working_with_buffering_logs_when_raise_exception.py

@@ -2,8 +2,8 @@
 from aws_lambda_powertools.logging.buffer import LoggerBufferConfig
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
-logger_buffer_config = LoggerBufferConfig(max_size=20480, flush_on_error=False)
-logger = Logger(level="INFO", logger_buffer=logger_buffer_config)
+logger_buffer_config = LoggerBufferConfig(max_bytes=20480, flush_on_error_log=False)
+logger = Logger(level="INFO", buffer_config=logger_buffer_config)
 
 
 class MyException(Exception):

tests/e2e/logger/handlers/buffer_logs_with_flush.py

@@ -1,9 +1,9 @@
 from aws_lambda_powertools import Logger
 from aws_lambda_powertools.logging.buffer import LoggerBufferConfig
 
-logger_buffer_config = LoggerBufferConfig(max_size=10240)
+logger_buffer_config = LoggerBufferConfig(max_bytes=10240)
 
-logger = Logger(level="INFO", logger_buffer=logger_buffer_config)
+logger = Logger(level="INFO", buffer_config=logger_buffer_config)
 
 
 def lambda_handler(event, context):

tests/e2e/logger/handlers/buffer_logs_without_flush.py

@@ -1,9 +1,9 @@
 from aws_lambda_powertools import Logger
 from aws_lambda_powertools.logging.buffer import LoggerBufferConfig
 
-logger_buffer_config = LoggerBufferConfig(max_size=10240)
+logger_buffer_config = LoggerBufferConfig(max_bytes=10240)
 
-logger = Logger(level="INFO", logger_buffer=logger_buffer_config)
+logger = Logger(level="INFO", buffer_config=logger_buffer_config)
 
 
 def lambda_handler(event, context):