/docs/howto/error-reporting.txt

 1Error reporting via e-mail
 2==========================
 3
 4When you're running a public site you should always turn off the
 5:setting:`DEBUG` setting. That will make your server run much faster, and will
 6also prevent malicious users from seeing details of your application that can be
 7revealed by the error pages.
 8
 9However, running with :setting:`DEBUG` set to ``False`` means you'll never see
10errors generated by your site -- everyone will just see your public error pages.
11You need to keep track of errors that occur in deployed sites, so Django can be
12configured to e-mail you details of those errors.
13
14Server errors
15-------------
16
17When :setting:`DEBUG` is ``False``, Django will e-mail the users listed in the
18:setting:`ADMINS` setting whenever your code raises an unhandled exception and
19results in an internal server error (HTTP status code 500). This gives the
20administrators immediate notification of any errors. The :setting:`ADMINS` will
21get a description of the error, a complete Python traceback, and details about
22the HTTP request that caused the error.
23
24.. note::
25
26   In order to send e-mail, Django requires a few settings telling it
27   how to connect to your mail server. At the very least, you'll need
28   to specify :setting:`EMAIL_HOST` and possibly
29   :setting:`EMAIL_HOST_USER` and :setting:`EMAIL_HOST_PASSWORD`,
30   though other settings may be also required depending on your mail
31   server's configuration. Consult :doc:`the Django settings
32   documentation </ref/settings>` for a full list of email-related
33   settings.
34
35By default, Django will send e-mail from root@localhost. However, some mail
36providers reject all e-mail from this address. To use a different sender
37address, modify the :setting:`SERVER_EMAIL` setting.
38
39To disable this behavior, just remove all entries from the :setting:`ADMINS`
40setting.
41
42.. seealso::
43
44   .. versionadded:: 1.3
45
46   Server error e-mails are sent using the logging framework, so you can
47   customize this behaviour by :doc:`customizing your logging configuration
48   </topics/logging>`.
49
50404 errors
51----------
52
53Django can also be configured to e-mail errors about broken links (404 "page
54not found" errors). Django sends e-mails about 404 errors when:
55
56    * :setting:`DEBUG` is ``False``
57
58    * :setting:`SEND_BROKEN_LINK_EMAILS` is ``True``
59
60    * Your :setting:`MIDDLEWARE_CLASSES` setting includes ``CommonMiddleware``
61      (which it does by default).
62
63If those conditions are met, Django will e-mail the users listed in the
64:setting:`MANAGERS` setting whenever your code raises a 404 and the request has
65a referer. (It doesn't bother to e-mail for 404s that don't have a referer --
66those are usually just people typing in broken URLs or broken Web 'bots).
67
68You can tell Django to stop reporting particular 404s by tweaking the
69:setting:`IGNORABLE_404_ENDS` and :setting:`IGNORABLE_404_STARTS` settings. Both
70should be a tuple of strings. For example::
71
72    IGNORABLE_404_ENDS = ('.php', '.cgi')
73    IGNORABLE_404_STARTS = ('/phpmyadmin/',)
74
75In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not* be
76reported. Neither will any URL starting with ``/phpmyadmin/``.
77
78The best way to disable this behavior is to set
79:setting:`SEND_BROKEN_LINK_EMAILS` to ``False``.
80
81.. seealso::
82
83    You can also set up custom error reporting by writing a custom piece of
84    :ref:`exception middleware <exception-middleware>`. If you do write custom
85    error handling, it's a good idea to emulate Django's built-in error handling
86    and only report/log errors if :setting:`DEBUG` is ``False``.
87
88.. seealso::
89
90   .. versionadded:: 1.3
91
92   404 errors are logged using the logging framework. By default, these log
93   records are ignored, but you can use them for error reporting by writing a
94   handler and :doc:`configuring logging </topics/logging>` appropriately.
95