improv: add comments on Log Record filtering

Author: heitorlessa

aws_lambda_powertools/logging/filters.py

@@ -6,7 +6,11 @@ def __init__(self, logger):
         self.logger = logger
 
     def filter(self, record):  # noqa: A003
-        """Suppress Log Records from registered logger"""
-        if self.logger in record.name:
-            return False
-        return True
+        """Suppress Log Records from registered logger
+
+        It rejects log records from registered logger e.g. a child logger
+        otherwise it honours log propagation from any log record
+        created by loggers who don't have a handler.
+        """
+        logger = record.name
+        return False if self.logger in logger else True

aws_lambda_powertools/logging/logger.py

@@ -159,6 +159,9 @@ def _init_logger(self, **kwargs):
 
             logger.debug("Adding filter in root logger to suppress child logger records to bubble up")
             for handler in logging.root.handlers:
+                # It'll add a filter to suppress any child logger from self.service
+                # Where service is Order, it'll reject parent logger Order,
+                # and child loggers such as Order.checkout, Order.shared
                 handler.addFilter(SuppressFilter(self.service))
 
     def _configure_sampling(self):