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. The BurinFilterer 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:

bool

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 the BurinFilterer.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:

BurinLogRecord | bool

remove_filter(filter)

Removes the specified filter from the list of filters

Parameters:

filter (BurinFilter) – The filter to remove from this filterer instance.