feat(logging): configurable standard-library log filters (#195)

Adds `logging_record_filters` to `LoggingConfig`: a map of exact logger name to
`logging.Filter` instances, attached during `LoggingInstrument.bootstrap()` and
removed pairwise during `teardown()`. Every framework config inherits it.

Filters go on the logger rather than a handler or a structlog processor because
`logging.Logger.handle` runs them before `callHandlers`, where Sentry's
`LoggingIntegration` patches in. A filter can therefore demote or drop a foreign
`LogRecord` before any handler renders it and before Sentry creates an issue,
whatever order the bootstrapper installs the two instruments in — only
`FreeBootstrapper` installs logging first.

`LitestarLoggingInstrument` now overrides `_configure_structlog_loggers` instead
of the whole `bootstrap()`. Its override reimplemented the base's steps verbatim,
so any new step the base gained was silently skipped for Litestar users; filter
attachment was the first such step.

Default is empty, no new runtime dependency, existing configs unaffected.

Author: lesnik512

CONTEXT.md

@@ -57,3 +57,12 @@ and traceback together. One event is one rendered line is one physical line of s
 never diverge.
 _Avoid_: formatted message — reserve that for Sentry's own `logentry.formatted` field, which holds
 a rendered line only until the seam lifts the message out of it.
+
+**Record filter**:
+A `logging.Filter` attached to a named standard-library logger through `logging_record_filters`. It
+runs inside `Logger.handle`, so it sees a `LogRecord` before any handler renders it and before
+Sentry's patched `callHandlers` turns it into an issue; it may rewrite the record or drop it. The
+logger name is exact — a filter on `package` never sees `package.child`.
+_Avoid_: processor — a structlog processor runs on an event dict inside the rendering chain, too
+late to change what Sentry captured; `logging_extra_processors` takes those. Also avoid bare
+"filter" where a handler filter or `structlog.stdlib.filter_by_level` could be meant.

docs/introduction/configuration.md

@@ -114,6 +114,7 @@ Additional parameters:
 - `logging_buffer_capacity`
 - `logging_extra_processors`
 - `logging_unset_handlers`
+- `logging_record_filters` - standard-library `logging.Filter` instances to attach to named loggers (see below).
 - `logging_time_stamper` - a `structlog.processors.TimeStamper` instance controlling timestamp format (default: `TimeStamper(fmt="iso")`). Pass a custom instance to change the format or enable UTC:
 
 ```python
@@ -125,6 +126,40 @@ config = FastAPIConfig(
 )
 ```
 
+### Filtering standard-library log records
+
+`logging_record_filters` attaches `logging.Filter` instances to loggers by name. A filter sees every
+record its logger emits, before any handler renders it, and may rewrite the record or return `False`
+to drop it — useful for demoting a third-party error you already handle:
+
+```python
+import logging
+
+from lite_bootstrap import FreeBootstrapper, FreeConfig
+
+
+class ExpectedFailureFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        if record.levelno == logging.ERROR and "expected failure" in record.getMessage():
+            record.levelno = logging.WARNING
+            record.levelname = "WARNING"
+        return True
+
+
+bootstrapper = FreeBootstrapper(
+    bootstrap_config=FreeConfig(
+        logging_record_filters={"some_library.worker": (ExpectedFailureFilter(),)},
+    ),
+)
+```
+
+- **Set both `levelno` and `levelname`** when changing a level: handlers read them independently.
+- **The logger name is exact.** A filter on `some_library` never sees `some_library.worker`, and
+  `""` is the root logger, matching only records logged through root itself. That is standard
+  `logging` behaviour: a logger consults its own filters, then its ancestors' *handlers*.
+- **Teardown removes only what it attached**, leaving filters your application put on the same
+  logger in place.
+
 ### Structlog Litestar
 
 When using Litestar, the `StructlogPlugin` is automatically registered, which enables `request.logger` inside route handlers:

lite_bootstrap/bootstrappers/litestar_bootstrapper.py

@@ -226,8 +226,8 @@ def _build_logging_middleware_config(self) -> "LoggingMiddlewareConfig":
             exclude=excluded_paths or None,
         )
 
-    def bootstrap(self) -> None:
-        self._unset_handlers()
+    def _configure_structlog_loggers(self) -> None:
+        """Register Litestar's StructlogPlugin instead of calling ``structlog.configure`` directly."""
         self.bootstrap_config.application_config.plugins.append(
             StructlogPlugin(
                 config=StructlogConfig(
@@ -245,7 +245,6 @@ def bootstrap(self) -> None:
                 ),
             )
         )
-        self._configure_foreign_loggers()
 
 
 @dataclasses.dataclass(kw_only=True)

lite_bootstrap/instruments/logging_instrument.py

@@ -73,6 +73,7 @@ class LoggingConfig(BaseConfig):
     logging_unset_handlers: list[str] = dataclasses.field(
         default_factory=list,
     )
+    logging_record_filters: dict[str, tuple[logging.Filter, ...]] = dataclasses.field(default_factory=dict)
     logging_time_stamper: "structlog.processors.TimeStamper | None" = None
     logging_enabled: bool = True
 
@@ -84,6 +85,9 @@ class LoggingInstrument(BaseInstrument[LoggingConfig]):
     _logger_factory: "MemoryLoggerFactory | None" = dataclasses.field(
         default_factory=lambda: None, init=False, repr=False, compare=False
     )
+    _attached_filters: list[tuple[logging.Logger, logging.Filter]] = dataclasses.field(
+        default_factory=list, init=False, repr=False, compare=False
+    )
 
     @property
     def structlog_pre_chain_processors(self) -> list[typing.Any]:
@@ -160,15 +164,32 @@ def _configure_foreign_loggers(self) -> None:
         root_logger.addHandler(stream_handler)
         root_logger.setLevel(self.bootstrap_config.logging_log_level)
 
+    def _attach_record_filters(self) -> None:
+        """Attach each configured filter to its logger, remembering the pair for teardown."""
+        for logger_name, record_filters in self.bootstrap_config.logging_record_filters.items():
+            target_logger = logging.getLogger(logger_name)
+            for record_filter in record_filters:
+                target_logger.addFilter(record_filter)
+                self._attached_filters.append((target_logger, record_filter))
+
+    def _detach_record_filters(self) -> None:
+        """Remove only the filters this instrument attached, leaving any others in place."""
+        for target_logger, record_filter in self._attached_filters:
+            target_logger.removeFilter(record_filter)
+        self._attached_filters.clear()
+
     def bootstrap(self) -> None:
         self._unset_handlers()
         self._configure_structlog_loggers()
         self._configure_foreign_loggers()
+        self._attach_record_filters()
 
     def teardown(self) -> None:
         """Reset structlog and root logger.
 
         Root logger level is unconditionally set to WARNING; pre-existing user configuration is overwritten.
+        Filters from ``logging_record_filters`` are removed one pair at a time, so a filter the
+        application or another library put on the same logger survives.
 
         Best-effort cleanup: errors from individual ``handler.close()`` calls and from the memory
         logger factory's ``close_handlers()`` are collected and re-raised together via
@@ -188,6 +209,7 @@ def teardown(self) -> None:
                     errors.append((type(h).__name__, e))
             root_logger.setLevel(logging.WARNING)
         finally:
+            self._detach_record_filters()
             if self._logger_factory is not None:
                 try:
                     self._logger_factory.close_handlers()