Filters and Filterers
Filters can be used to determine if specific log records should be logged or not, and also provide the ability to modify records during processing.
Both BurinLogger
and BurinHandler
are subclasses of
BurinFilterer
. When processing a logging event all filter checks
will be done on the record to determine if it should be logged.
Custom filters can be created by subclassing BurinFilter
and
overriding the BurinFilter.filter()
method to perform custom checks or
modify log records in place during processing.
BurinFilter
The default BurinFilter
is based on logging.Filter
and
should function identically to it; it is not a subclass of it though.
- class burin.BurinFilter(name='')
A filter can be used to apply filtering or modification of log records.
Note
This functions identically to the standard library
logging.Filter
class.The base filter by default will allow all events which are lower in the logger hierarchy.
This creates the filter for the specified name.
The name of logger is used to allow only events from the specified logger and all loggers lower in the hierarchy. If this is an empty string the all events are allowed.
- Parameters:
name (str) – The name of the logger to allow events from along with all other loggers lower in the hierarchy. All events are allowed if this is an empty string. (Default = ‘’)
- filter(record)
Determines if the record should be logged.
Note
If you are subclassing
BurinFilter
and intend to modify the log record then the modified record should also be returned. TheBurinFilterer
will then use the modified record for all further processing and return it to the original caller.- Parameters:
record (BurinLogRecord) – The record to check.
- Returns:
Whether the record should be logged or not.
- Return type:
BurinFilterer
This is a base class that is subclassed by both BurinLogger
and
BurinHandler
so that filtering functionality can be re-used in both.
While this is based on the standard library logging.Filterer
it is not
a subclass of it.
Note
All methods of the BurinFilterer
with an underscore_separated
name also have a camelCase alias name which matches the names used in the
standard logging
library.
- class burin.BurinFilterer
A base class for loggers and handlers to allow common code for filtering.
Note
This works identically to the
logging.Filterer
in Python 3.12. The class is recreated in Burin to simplify allowing theBurinFilterer.filter()
method to return a log record. This was added to the standard library in 3.12 and is supported here for all versions of Python compatible with Burin (including versions below 3.12).Initializes the filterer with an empty list of filters.
- add_filter(filter)
Adds the specified filter to the the list of filters.
- Parameters:
filter (BurinFilter) – The filter to add to this filterer instance.
- filter(record)
Determine if a record is loggable according to all filters.
All filters are checked in the order that they were added using the
BurinFilterer.add_filter()
method. If any filter returns False the record will not be logged.If a filter returns a log record instance then that instance will be used for all further processing.
If none of the filters return False then a log record will be returned. If any filters returned an instance of a log record then the returned record will be the last instance that was returned by a filter.
However if any filter does return a False value then this method will also return a false value.
Note
In Python 3.12 the ability for a filterer to return a record was added to the standard library; it is supported here for all versions of Python compatible with Burin (including versions below 3.12).
- Parameters:
record (BurinLogRecord) – The log record instance to check.
- Returns:
An instance of the record if it should be logged or False if it shouldn’t. If any filters modified the record or returned an different instance of a record then that is what will be returned here. It should be used for all further processing and handling of the log record event.
- Return type:
- remove_filter(filter)
Removes the specified filter from the list of filters
- Parameters:
filter (BurinFilter) – The filter to remove from this filterer instance.