How do you write a logging.Filter that redacts a token from every LogRecord?

## The protocol A logging filter is not a class you must inherit from. Anything with a `filter(record)` method qualifies, and since Python 3.2 a plain callable taking a `LogRecord` does too, so `lambda record: "tok_" not in record.getMessage()` is a legal filter. `logging.Filter` itself exists mostly for its one built-in behaviour: constructed with a name, it passes only records from that logger or its descendants. For redaction you subclass it (or write a callable) and ignore that behaviour. The return value has three meanings. Falsy means *drop this record* — no handler downstream of that point will see it. `True` means keep it. Since 3.12, returning a `LogRecord` instance means *use this record instead*, which lets you build a scrubbed copy rather than mutating the caller's data — useful because the same record object is shared by every handler on the propagation path. ## What to rewrite The interesting attributes are `record.msg` (the format string as passed) and `record.args` (the values). If the call site used lazy `%`-style arguments, the cleanest redaction is structural: walk `record.args` and replace the elements that are credentials. If the call site interpolated eagerly you are left with prose, and the only option is a regex over `record.getMessage()`. A common shape collapses both: ```python record.msg = SECRET_RE.sub("<redacted>", record.getMessage()) record.args = () ``` Clearing `args` is not optional. `getMessage()` runs `msg % self.args` whenever `args` is truthy, so leaving the old tuple in place means the finished text is interpolated a second time — which raises on a stray `%` or silently corrupts the line. Do not stop at the message. A `LogRecord` also carries whatever the call passed as `extra=`, set directly as attributes on the record, and a formatter whose format string names them will print them untouched. `record.name`, `record.pathname`, `record.funcName` and the exception text attached to the record are all rendered by some format strings. If your redaction only looks at the message, an `extra={"authorization": token}` walks straight past it. ## Where to attach it — the mistake that matters `Logger.addFilter` and `Handler.addFilter` sound symmetric and are not. When you log on `"svc.db"`, `Logger.handle` applies *that logger's* filters and then calls `callHandlers`, which walks up the ancestor chain invoking the **handlers** it finds. Ancestor loggers' filters are never consulted. So a redaction filter attached to `"svc"`, or even to the root logger, silently misses every record produced by a child logger — which, in a package that follows the `getLogger(__name__)` convention, is essentially all of them. A filter on a handler sees every record that reaches that handler, whichever logger produced it. That is the placement for a security control. The cost is that you must attach it to each handler, which is exactly what `logging.config.dictConfig` is for: declare the filter once in the `filters` section and list its key under each handler's `filters`. ## Failure modes to expect A filter that raises does not fail quietly. Filters run outside the `try` that routes emit errors to `Handler.handleError`, so an exception inside `filter()` propagates out of the `log.info(...)` call and into the application. For a redaction filter that is arguably the safer default — a broken scrubber that returns nothing would leak — but it must be a deliberate choice, and the filter body should be simple enough to trust. A filter is also a blunt instrument for a fundamentally lossy job. Regexes over free text miss formats they were not written for, and mangle innocent text that resembles one; a token that reaches the record inside a nested dict's `repr` is not going to be matched at all. Redaction at the log boundary is a backstop, not a substitute for not passing secrets to log calls in the first place. Treat a hit in the filter as a signal that some call site needs fixing, and consider having the filter count its hits so that signal is visible. ## Related knobs `logging.setLogRecordFactory` replaces the callable that builds every record, which is the place for adding attributes rather than removing them. `logging.LoggerAdapter` lets a caller inject contextual data on the way in. Neither is a redaction point: they run at record creation, before you know which handler will render what.