Code

Ticket #12012: t12012-rc1.diff

File t12012-rc1.diff, 62.0 KB (added by russellm, 4 years ago)

RC1 of logging patch

Line 
1diff -r d861e2426ce4 django/conf/__init__.py
2--- a/django/conf/__init__.py   Tue Sep 28 14:52:20 2010 +0000
3+++ b/django/conf/__init__.py   Thu Sep 30 21:31:39 2010 +0800
4@@ -16,6 +16,7 @@
5 
6 ENVIRONMENT_VARIABLE = "DJANGO_SETTINGS_MODULE"
7 
8+
9 class LazySettings(LazyObject):
10     """
11     A lazy proxy for either global Django settings or a custom settings object.
12@@ -114,6 +115,16 @@
13             os.environ['TZ'] = self.TIME_ZONE
14             time.tzset()
15 
16+        # Settings are configured, so we can set up the logger if required
17+        if self.LOGGING_CONFIG:
18+            # First find the logging configuration function ...
19+            logging_config_path, logging_config_func_name = self.LOGGING_CONFIG.rsplit('.', 1)
20+            logging_config_module = importlib.import_module(logging_config_path)
21+            logging_config_func = getattr(logging_config_module, logging_config_func_name)
22+
23+            # ... then invoke it with the logging settings
24+            logging_config_func(self.LOGGING)
25+
26 class UserSettingsHolder(object):
27     """
28     Holder for user configured settings.
29diff -r d861e2426ce4 django/conf/global_settings.py
30--- a/django/conf/global_settings.py    Tue Sep 28 14:52:20 2010 +0000
31+++ b/django/conf/global_settings.py    Thu Sep 30 21:31:39 2010 +0800
32@@ -499,6 +499,50 @@
33 # django.contrib.messages to avoid imports in this settings file.
34 
35 ###########
36+# LOGGING #
37+###########
38+
39+# The callable to use to configure logging
40+LOGGING_CONFIG = 'django.utils.log.dictConfig'
41+
42+# The default logging configuration
43+LOGGING = {
44+    'version': 1,
45+    'disable_existing_loggers': False,
46+    'handlers': {
47+        'null': {
48+            'level':'DEBUG',
49+            'class':'django.utils.log.NullHandler',
50+        },
51+        'console':{
52+            'level':'DEBUG',
53+            'class':'logging.StreamHandler',
54+        },
55+        'mail_admins': {
56+            'level': 'ERROR',
57+            'class': 'django.utils.log.AdminEmailHandler'
58+        }
59+    },
60+    'loggers': {
61+        'django': {
62+            'handlers':['null'],
63+            'propagate': True,
64+            'level':'INFO',
65+        },
66+        'django.db.backends':{
67+            'handlers': [],
68+            'level': 'INFO',
69+            'propagate': True,
70+        },
71+        'django.request':{
72+            'handlers': ['mail_admins'],
73+            'level': 'ERROR',
74+            'propagate': True,
75+        },
76+    }
77+}
78+
79+###########
80 # TESTING #
81 ###########
82 
83diff -r d861e2426ce4 django/conf/project_template/settings.py
84--- a/django/conf/project_template/settings.py  Tue Sep 28 14:52:20 2010 +0000
85+++ b/django/conf/project_template/settings.py  Thu Sep 30 21:31:39 2010 +0800
86@@ -94,3 +94,39 @@
87     # Uncomment the next line to enable admin documentation:
88     # 'django.contrib.admindocs',
89 )
90+
91+LOGGING = {
92+    'version': 1,
93+    'disable_existing_loggers': False,
94+    'handlers': {
95+        'null': {
96+            'level':'DEBUG',
97+            'class':'django.utils.log.NullHandler',
98+        },
99+        'console':{
100+            'level':'DEBUG',
101+            'class':'logging.StreamHandler',
102+        },
103+        'mail_admins': {
104+            'level': 'ERROR',
105+            'class': 'django.utils.log.AdminEmailHandler'
106+        }
107+    },
108+    'loggers': {
109+        'django': {
110+            'handlers':['null'],
111+            'propagate': True,
112+            'level':'INFO',
113+        },
114+        'django.db.backends':{
115+            'handlers': [],
116+            'level': 'INFO',
117+            'propagate': True,
118+        },
119+        'django.request':{
120+            'handlers': ['mail_admins'],
121+            'level': 'ERROR',
122+            'propagate': True,
123+        },
124+    }
125+}
126diff -r d861e2426ce4 django/core/handlers/base.py
127--- a/django/core/handlers/base.py      Tue Sep 28 14:52:20 2010 +0000
128+++ b/django/core/handlers/base.py      Thu Sep 30 21:31:39 2010 +0800
129@@ -1,3 +1,4 @@
130+import logging
131 import sys
132 
133 from django import http
134@@ -5,6 +6,9 @@
135 from django.utils.encoding import force_unicode
136 from django.utils.importlib import import_module
137 
138+logger = logging.getLogger('django.request')
139+
140+
141 class BaseHandler(object):
142     # Changes that are always applied to a response (in this order).
143     response_fixes = [
144@@ -118,6 +122,11 @@
145 
146                 return response
147             except http.Http404, e:
148+                logger.warning('Not Found: %s' % request.path,
149+                            extra={
150+                                'status_code': 404,
151+                                'request': request
152+                            })
153                 if settings.DEBUG:
154                     from django.views import debug
155                     return debug.technical_404_response(request, e)
156@@ -131,6 +140,11 @@
157                         finally:
158                             receivers = signals.got_request_exception.send(sender=self.__class__, request=request)
159             except exceptions.PermissionDenied:
160+                logger.warning('Forbidden (Permission denied): %s' % request.path,
161+                            extra={
162+                                'status_code': 403,
163+                                'request': request
164+                            })
165                 return http.HttpResponseForbidden('<h1>Permission denied</h1>')
166             except SystemExit:
167                 # Allow sys.exit() to actually exit. See tickets #1023 and #4701
168@@ -155,7 +169,6 @@
169         available would be an error.
170         """
171         from django.conf import settings
172-        from django.core.mail import mail_admins
173 
174         if settings.DEBUG_PROPAGATE_EXCEPTIONS:
175             raise
176@@ -164,14 +177,14 @@
177             from django.views import debug
178             return debug.technical_500_response(request, *exc_info)
179 
180-        # When DEBUG is False, send an error message to the admins.
181-        subject = 'Error (%s IP): %s' % ((request.META.get('REMOTE_ADDR') in settings.INTERNAL_IPS and 'internal' or 'EXTERNAL'), request.path)
182-        try:
183-            request_repr = repr(request)
184-        except:
185-            request_repr = "Request repr() unavailable"
186-        message = "%s\n\n%s" % (self._get_traceback(exc_info), request_repr)
187-        mail_admins(subject, message, fail_silently=True)
188+        logger.error('Internal Server Error: %s' % request.path,
189+            exc_info=exc_info,
190+            extra={
191+                'status_code': 500,
192+                'request':request
193+            }
194+        )
195+
196         # If Http500 handler is not installed, re-raise last exception
197         if resolver.urlconf_module is None:
198             raise exc_info[1], None, exc_info[2]
199@@ -179,11 +192,6 @@
200         callback, param_dict = resolver.resolve500()
201         return callback(request, **param_dict)
202 
203-    def _get_traceback(self, exc_info=None):
204-        "Helper function to return the traceback as a string"
205-        import traceback
206-        return '\n'.join(traceback.format_exception(*(exc_info or sys.exc_info())))
207-
208     def apply_response_fixes(self, request, response):
209         """
210         Applies each of the functions in self.response_fixes to the request and
211diff -r d861e2426ce4 django/core/handlers/modpython.py
212--- a/django/core/handlers/modpython.py Tue Sep 28 14:52:20 2010 +0000
213+++ b/django/core/handlers/modpython.py Thu Sep 30 21:31:39 2010 +0800
214@@ -1,5 +1,7 @@
215+import logging
216 import os
217 from pprint import pformat
218+import sys
219 from warnings import warn
220 
221 from django import http
222@@ -9,6 +11,9 @@
223 from django.utils import datastructures
224 from django.utils.encoding import force_unicode, smart_str, iri_to_uri
225 
226+logger = logging.getLogger('django.request')
227+
228+
229 # NOTE: do *not* import settings (or any module which eventually imports
230 # settings) until after ModPythonHandler has been called; otherwise os.environ
231 # won't be set up correctly (with respect to settings).
232@@ -200,6 +205,13 @@
233             try:
234                 request = self.request_class(req)
235             except UnicodeDecodeError:
236+                logger.warning('Bad Request (UnicodeDecodeError): %s' % request.path,
237+                    exc_info=sys.exc_info(),
238+                    extra={
239+                        'status_code': 400,
240+                        'request': request
241+                    }
242+                )
243                 response = http.HttpResponseBadRequest()
244             else:
245                 response = self.get_response(request)
246diff -r d861e2426ce4 django/core/handlers/wsgi.py
247--- a/django/core/handlers/wsgi.py      Tue Sep 28 14:52:20 2010 +0000
248+++ b/django/core/handlers/wsgi.py      Thu Sep 30 21:31:39 2010 +0800
249@@ -1,5 +1,7 @@
250+import logging
251+from pprint import pformat
252+import sys
253 from threading import Lock
254-from pprint import pformat
255 try:
256     from cStringIO import StringIO
257 except ImportError:
258@@ -12,6 +14,9 @@
259 from django.utils import datastructures
260 from django.utils.encoding import force_unicode, iri_to_uri
261 
262+logger = logging.getLogger('django.request')
263+
264+
265 # See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
266 STATUS_CODE_TEXT = {
267     100: 'CONTINUE',
268@@ -236,6 +241,13 @@
269             try:
270                 request = self.request_class(environ)
271             except UnicodeDecodeError:
272+                logger.warning('Bad Request (UnicodeDecodeError): %s' % request.path,
273+                    exc_info=sys.exc_info(),
274+                    extra={
275+                        'status_code': 400,
276+                        'request': request
277+                    }
278+                )
279                 response = http.HttpResponseBadRequest()
280             else:
281                 response = self.get_response(request)
282diff -r d861e2426ce4 django/db/backends/util.py
283--- a/django/db/backends/util.py        Tue Sep 28 14:52:20 2010 +0000
284+++ b/django/db/backends/util.py        Thu Sep 30 21:31:39 2010 +0800
285@@ -1,9 +1,12 @@
286 import datetime
287 import decimal
288+import logging
289 from time import time
290 
291 from django.utils.hashcompat import md5_constructor
292 
293+logger = logging.getLogger('django.db.backends')
294+
295 class CursorDebugWrapper(object):
296     def __init__(self, cursor, db):
297         self.cursor = cursor
298@@ -15,11 +18,15 @@
299             return self.cursor.execute(sql, params)
300         finally:
301             stop = time()
302+            duration = stop - start
303             sql = self.db.ops.last_executed_query(self.cursor, sql, params)
304             self.db.queries.append({
305                 'sql': sql,
306-                'time': "%.3f" % (stop - start),
307+                'time': "%.3f" % duration,
308             })
309+            logger.debug('(%.3f) %s; args=%s' % (duration, sql, params),
310+                extra={'duration':duration, 'sql':sql, 'params':params}
311+            )
312 
313     def executemany(self, sql, param_list):
314         start = time()
315@@ -27,10 +34,14 @@
316             return self.cursor.executemany(sql, param_list)
317         finally:
318             stop = time()
319+            duration = stop - start
320             self.db.queries.append({
321                 'sql': '%s times: %s' % (len(param_list), sql),
322-                'time': "%.3f" % (stop - start),
323+                'time': "%.3f" % duration,
324             })
325+            logger.debug('(%.3f) %s; args=%s' % (duration, sql, param_list),
326+                extra={'duration':duration, 'sql':sql, 'params':param_list}
327+            )
328 
329     def __getattr__(self, attr):
330         if attr in self.__dict__:
331diff -r d861e2426ce4 django/middleware/common.py
332--- a/django/middleware/common.py       Tue Sep 28 14:52:20 2010 +0000
333+++ b/django/middleware/common.py       Thu Sep 30 21:31:39 2010 +0800
334@@ -1,3 +1,4 @@
335+import logging
336 import re
337 
338 from django.conf import settings
339@@ -7,6 +8,9 @@
340 from django.core import urlresolvers
341 from django.utils.hashcompat import md5_constructor
342 
343+logger = logging.getLogger('django.request')
344+
345+
346 class CommonMiddleware(object):
347     """
348     "Common" middleware for taking care of some basic operations:
349@@ -38,6 +42,12 @@
350         if 'HTTP_USER_AGENT' in request.META:
351             for user_agent_regex in settings.DISALLOWED_USER_AGENTS:
352                 if user_agent_regex.search(request.META['HTTP_USER_AGENT']):
353+                    logger.warning('Forbidden (User agent): %s' % request.path,
354+                        extra={
355+                            'status_code': 403,
356+                            'request': request
357+                        }
358+                    )
359                     return http.HttpResponseForbidden('<h1>Forbidden</h1>')
360 
361         # Check for a redirect based on settings.APPEND_SLASH
362diff -r d861e2426ce4 django/middleware/csrf.py
363--- a/django/middleware/csrf.py Tue Sep 28 14:52:20 2010 +0000
364+++ b/django/middleware/csrf.py Thu Sep 30 21:31:39 2010 +0800
365@@ -6,6 +6,7 @@
366 """
367 
368 import itertools
369+import logging
370 import re
371 import random
372 
373@@ -20,6 +21,8 @@
374 
375 _HTML_TYPES = ('text/html', 'application/xhtml+xml')
376 
377+logger = logging.getLogger('django.request')
378+
379 # Use the system (hardware-based) random number generator if it exists.
380 if hasattr(random, 'SystemRandom'):
381     randrange = random.SystemRandom().randrange
382@@ -169,14 +172,26 @@
383                 # we can use strict Referer checking.
384                 referer = request.META.get('HTTP_REFERER')
385                 if referer is None:
386+                    logger.warning('Forbidden (%s): %s' % (REASON_NO_COOKIE, request.path),
387+                        extra={
388+                            'status_code': 403,
389+                            'request': request,
390+                        }
391+                    )
392                     return reject(REASON_NO_REFERER)
393 
394                 # The following check ensures that the referer is HTTPS,
395                 # the domains match and the ports match - the same origin policy.
396                 good_referer = 'https://%s/' % request.get_host()
397                 if not referer.startswith(good_referer):
398-                    return reject(REASON_BAD_REFERER %
399-                                  (referer, good_referer))
400+                    reason = REASON_BAD_REFERER % (referer, good_referer)
401+                    logger.warning('Forbidden (%s): %s' % (reason, request.path),
402+                        extra={
403+                            'status_code': 403,
404+                            'request': request,
405+                        }
406+                    )
407+                    return reject(reason)
408 
409             # If the user didn't already have a CSRF cookie, then fall back to
410             # the Django 1.1 method (hash of session ID), so a request is not
411@@ -190,6 +205,12 @@
412                     # No CSRF cookie and no session cookie. For POST requests,
413                     # we insist on a CSRF cookie, and in this way we can avoid
414                     # all CSRF attacks, including login CSRF.
415+                    logger.warning('Forbidden (%s): %s' % (REASON_NO_COOKIE, request.path),
416+                        extra={
417+                            'status_code': 403,
418+                            'request': request,
419+                        }
420+                    )
421                     return reject(REASON_NO_COOKIE)
422             else:
423                 csrf_token = request.META["CSRF_COOKIE"]
424@@ -199,8 +220,20 @@
425             if request_csrf_token != csrf_token:
426                 if cookie_is_new:
427                     # probably a problem setting the CSRF cookie
428+                    logger.warning('Forbidden (%s): %s' % (REASON_NO_CSRF_COOKIE, request.path),
429+                        extra={
430+                            'status_code': 403,
431+                            'request': request,
432+                        }
433+                    )
434                     return reject(REASON_NO_CSRF_COOKIE)
435                 else:
436+                    logger.warning('Forbidden (%s): %s' % (REASON_BAD_TOKEN, request.path),
437+                        extra={
438+                            'status_code': 403,
439+                            'request': request,
440+                        }
441+                    )
442                     return reject(REASON_BAD_TOKEN)
443 
444         return accept()
445diff -r d861e2426ce4 django/utils/dictconfig.py
446--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
447+++ b/django/utils/dictconfig.py        Thu Sep 30 21:31:39 2010 +0800
448@@ -0,0 +1,553 @@
449+# This is a copy of the Python logging.config.dictconfig module,
450+# reproduced with permission. It is provided here for backwards
451+# compatibility for Python versions prior to 2.7.
452+#
453+# Copyright 2009-2010 by Vinay Sajip. All Rights Reserved.
454+#
455+# Permission to use, copy, modify, and distribute this software and its
456+# documentation for any purpose and without fee is hereby granted,
457+# provided that the above copyright notice appear in all copies and that
458+# both that copyright notice and this permission notice appear in
459+# supporting documentation, and that the name of Vinay Sajip
460+# not be used in advertising or publicity pertaining to distribution
461+# of the software without specific, written prior permission.
462+# VINAY SAJIP DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
463+# ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
464+# VINAY SAJIP BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
465+# ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
466+# IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
467+# OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
468+
469+import logging.handlers
470+import re
471+import sys
472+import types
473+
474+IDENTIFIER = re.compile('^[a-z_][a-z0-9_]*$', re.I)
475+
476+def valid_ident(s):
477+    m = IDENTIFIER.match(s)
478+    if not m:
479+        raise ValueError('Not a valid Python identifier: %r' % s)
480+    return True
481+
482+#
483+# This function is defined in logging only in recent versions of Python
484+#
485+try:
486+    from logging import _checkLevel
487+except ImportError:
488+    def _checkLevel(level):
489+        if isinstance(level, int):
490+            rv = level
491+        elif str(level) == level:
492+            if level not in logging._levelNames:
493+                raise ValueError('Unknown level: %r' % level)
494+            rv = logging._levelNames[level]
495+        else:
496+            raise TypeError('Level not an integer or a '
497+                            'valid string: %r' % level)
498+        return rv
499+
500+# The ConvertingXXX classes are wrappers around standard Python containers,
501+# and they serve to convert any suitable values in the container. The
502+# conversion converts base dicts, lists and tuples to their wrapped
503+# equivalents, whereas strings which match a conversion format are converted
504+# appropriately.
505+#
506+# Each wrapper should have a configurator attribute holding the actual
507+# configurator to use for conversion.
508+
509+class ConvertingDict(dict):
510+    """A converting dictionary wrapper."""
511+
512+    def __getitem__(self, key):
513+        value = dict.__getitem__(self, key)
514+        result = self.configurator.convert(value)
515+        #If the converted value is different, save for next time
516+        if value is not result:
517+            self[key] = result
518+            if type(result) in (ConvertingDict, ConvertingList,
519+                                ConvertingTuple):
520+                result.parent = self
521+                result.key = key
522+        return result
523+
524+    def get(self, key, default=None):
525+        value = dict.get(self, key, default)
526+        result = self.configurator.convert(value)
527+        #If the converted value is different, save for next time
528+        if value is not result:
529+            self[key] = result
530+            if type(result) in (ConvertingDict, ConvertingList,
531+                                ConvertingTuple):
532+                result.parent = self
533+                result.key = key
534+        return result
535+
536+    def pop(self, key, default=None):
537+        value = dict.pop(self, key, default)
538+        result = self.configurator.convert(value)
539+        if value is not result:
540+            if type(result) in (ConvertingDict, ConvertingList,
541+                                ConvertingTuple):
542+                result.parent = self
543+                result.key = key
544+        return result
545+
546+class ConvertingList(list):
547+    """A converting list wrapper."""
548+    def __getitem__(self, key):
549+        value = list.__getitem__(self, key)
550+        result = self.configurator.convert(value)
551+        #If the converted value is different, save for next time
552+        if value is not result:
553+            self[key] = result
554+            if type(result) in (ConvertingDict, ConvertingList,
555+                                ConvertingTuple):
556+                result.parent = self
557+                result.key = key
558+        return result
559+
560+    def pop(self, idx=-1):
561+        value = list.pop(self, idx)
562+        result = self.configurator.convert(value)
563+        if value is not result:
564+            if type(result) in (ConvertingDict, ConvertingList,
565+                                ConvertingTuple):
566+                result.parent = self
567+        return result
568+
569+class ConvertingTuple(tuple):
570+    """A converting tuple wrapper."""
571+    def __getitem__(self, key):
572+        value = tuple.__getitem__(self, key)
573+        result = self.configurator.convert(value)
574+        if value is not result:
575+            if type(result) in (ConvertingDict, ConvertingList,
576+                                ConvertingTuple):
577+                result.parent = self
578+                result.key = key
579+        return result
580+
581+class BaseConfigurator(object):
582+    """
583+    The configurator base class which defines some useful defaults.
584+    """
585+
586+    CONVERT_PATTERN = re.compile(r'^(?P<prefix>[a-z]+)://(?P<suffix>.*)$')
587+
588+    WORD_PATTERN = re.compile(r'^\s*(\w+)\s*')
589+    DOT_PATTERN = re.compile(r'^\.\s*(\w+)\s*')
590+    INDEX_PATTERN = re.compile(r'^\[\s*(\w+)\s*\]\s*')
591+    DIGIT_PATTERN = re.compile(r'^\d+$')
592+
593+    value_converters = {
594+        'ext' : 'ext_convert',
595+        'cfg' : 'cfg_convert',
596+    }
597+
598+    # We might want to use a different one, e.g. importlib
599+    importer = __import__
600+
601+    def __init__(self, config):
602+        self.config = ConvertingDict(config)
603+        self.config.configurator = self
604+
605+    def resolve(self, s):
606+        """
607+        Resolve strings to objects using standard import and attribute
608+        syntax.
609+        """
610+        name = s.split('.')
611+        used = name.pop(0)
612+        try:
613+            found = self.importer(used)
614+            for frag in name:
615+                used += '.' + frag
616+                try:
617+                    found = getattr(found, frag)
618+                except AttributeError:
619+                    self.importer(used)
620+                    found = getattr(found, frag)
621+            return found
622+        except ImportError:
623+            e, tb = sys.exc_info()[1:]
624+            v = ValueError('Cannot resolve %r: %s' % (s, e))
625+            v.__cause__, v.__traceback__ = e, tb
626+            raise v
627+
628+    def ext_convert(self, value):
629+        """Default converter for the ext:// protocol."""
630+        return self.resolve(value)
631+
632+    def cfg_convert(self, value):
633+        """Default converter for the cfg:// protocol."""
634+        rest = value
635+        m = self.WORD_PATTERN.match(rest)
636+        if m is None:
637+            raise ValueError("Unable to convert %r" % value)
638+        else:
639+            rest = rest[m.end():]
640+            d = self.config[m.groups()[0]]
641+            #print d, rest
642+            while rest:
643+                m = self.DOT_PATTERN.match(rest)
644+                if m:
645+                    d = d[m.groups()[0]]
646+                else:
647+                    m = self.INDEX_PATTERN.match(rest)
648+                    if m:
649+                        idx = m.groups()[0]
650+                        if not self.DIGIT_PATTERN.match(idx):
651+                            d = d[idx]
652+                        else:
653+                            try:
654+                                n = int(idx) # try as number first (most likely)
655+                                d = d[n]
656+                            except TypeError:
657+                                d = d[idx]
658+                if m:
659+                    rest = rest[m.end():]
660+                else:
661+                    raise ValueError('Unable to convert '
662+                                     '%r at %r' % (value, rest))
663+        #rest should be empty
664+        return d
665+
666+    def convert(self, value):
667+        """
668+        Convert values to an appropriate type. dicts, lists and tuples are
669+        replaced by their converting alternatives. Strings are checked to
670+        see if they have a conversion format and are converted if they do.
671+        """
672+        if not isinstance(value, ConvertingDict) and isinstance(value, dict):
673+            value = ConvertingDict(value)
674+            value.configurator = self
675+        elif not isinstance(value, ConvertingList) and isinstance(value, list):
676+            value = ConvertingList(value)
677+            value.configurator = self
678+        elif not isinstance(value, ConvertingTuple) and\
679+                 isinstance(value, tuple):
680+            value = ConvertingTuple(value)
681+            value.configurator = self
682+        elif isinstance(value, basestring): # str for py3k
683+            m = self.CONVERT_PATTERN.match(value)
684+            if m:
685+                d = m.groupdict()
686+                prefix = d['prefix']
687+                converter = self.value_converters.get(prefix, None)
688+                if converter:
689+                    suffix = d['suffix']
690+                    converter = getattr(self, converter)
691+                    value = converter(suffix)
692+        return value
693+
694+    def configure_custom(self, config):
695+        """Configure an object with a user-supplied factory."""
696+        c = config.pop('()')
697+        if not hasattr(c, '__call__') and hasattr(types, 'ClassType') and type(c) != types.ClassType:
698+            c = self.resolve(c)
699+        props = config.pop('.', None)
700+        # Check for valid identifiers
701+        kwargs = dict([(k, config[k]) for k in config if valid_ident(k)])
702+        result = c(**kwargs)
703+        if props:
704+            for name, value in props.items():
705+                setattr(result, name, value)
706+        return result
707+
708+    def as_tuple(self, value):
709+        """Utility function which converts lists to tuples."""
710+        if isinstance(value, list):
711+            value = tuple(value)
712+        return value
713+
714+class DictConfigurator(BaseConfigurator):
715+    """
716+    Configure logging using a dictionary-like object to describe the
717+    configuration.
718+    """
719+
720+    def configure(self):
721+        """Do the configuration."""
722+
723+        config = self.config
724+        if 'version' not in config:
725+            raise ValueError("dictionary doesn't specify a version")
726+        if config['version'] != 1:
727+            raise ValueError("Unsupported version: %s" % config['version'])
728+        incremental = config.pop('incremental', False)
729+        EMPTY_DICT = {}
730+        logging._acquireLock()
731+        try:
732+            if incremental:
733+                handlers = config.get('handlers', EMPTY_DICT)
734+                # incremental handler config only if handler name
735+                # ties in to logging._handlers (Python 2.7)
736+                if sys.version_info[:2] == (2, 7):
737+                    for name in handlers:
738+                        if name not in logging._handlers:
739+                            raise ValueError('No handler found with '
740+                                             'name %r'  % name)
741+                        else:
742+                            try:
743+                                handler = logging._handlers[name]
744+                                handler_config = handlers[name]
745+                                level = handler_config.get('level', None)
746+                                if level:
747+                                    handler.setLevel(_checkLevel(level))
748+                            except StandardError, e:
749+                                raise ValueError('Unable to configure handler '
750+                                                 '%r: %s' % (name, e))
751+                loggers = config.get('loggers', EMPTY_DICT)
752+                for name in loggers:
753+                    try:
754+                        self.configure_logger(name, loggers[name], True)
755+                    except StandardError, e:
756+                        raise ValueError('Unable to configure logger '
757+                                         '%r: %s' % (name, e))
758+                root = config.get('root', None)
759+                if root:
760+                    try:
761+                        self.configure_root(root, True)
762+                    except StandardError, e:
763+                        raise ValueError('Unable to configure root '
764+                                         'logger: %s' % e)
765+            else:
766+                disable_existing = config.pop('disable_existing_loggers', True)
767+
768+                logging._handlers.clear()
769+                del logging._handlerList[:]
770+
771+                # Do formatters first - they don't refer to anything else
772+                formatters = config.get('formatters', EMPTY_DICT)
773+                for name in formatters:
774+                    try:
775+                        formatters[name] = self.configure_formatter(
776+                                                            formatters[name])
777+                    except StandardError, e:
778+                        raise ValueError('Unable to configure '
779+                                         'formatter %r: %s' % (name, e))
780+                # Next, do filters - they don't refer to anything else, either
781+                filters = config.get('filters', EMPTY_DICT)
782+                for name in filters:
783+                    try:
784+                        filters[name] = self.configure_filter(filters[name])
785+                    except StandardError, e:
786+                        raise ValueError('Unable to configure '
787+                                         'filter %r: %s' % (name, e))
788+
789+                # Next, do handlers - they refer to formatters and filters
790+                # As handlers can refer to other handlers, sort the keys
791+                # to allow a deterministic order of configuration
792+                handlers = config.get('handlers', EMPTY_DICT)
793+                for name in sorted(handlers):
794+                    try:
795+                        handler = self.configure_handler(handlers[name])
796+                        handler.name = name
797+                        handlers[name] = handler
798+                    except StandardError, e:
799+                        raise ValueError('Unable to configure handler '
800+                                         '%r: %s' % (name, e))
801+                # Next, do loggers - they refer to handlers and filters
802+
803+                #we don't want to lose the existing loggers,
804+                #since other threads may have pointers to them.
805+                #existing is set to contain all existing loggers,
806+                #and as we go through the new configuration we
807+                #remove any which are configured. At the end,
808+                #what's left in existing is the set of loggers
809+                #which were in the previous configuration but
810+                #which are not in the new configuration.
811+                root = logging.root
812+                existing = root.manager.loggerDict.keys()
813+                #The list needs to be sorted so that we can
814+                #avoid disabling child loggers of explicitly
815+                #named loggers. With a sorted list it is easier
816+                #to find the child loggers.
817+                existing.sort()
818+                #We'll keep the list of existing loggers
819+                #which are children of named loggers here...
820+                child_loggers = []
821+                #now set up the new ones...
822+                loggers = config.get('loggers', EMPTY_DICT)
823+                for name in loggers:
824+                    if name in existing:
825+                        i = existing.index(name)
826+                        prefixed = name + "."
827+                        pflen = len(prefixed)
828+                        num_existing = len(existing)
829+                        i = i + 1 # look at the entry after name
830+                        while (i < num_existing) and\
831+                              (existing[i][:pflen] == prefixed):
832+                            child_loggers.append(existing[i])
833+                            i = i + 1
834+                        existing.remove(name)
835+                    try:
836+                        self.configure_logger(name, loggers[name])
837+                    except StandardError, e:
838+                        raise ValueError('Unable to configure logger '
839+                                         '%r: %s' % (name, e))
840+
841+                #Disable any old loggers. There's no point deleting
842+                #them as other threads may continue to hold references
843+                #and by disabling them, you stop them doing any logging.
844+                #However, don't disable children of named loggers, as that's
845+                #probably not what was intended by the user.
846+                for log in existing:
847+                    logger = root.manager.loggerDict[log]
848+                    if log in child_loggers:
849+                        logger.level = logging.NOTSET
850+                        logger.handlers = []
851+                        logger.propagate = True
852+                    elif disable_existing:
853+                        logger.disabled = True
854+
855+                # And finally, do the root logger
856+                root = config.get('root', None)
857+                if root:
858+                    try:
859+                        self.configure_root(root)
860+                    except StandardError, e:
861+                        raise ValueError('Unable to configure root '
862+                                         'logger: %s' % e)
863+        finally:
864+            logging._releaseLock()
865+
866+    def configure_formatter(self, config):
867+        """Configure a formatter from a dictionary."""
868+        if '()' in config:
869+            factory = config['()'] # for use in exception handler
870+            try:
871+                result = self.configure_custom(config)
872+            except TypeError, te:
873+                if "'format'" not in str(te):
874+                    raise
875+                #Name of parameter changed from fmt to format.
876+                #Retry with old name.
877+                #This is so that code can be used with older Python versions
878+                #(e.g. by Django)
879+                config['fmt'] = config.pop('format')
880+                config['()'] = factory
881+                result = self.configure_custom(config)
882+        else:
883+            fmt = config.get('format', None)
884+            dfmt = config.get('datefmt', None)
885+            result = logging.Formatter(fmt, dfmt)
886+        return result
887+
888+    def configure_filter(self, config):
889+        """Configure a filter from a dictionary."""
890+        if '()' in config:
891+            result = self.configure_custom(config)
892+        else:
893+            name = config.get('name', '')
894+            result = logging.Filter(name)
895+        return result
896+
897+    def add_filters(self, filterer, filters):
898+        """Add filters to a filterer from a list of names."""
899+        for f in filters:
900+            try:
901+                filterer.addFilter(self.config['filters'][f])
902+            except StandardError, e:
903+                raise ValueError('Unable to add filter %r: %s' % (f, e))
904+
905+    def configure_handler(self, config):
906+        """Configure a handler from a dictionary."""
907+        formatter = config.pop('formatter', None)
908+        if formatter:
909+            try:
910+                formatter = self.config['formatters'][formatter]
911+            except StandardError, e:
912+                raise ValueError('Unable to set formatter '
913+                                 '%r: %s' % (formatter, e))
914+        level = config.pop('level', None)
915+        filters = config.pop('filters', None)
916+        if '()' in config:
917+            c = config.pop('()')
918+            if not hasattr(c, '__call__') and hasattr(types, 'ClassType') and type(c) != types.ClassType:
919+                c = self.resolve(c)
920+            factory = c
921+        else:
922+            klass = self.resolve(config.pop('class'))
923+            #Special case for handler which refers to another handler
924+            if issubclass(klass, logging.handlers.MemoryHandler) and\
925+                'target' in config:
926+                try:
927+                    config['target'] = self.config['handlers'][config['target']]
928+                except StandardError, e:
929+                    raise ValueError('Unable to set target handler '
930+                                     '%r: %s' % (config['target'], e))
931+            elif issubclass(klass, logging.handlers.SMTPHandler) and\
932+                'mailhost' in config:
933+                config['mailhost'] = self.as_tuple(config['mailhost'])
934+            elif issubclass(klass, logging.handlers.SysLogHandler) and\
935+                'address' in config:
936+                config['address'] = self.as_tuple(config['address'])
937+            factory = klass
938+        kwargs = dict([(k, config[k]) for k in config if valid_ident(k)])
939+        try:
940+            result = factory(**kwargs)
941+        except TypeError, te:
942+            if "'stream'" not in str(te):
943+                raise
944+            #The argument name changed from strm to stream
945+            #Retry with old name.
946+            #This is so that code can be used with older Python versions
947+            #(e.g. by Django)
948+            kwargs['strm'] = kwargs.pop('stream')
949+            result = factory(**kwargs)
950+        if formatter:
951+            result.setFormatter(formatter)
952+        if level is not None:
953+            result.setLevel(_checkLevel(level))
954+        if filters:
955+            self.add_filters(result, filters)
956+        return result
957+
958+    def add_handlers(self, logger, handlers):
959+        """Add handlers to a logger from a list of names."""
960+        for h in handlers:
961+            try:
962+                logger.addHandler(self.config['handlers'][h])
963+            except StandardError, e:
964+                raise ValueError('Unable to add handler %r: %s' % (h, e))
965+
966+    def common_logger_config(self, logger, config, incremental=False):
967+        """
968+        Perform configuration which is common to root and non-root loggers.
969+        """
970+        level = config.get('level', None)
971+        if level is not None:
972+            logger.setLevel(_checkLevel(level))
973+        if not incremental:
974+            #Remove any existing handlers
975+            for h in logger.handlers[:]:
976+                logger.removeHandler(h)
977+            handlers = config.get('handlers', None)
978+            if handlers:
979+                self.add_handlers(logger, handlers)
980+            filters = config.get('filters', None)
981+            if filters:
982+                self.add_filters(logger, filters)
983+
984+    def configure_logger(self, name, config, incremental=False):
985+        """Configure a non-root logger from a dictionary."""
986+        logger = logging.getLogger(name)
987+        self.common_logger_config(logger, config, incremental)
988+        propagate = config.get('propagate', None)
989+        if propagate is not None:
990+            logger.propagate = propagate
991+
992+    def configure_root(self, config, incremental=False):
993+        """Configure a root logger from a dictionary."""
994+        root = logging.getLogger()
995+        self.common_logger_config(root, config, incremental)
996+
997+dictConfigClass = DictConfigurator
998+
999+def dictConfig(config):
1000+    """Configure logging using a dictionary."""
1001+    dictConfigClass(config).configure()
1002diff -r d861e2426ce4 django/utils/log.py
1003--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
1004+++ b/django/utils/log.py       Thu Sep 30 21:31:39 2010 +0800
1005@@ -0,0 +1,53 @@
1006+import logging
1007+from django.core import mail
1008+
1009+# Make sure a NullHandler is available
1010+# This was added in Python 2.7/3.2
1011+try:
1012+    from logging import NullHandler
1013+except ImportError:
1014+    class NullHandler(logging.Handler):
1015+        def emit(self, record):
1016+            pass
1017+
1018+# Make sure that dictConfig is available
1019+# This was added in Python 2.7/3.2
1020+try:
1021+    from logging.config import dictConfig
1022+except ImportError:
1023+    from django.utils.dictconfig import dictConfig
1024+
1025+# Ensure the creation of the Django logger
1026+logger = logging.getLogger('django')
1027+
1028+
1029+class AdminEmailHandler(logging.Handler):
1030+    """An exception log handler that emails log entries to site admins
1031+
1032+    If the request is passed as the first argument to the log record,
1033+    request data will be provided in the
1034+    """
1035+    def emit(self, record):
1036+        import traceback
1037+        from django.conf import settings
1038+
1039+        try:
1040+            request = record.request
1041+
1042+            subject = '%s (%s IP): %s' % (
1043+                record.levelname,
1044+                (request.META.get('REMOTE_ADDR') in settings.INTERNAL_IPS and 'internal' or 'EXTERNAL'),
1045+                request.path
1046+            )
1047+            request_repr = repr(request)
1048+        except:
1049+            subject = 'Error: Unknown URL'
1050+            request_repr = "Request repr() unavailable"
1051+
1052+        if record.exc_info:
1053+            stack_trace = '\n'.join(traceback.format_exception(*record.exc_info))
1054+        else:
1055+            stack_trace = 'No stack trace available'
1056+
1057+        message = "%s\n\n%s" % (stack_trace, request_repr)
1058+        mail.mail_admins(subject, message, fail_silently=True)
1059diff -r d861e2426ce4 django/views/decorators/http.py
1060--- a/django/views/decorators/http.py   Tue Sep 28 14:52:20 2010 +0000
1061+++ b/django/views/decorators/http.py   Thu Sep 30 21:31:39 2010 +0800
1062@@ -10,14 +10,17 @@
1063 from calendar import timegm
1064 from datetime import timedelta
1065 from email.Utils import formatdate
1066+import logging
1067 
1068 from django.utils.decorators import decorator_from_middleware, available_attrs
1069 from django.utils.http import parse_etags, quote_etag
1070 from django.middleware.http import ConditionalGetMiddleware
1071 from django.http import HttpResponseNotAllowed, HttpResponseNotModified, HttpResponse
1072 
1073+conditional_page = decorator_from_middleware(ConditionalGetMiddleware)
1074 
1075-conditional_page = decorator_from_middleware(ConditionalGetMiddleware)
1076+logger = logging.getLogger('django.request')
1077+
1078 
1079 def require_http_methods(request_method_list):
1080     """
1081@@ -33,6 +36,12 @@
1082     def decorator(func):
1083         def inner(request, *args, **kwargs):
1084             if request.method not in request_method_list:
1085+                logger.warning('Method Not Allowed (%s): %s' % (request.method, request.path),
1086+                    extra={
1087+                        'status_code': 405,
1088+                        'request': request
1089+                    }
1090+                )
1091                 return HttpResponseNotAllowed(request_method_list)
1092             return func(request, *args, **kwargs)
1093         return wraps(func, assigned=available_attrs(func))(inner)
1094@@ -111,9 +120,21 @@
1095                     if request.method in ("GET", "HEAD"):
1096                         response = HttpResponseNotModified()
1097                     else:
1098+                        logger.warning('Precondition Failed: %s' % request.path,
1099+                            extra={
1100+                                'status_code': 412,
1101+                                'request': request
1102+                            }
1103+                        )
1104                         response = HttpResponse(status=412)
1105                 elif if_match and ((not res_etag and "*" in etags) or
1106                         (res_etag and res_etag not in etags)):
1107+                    logger.warning('Precondition Failed: %s' % request.path,
1108+                        extra={
1109+                            'status_code': 412,
1110+                            'request': request
1111+                        }
1112+                    )
1113                     response = HttpResponse(status=412)
1114                 elif (not if_none_match and if_modified_since and
1115                         request.method == "GET" and
1116diff -r d861e2426ce4 django/views/generic/simple.py
1117--- a/django/views/generic/simple.py    Tue Sep 28 14:52:20 2010 +0000
1118+++ b/django/views/generic/simple.py    Thu Sep 30 21:31:39 2010 +0800
1119@@ -1,6 +1,11 @@
1120+import logging
1121+
1122 from django.template import loader, RequestContext
1123 from django.http import HttpResponse, HttpResponseRedirect, HttpResponsePermanentRedirect, HttpResponseGone
1124 
1125+logger = logging.getLogger('django.request')
1126+
1127+
1128 def direct_to_template(request, template, extra_context=None, mimetype=None, **kwargs):
1129     """
1130     Render a given template with any extra URL parameters in the context as
1131@@ -46,4 +51,9 @@
1132         klass = permanent and HttpResponsePermanentRedirect or HttpResponseRedirect
1133         return klass(url % kwargs)
1134     else:
1135+        logger.warning('Gone: %s' % request.path,
1136+                    extra={
1137+                        'status_code': 410,
1138+                        'request': request
1139+                    })
1140         return HttpResponseGone()
1141diff -r d861e2426ce4 docs/index.txt
1142--- a/docs/index.txt    Tue Sep 28 14:52:20 2010 +0000
1143+++ b/docs/index.txt    Thu Sep 30 21:31:39 2010 +0800
1144@@ -176,6 +176,7 @@
1145     * :doc:`Internationalization <topics/i18n/index>`
1146     * :doc:`Jython support <howto/jython>`
1147     * :doc:`"Local flavor" <ref/contrib/localflavor>`
1148+    * :doc:`Logging <topics/logging>`
1149     * :doc:`Messages <ref/contrib/messages>`
1150     * :doc:`Pagination <topics/pagination>`
1151     * :doc:`Redirects <ref/contrib/redirects>`
1152diff -r d861e2426ce4 docs/ref/settings.txt
1153--- a/docs/ref/settings.txt     Tue Sep 28 14:52:20 2010 +0000
1154+++ b/docs/ref/settings.txt     Thu Sep 30 21:31:39 2010 +0800
1155@@ -1008,6 +1008,36 @@
1156 
1157 .. setting:: LOGIN_REDIRECT_URL
1158 
1159+LOGGING
1160+-------
1161+
1162+Default: A logging configuration dictionary.
1163+
1164+A data structure containing configuration information. The contents of
1165+this data structure will be passed as the argument to the
1166+configuration method described in :setting:`LOGGING_CONFIG`.
1167+
1168+The default logging configuration passes HTTP 500 server errors to an
1169+email log handler; all other log messages are given to a NullHandler.
1170+
1171+.. versionadded:: 1.3
1172+
1173+LOGGING_CONFIG
1174+--------------
1175+
1176+Default: ``'django.utils.log.dictConfig'``
1177+
1178+A path to a callable that will be used to configure logging in the
1179+Django project. Points at a instance of Python's `dictConfig`_
1180+configuration method by default.
1181+
1182+If you set :setting:`LOGGING_CONFIG` to ``None``, the logging
1183+configuration process will be skipped.
1184+
1185+.. _dictConfig: http://docs.python.org/library/logging.html#logging.dictConfig
1186+
1187+.. versionadded:: 1.3
1188+
1189 LOGIN_REDIRECT_URL
1190 ------------------
1191 
1192diff -r d861e2426ce4 docs/releases/1.3.txt
1193--- a/docs/releases/1.3.txt     Tue Sep 28 14:52:20 2010 +0000
1194+++ b/docs/releases/1.3.txt     Thu Sep 30 21:31:39 2010 +0800
1195@@ -84,3 +84,13 @@
1196 What's new in Django 1.3
1197 ========================
1198 
1199+Logging
1200+~~~~~~~
1201+
1202+Django 1.3 adds framework-level support for Python's logging module.
1203+This means you can now esaily configure and control logging as part of
1204+your Django project. A number of logging handlers and logging calls
1205+have been added to Django's own code as well -- most notably, the
1206+error emails sent on a HTTP 500 server error are now handled as a
1207+logging activity. See :doc:`the documentation on Django's logging
1208+interface </topics/logging>` for more details.
1209diff -r d861e2426ce4 docs/topics/index.txt
1210--- a/docs/topics/index.txt     Tue Sep 28 14:52:20 2010 +0000
1211+++ b/docs/topics/index.txt     Thu Sep 30 21:31:39 2010 +0800
1212@@ -20,6 +20,7 @@
1213    conditional-view-processing
1214    email
1215    i18n/index
1216+   logging
1217    pagination
1218    serialization
1219    settings
1220diff -r d861e2426ce4 docs/topics/logging.txt
1221--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
1222+++ b/docs/topics/logging.txt   Thu Sep 30 21:31:39 2010 +0800
1223@@ -0,0 +1,435 @@
1224+=======
1225+Logging
1226+=======
1227+
1228+.. versionadded:: 1.3
1229+
1230+.. module:: django.utils.log
1231+   :synopsis: Logging tools for Django applications
1232+
1233+A quick logging primer
1234+======================
1235+
1236+Django uses Python's builtin logging module to perform system logging.
1237+The usage of the logging module is discussed in detail in `Python's
1238+own documentation`_. However, if you've never used Python's logging
1239+framework (or even if you have), here's a quick primer.
1240+
1241+.. _Python's own documentation: http://docs.python.org/library/logging.html
1242+
1243+The cast of players
1244+-------------------
1245+
1246+A Python logging configuration consists of four parts:
1247+
1248+    * :ref:`topic-logging-parts-loggers`
1249+    * :ref:`topic-logging-parts-handlers`
1250+    * :ref:`topic-logging-parts-filters`
1251+    * :ref:`topic-logging-parts-formatters`
1252+
1253+.. _topic-logging-parts-loggers:
1254+
1255+Loggers
1256+~~~~~~~
1257+
1258+A logger is the entry point into the logging system. Each logger is
1259+a named bucket to which messages can be written for processing.
1260+
1261+A logger is configured to have *log level*. This log level describes
1262+the severity of the messages that the logger will handle. Python
1263+defines the following log levels:
1264+
1265+    * ``DEBUG``: Low level system information for debugging purposes
1266+
1267+    * ``INFO``: General system information
1268+
1269+    * ``WARNING``: Information describing a minor problem that has
1270+      occurred.
1271+
1272+    * ``ERROR``: Information describing a major problem that has
1273+      occurred.
1274+
1275+    * ``CRITICAL``: Information describing a critical problem that has
1276+      occurred.
1277+
1278+Each message that is written to the logger is a *Log Record*. Each log
1279+record also has a *log level* indicating the severity of that specific
1280+message. A log record can also contain useful metadata that describes
1281+the event that is being logged. This can include details such as a
1282+stack trace or an error code.
1283+
1284+When a message is given to the logger, the log level of the message is
1285+compare to the log level of the logger. If the log level of the
1286+message meets or exceeds the log level of the logger itself, the
1287+message will undergo further processing. If it doesn't, the message
1288+will be ignored.
1289+
1290+Once a logger has determined that a message needs to be processed,
1291+it is passed to a *Handler*.
1292+
1293+.. _topic-logging-parts-handlers:
1294+
1295+Handlers
1296+~~~~~~~~
1297+
1298+The handler is the engine that determines what happens to each message
1299+in a logger. It describes a particular logging behavior, such as
1300+writing a message to the screen, to a file, or to a network socket.
1301+
1302+Like loggers, handlers also have a log level. If the log level of a
1303+log record doesn't meet or exceed the level of the handler, the
1304+handler will ignore the message.
1305+
1306+A logger can have multiple handlers, and each handler can have a
1307+different log level. In this way, it is possible to provide different
1308+forms of notification depending on the importance of a message. For
1309+example, you could install one handler that forwards ``ERROR`` and
1310+``CRITICIAL`` messages to a paging service, while a second handler
1311+logs all messages (including ``ERROR`` and ``CRITICAL`` messages) to a
1312+file for later analysis.
1313+
1314+.. _topic-logging-parts-filters:
1315+
1316+Filters
1317+~~~~~~~
1318+
1319+A filter is used to provide additional control over which log records
1320+are passed from logger to handler.
1321+
1322+By default, any log message that meets log level requirements will be
1323+handled. However, by installing a filter, you can place additional
1324+criteria on the logging process. For example, you could install a
1325+filter that only allows ``ERROR`` messages from a particular source to
1326+be emitted.
1327+
1328+Filters can also be used to modify the logging record prior to being
1329+emitted. For example, you could write a filter that downgrades
1330+``ERROR`` log records to ``WARNING`` records if a particular set of
1331+criteria are met.
1332+
1333+Filters can be installed on loggers or on handlers; multiple filters
1334+can be used in a chain to perform multiple filtering actions.
1335+
1336+.. _topic-logging-parts-formatters:
1337+
1338+Formatters
1339+~~~~~~~~~~
1340+
1341+Ultimately, a log record needs to be rendered as text. Formatters
1342+describe the exact format of that text. A formatter usually consists
1343+of a Python formatting string; however, you can also write custom
1344+formatters to implement specific formatting behavior.
1345+
1346+Using logging
1347+=============
1348+
1349+Once you have configured your loggers, handlers, filters and
1350+formatters, you need to place logging calls into your code. Using the
1351+logging framework is very simple. Here's an example::
1352+
1353+    # import the logging library
1354+    import logging
1355+
1356+    # Get an instance of a logger
1357+    logger = logging.getLogger(__name__)
1358+
1359+    def my_view(request, arg1, arg):
1360+        ...
1361+        if bad_mojo:
1362+            # Log an error message
1363+            logger.error('Something went wrong!')
1364+
1365+And that's it! Every time the ``bad_mojo`` condition is activated, an
1366+error log record will be written.
1367+
1368+Naming loggers
1369+~~~~~~~~~~~~~~
1370+
1371+The call to :meth:`logging.getLogger()` obtains (creating, if
1372+necessary) an instance of a logger. The logger instance is identified
1373+by a name. This name is used to identify the logger for configuration
1374+purposes.
1375+
1376+By convention, the logger name is usually ``__name__``, the name of
1377+the python module that contains the logger. This allows you to filter
1378+and handle logging calls on a per-module basis. However, if you have
1379+some other way of organizing your logging messages, you can provide
1380+any dot-separated name to identify your logger::
1381+
1382+    # Get an instance of a specfic named logger
1383+    logger = logging.getLogger('project.interesting.stuff')
1384+
1385+The dotted paths of logger names define a hierarchy. The
1386+``project.interesting`` logger is considered to be a parent of the
1387+``project.interesting.stuff`` logger; the ``project`` logger
1388+is a parent of the ``project.interesting`` logger.
1389+
1390+Why is the hierarchy important? Well, because loggers can be set to
1391+*propagate* their logging calls to their parents. In this way, you can
1392+define a single set of handlers at the root of a logger tree, and
1393+capture all logging calls in the subtree of loggers. A logging handler
1394+defined in the ``project`` namespace will catch all logging messages
1395+issued on the ``project.interesting`` and
1396+``project.interesting.stuff`` loggers.
1397+
1398+This propagation can be controlled on a per-logger basis. If
1399+you don't want a particular logger to propagate to it's parents, you
1400+can turn off this behavior.
1401+
1402+Making logging calls
1403+~~~~~~~~~~~~~~~~~~~~
1404+
1405+The logger instance contains an entry method for each of the default
1406+log levels:
1407+
1408+    * ``logger.critical()``
1409+    * ``logger.error()``
1410+    * ``logger.warning()``
1411+    * ``logger.info()``
1412+    * ``logger.debug()``
1413+
1414+There are two other logging calls available:
1415+
1416+    * ``logger.log()``: manually a logging message with a specific
1417+      log level.
1418+
1419+    * ``logger.exception()``: create a ``ERRORR`` level logging
1420+      message wrapping the current exception stack frame.
1421+
1422+Configuring logging
1423+===================
1424+
1425+Of course, it isn't enough to just put logging calls into your code.
1426+You also need to configure the loggers, handlers, filters and
1427+formatters to ensure that logging output is output in a useful way.
1428+
1429+Python's logging library provides several techniques to configure
1430+logging, ranging from a programatic interface to configuration files.
1431+By default, Django uses the `dictConfig format`_.
1432+
1433+.. note::
1434+    ``logging.dictConfig`` is a builtin library in Python 2.7. In
1435+    order to make this library available for users of earlier Python
1436+    versions, Django includes a copy as part of ``django.utils.log``.
1437+    If you have Python 2.7, the system native library will be used; if
1438+    you have Python 2.6 or earlier, Django's copy will be used.
1439+
1440+In order to configure logging, you use :setting:`LOGGING` to define a
1441+dictionary of logging settings. These settings describes the loggers,
1442+handlers, filters and formatters that you want in your logging setup,
1443+and the log levels and other properties that you want those components
1444+to have.
1445+
1446+Logging is configured immediately after settings have been loaded.
1447+Since the loading of settings is one of the first things that Django
1448+does, you can be certain that loggers are always ready for use in your
1449+project code.
1450+
1451+.. _dictConfig format: http://docs.python.org/library/logging.html#configuration-dictionary-schema
1452+
1453+.. _a third-party library: http://bitbucket.org/vinay.sajip/dictconfig
1454+
1455+An example
1456+----------
1457+
1458+The full documentation for `dictConfig format`_ is the best source of
1459+information about logging configuration dictionaries. However, to give
1460+you a taste of what is possible, here is an example of a fairly
1461+complex logging setup, configured using :meth:`logging.dictConfig`::
1462+
1463+    LOGGING = {
1464+        'version': 1,
1465+        'disable_existing_loggers': False,
1466+        'formatters': {
1467+            'explicit': {
1468+                'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
1469+            },
1470+            'simple': {
1471+                'format': '%(levelname)s %(message)s'
1472+            },
1473+        },
1474+        'filters': {
1475+            'special': {
1476+                '()': 'project.logging.SpecialFilter',
1477+                'foo': 'bar',
1478+            }
1479+        },
1480+        'handlers': {
1481+            'null': {
1482+                'level':'DEBUG',
1483+                'class':'django.utils.log.NullHandler',
1484+            },
1485+            'console':{
1486+                'level':'DEBUG',
1487+                'class':'logging.StreamHandler',
1488+                'formatter': 'simple'
1489+            },
1490+            'mail_admins': {
1491+                'level': 'ERROR',
1492+                'class': 'django.utils.log.AdminEmailHandler'
1493+                'filters': ['special']
1494+            }
1495+        },
1496+        'loggers': {
1497+            'django': {
1498+                'handlers':['null'],
1499+                'propagate': True,
1500+                'level':'INFO',
1501+            },
1502+            'django.request': {
1503+                'handlers': ['mail_admins'],
1504+                'level': 'ERROR',
1505+                'propagate': False,
1506+            },
1507+            'myproject.custom': {
1508+                'handlers: ['console', 'mail_admins'],
1509+                'level': 'INFO',
1510+                'filters': ['special']
1511+            }
1512+        }
1513+    }
1514+
1515+This logging configuration does the following things:
1516+
1517+    * Identifies the configuration as being in 'dictConfig version 1'
1518+      format. At present, this is the only dictConfig format version.
1519+
1520+    * Disables all existing logging configurations.
1521+
1522+    * Defines two formatters:
1523+
1524+        * ``simple``, that just outputs the log level name (e.g.,
1525+          ``DEBUG``) and the log message.
1526+
1527+          The `format` string is a normal Python formatting string
1528+          describing the details that are to be output on each logging
1529+          line. The full list of detail that can be output can be
1530+          found in the `formatter documentation`_.
1531+
1532+        * ``verbose``, that outputs the log level name, the log
1533+          message, plus the time, process, thread and module that
1534+          generate the log message.
1535+
1536+
1537+    * Defines one filter -- :class:`project.logging.SpecialFilter`,
1538+      using the alias ``special``. If this filter required additional
1539+      arguments at time of construction, they can be provided as
1540+      additional keys in the filter configuration dictionary. In this
1541+      case, the argument ``foo`` will be given a value of ``bar`` when
1542+      instantiating the :class:`SpecialFilter`.
1543+
1544+    * Defines three handlers:
1545+
1546+        * ``null``, a NullHandler, which will pass any `DEBUG` or
1547+          higher message to ``/dev/null``.
1548+
1549+        * ``console``, a StreamHandler, which will print any `DEBUG`
1550+          message to stdout. This handler uses the `simple` output
1551+          format.
1552+
1553+        * ``mail_admins``, an AdminEmailHandler, which will email any
1554+          `ERROR` level message to the site admins. This handler uses
1555+          the ``special`` filter.
1556+
1557+    * Configures three loggers:
1558+
1559+        * ``django``, which passes all messages at ``INFO`` or higher
1560+          to the ``null`` handler.
1561+
1562+        * ``django.request``, which passes all ``ERROR`` messages to
1563+          the ``mail_admins`` handler. In addition, this logger is
1564+          marked to *not* propagate messages. This means that log
1565+          messages written to ``django.request`` will not be handled
1566+          by the ``django`` logger.
1567+
1568+        * ``myproject.custom``, which passes all messages at ``INFO``
1569+          or higher that also pass the ``special`` filter to two
1570+          handlers -- the ``console``, and ``mail_admins``. This
1571+          means that all ``INFO`` level messages (or higher) will be
1572+          printed to the console; ``ERROR`` and ``CRITICIAL``
1573+          messages will also be output via e-mail.
1574+
1575+.. _formatter documentation: http://docs.python.org/library/logging.html#formatter-objects
1576+
1577+Custom logging configuration
1578+----------------------------
1579+
1580+If you don't want to use Python's dictConfig format to configure your
1581+logger, you can specify your own configuration scheme.
1582+
1583+The :setting:`LOGGING_CONFIG` setting defines the callable that will
1584+be used to configure Django's loggers. By default, it points at
1585+Python's :meth:`logging.dictConfig()` method. However, if you want to
1586+use a different configuration process, you can use any other callable
1587+that takes a single argument. The contents of :setting:`LOGGING` will
1588+be provided as the value of that argument when logging is configured.
1589+
1590+Disabling logging configuration
1591+-------------------------------
1592+
1593+If you don't want to configure logging at all (or you want to manually
1594+configure logging using your own approach), you can set
1595+:setting:`LOGGING_CONFIG` to ``None``. This will disable the
1596+configuration process.
1597+
1598+Django's logging extensions
1599+===========================
1600+
1601+Django provides a number of utilities to handle the unique
1602+requirements of logging in webserver environment.
1603+
1604+Loggers
1605+-------
1606+
1607+Django provides three built-in loggers.
1608+
1609+``django``
1610+~~~~~~~~~~
1611+
1612+``django`` is the catch-all logger. No messages are posted directly to
1613+this logger.
1614+
1615+``django.requests``
1616+~~~~~~~~~~~~~~~~~~~
1617+
1618+Log messages related to the handling of requests. 5XX responses are
1619+raised as ``ERROR`` messages; 4XX responses are raised as ``WARNING``
1620+messages.
1621+
1622+Messages to this logger have the following extra context:
1623+
1624+    * ``status_code``: The HTTP response code associated with the
1625+      request.
1626+
1627+    * ``request``: The request object that generated the logging
1628+      message.
1629+
1630+``django.db.backends``
1631+~~~~~~~~~~~~~~~~~~~~~~
1632+
1633+Messages relating to the interaction of code with the database.
1634+For example, every SQL statement executed by a request is logged
1635+at the ``DEBUG`` level to this logger.
1636+
1637+Messages to this logger have the following extra context:
1638+
1639+    * ``duration``: The time taken to execute the SQL statement.
1640+    * ``sql``: The SQL statement that was executed.
1641+    * ``params``: The parameters that were used in the SQL call.
1642+
1643+Handlers
1644+--------
1645+
1646+Django provides one log handler in addition to those provided by the
1647+Python logging module.
1648+
1649+.. class:: AdminEmailHandler()
1650+
1651+    This handler sends an email to the site admins for each log
1652+    message it receives.
1653+
1654+    If the log record contains a 'request' attribute, the full details
1655+    of the request will be included in the email.
1656+
1657+    If the log record contains stack trace information, that stack
1658+    trace will be included in the email.