Fixed #17069 -- Added log filter example to docs.

Added an example of filtering admin error emails (to exclude
UnreadablePostErrors) to the docs.

1 files changed, 29 insertions, 0 deletions

diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt
index 9bdd706355..b54a9475ae 100644
--- a/docs/topics/logging.txt
+++ b/docs/topics/logging.txt
@@ -516,6 +516,35 @@ logging module.
    through the filter. Handling of that record will not proceed if the callback
    returns False.
 
+   For instance, to filter out :class:`~django.http.UnreadablePostError`
+   (raised when a user cancels an upload) from the admin emails, you would
+   create a filter function::
+
+    from django.http import UnreadablePostError
+
+    def skip_unreadable_post(record):
+        if record.exc_info:
+            exc_type, exc_value = record.exc_info[:2]
+            if isinstance(exc_value, UnreadablePostError):
+                return False
+        return True
+
+   and then add it to your logging config::
+
+        'filters': {
+            'skip_unreadable_posts': {
+                '()': 'django.utils.log.CallbackFilter',
+                'callback': skip_unreadable_post,
+            }
+        },
+        'handlers': {
+            'mail_admins': {
+                'level': 'ERROR',
+                'filters': ['skip_unreadable_posts'],
+                'class': 'django.utils.log.AdminEmailHandler'
+            }
+        },
+
 .. class:: RequireDebugFalse()
 
    .. versionadded:: 1.4