Improved Filter documentation.

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index d9fcb230e88ad27224aac44be3d7c247ef2e962a..7b579f15c51d502bcb8d61cc5a041f81edb2fd66 100644 (file)
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1465,6 +1465,8 @@ When this script is run, the output should look something like this::
    2008-01-18 14:49:54,033 d.e.f WARNING  IP: 127.0.0.1       User: jim      A message at WARNING level with 2 parameters
 
 
+.. _filters-contextual:
+
 Using Filters to impart contextual information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -2852,6 +2854,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