Improved Filter documentation.

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index ee1bc844155ae7443a253567e856d69fce9e4ab5..342762406584115b66f53d37719f6086fbb93de5 100644 (file)
--- 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