diff options
| -rw-r--r-- | Doc/library/logging.rst | 16 |
1 files changed, 15 insertions, 1 deletions
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index ee1bc84415..3427624065 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1479,6 +1479,8 @@ When this script is run, the output should look something like this:: The :class:`LoggerAdapter` class was not present in previous versions. +.. _filters-contextual: + Using Filters to impart contextual information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -2657,7 +2659,7 @@ Currently, the useful mapping keys in a :class:`LogRecord` are: Filter Objects -------------- -Filters can be used by :class:`Handler`\ s and :class:`Logger`\ s for +:class:`Filter`\ s can be used by :class:`Handler`\ s and :class:`Logger`\ s for more sophisticated filtering than is provided by levels. The base filter class only allows events which are below a certain point in the logger hierarchy. For example, a filter initialized with "A.B" will allow events logged by loggers @@ -2685,6 +2687,18 @@ etc.) This means that events which have been generated by descendant loggers will not be filtered by a logger's filter setting, unless the filter has also been applied to those descendant loggers. +Other uses for filters +^^^^^^^^^^^^^^^^^^^^^^ + +Although filters are used primarily to filter records based on more +sophisticated criteria than levels, they get to see every record which is +processed by the handler or logger they're attached to: this can be useful if +you want to do things like counting how many records were processed by a +particular logger or handler, or adding, changing or removing attributes in +the LogRecord being processed. Obviously changing the LogRecord needs to be +done with some care, but it does allow the injection of contextual information +into logs (see :ref:`filters-contextual`). + .. _log-record: LogRecord Objects |