| 1 |
============================= |
| 2 |
How to manage error reporting |
| 3 |
============================= |
| 4 |
|
| 5 |
When you're running a public site you should always turn off the |
| 6 |
:setting:`DEBUG` setting. That will make your server run much faster, and will |
| 7 |
also prevent malicious users from seeing details of your application that can be |
| 8 |
revealed by the error pages. |
| 9 |
|
| 10 |
However, running with :setting:`DEBUG` set to ``False`` means you'll never see |
| 11 |
errors generated by your site -- everyone will instead see your public error |
| 12 |
pages. You need to keep track of errors that occur in deployed sites, so Django |
| 13 |
can be configured to create reports with details about those errors. |
| 14 |
|
| 15 |
Email reports |
| 16 |
============= |
| 17 |
|
| 18 |
Server errors |
| 19 |
------------- |
| 20 |
|
| 21 |
When :setting:`DEBUG` is ``False``, Django will email the users listed in the |
| 22 |
:setting:`ADMINS` setting whenever your code raises an unhandled exception and |
| 23 |
results in an internal server error (strictly speaking, for any response with |
| 24 |
an HTTP status code of 500 or greater). This gives the administrators immediate |
| 25 |
notification of any errors. The :setting:`ADMINS` will get a description of the |
| 26 |
error, a complete Python traceback, and details about the HTTP request that |
| 27 |
caused the error. |
| 28 |
|
| 29 |
.. note:: |
| 30 |
|
| 31 |
In order to send email, Django requires a few settings telling it |
| 32 |
how to connect to your mail server. At the very least, you'll need |
| 33 |
to specify :setting:`EMAIL_HOST` and possibly |
| 34 |
:setting:`EMAIL_HOST_USER` and :setting:`EMAIL_HOST_PASSWORD`, |
| 35 |
though other settings may be also required depending on your mail |
| 36 |
server's configuration. Consult :doc:`the Django settings |
| 37 |
documentation </ref/settings>` for a full list of email-related |
| 38 |
settings. |
| 39 |
|
| 40 |
By default, Django will send email from root@localhost. However, some mail |
| 41 |
providers reject all email from this address. To use a different sender |
| 42 |
address, modify the :setting:`SERVER_EMAIL` setting. |
| 43 |
|
| 44 |
To activate this behavior, put the email addresses of the recipients in the |
| 45 |
:setting:`ADMINS` setting. |
| 46 |
|
| 47 |
.. seealso:: |
| 48 |
|
| 49 |
Server error emails are sent using the logging framework, so you can |
| 50 |
customize this behavior by :doc:`customizing your logging configuration |
| 51 |
</topics/logging>`. |
| 52 |
|
| 53 |
404 errors |
| 54 |
---------- |
| 55 |
|
| 56 |
Django can also be configured to email errors about broken links (404 "page |
| 57 |
not found" errors). Django sends emails about 404 errors when: |
| 58 |
|
| 59 |
* :setting:`DEBUG` is ``False``; |
| 60 |
|
| 61 |
* Your :setting:`MIDDLEWARE` setting includes |
| 62 |
:class:`django.middleware.common.BrokenLinkEmailsMiddleware`. |
| 63 |
|
| 64 |
If those conditions are met, Django will email the users listed in the |
| 65 |
:setting:`MANAGERS` setting whenever your code raises a 404 and the request has |
| 66 |
a referer. It doesn't bother to email for 404s that don't have a referer -- |
| 67 |
those are usually people typing in broken URLs or broken web bots. It also |
| 68 |
ignores 404s when the referer is equal to the requested URL, since this |
| 69 |
behavior is from broken web bots too. |
| 70 |
|
| 71 |
.. note:: |
| 72 |
|
| 73 |
:class:`~django.middleware.common.BrokenLinkEmailsMiddleware` must appear |
| 74 |
before other middleware that intercepts 404 errors, such as |
| 75 |
:class:`~django.middleware.locale.LocaleMiddleware` or |
| 76 |
:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`. |
| 77 |
Put it toward the top of your :setting:`MIDDLEWARE` setting. |
| 78 |
|
| 79 |
You can tell Django to stop reporting particular 404s by tweaking the |
| 80 |
:setting:`IGNORABLE_404_URLS` setting. It should be a list of compiled |
| 81 |
regular expression objects. For example:: |
| 82 |
|
| 83 |
import re |
| 84 |
|
| 85 |
IGNORABLE_404_URLS = [ |
| 86 |
re.compile(r"\.(php|cgi)$"), |
| 87 |
re.compile(r"^/phpmyadmin/"), |
| 88 |
] |
| 89 |
|
| 90 |
In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not* be |
| 91 |
reported. Neither will any URL starting with ``/phpmyadmin/``. |
| 92 |
|
| 93 |
The following example shows how to exclude some conventional URLs that browsers and |
| 94 |
crawlers often request:: |
| 95 |
|
| 96 |
import re |
| 97 |
|
| 98 |
IGNORABLE_404_URLS = [ |
| 99 |
re.compile(r"^/apple-touch-icon.*\.png$"), |
| 100 |
re.compile(r"^/favicon\.ico$"), |
| 101 |
re.compile(r"^/robots\.txt$"), |
| 102 |
] |
| 103 |
|
| 104 |
(Note that these are regular expressions, so we put a backslash in front of |
| 105 |
periods to escape them.) |
| 106 |
|
| 107 |
If you'd like to customize the behavior of |
| 108 |
:class:`django.middleware.common.BrokenLinkEmailsMiddleware` further (for |
| 109 |
example to ignore requests coming from web crawlers), you should subclass it |
| 110 |
and override its methods. |
| 111 |
|
| 112 |
.. seealso:: |
| 113 |
|
| 114 |
404 errors are logged using the logging framework. By default, these log |
| 115 |
records are ignored, but you can use them for error reporting by writing a |
| 116 |
handler and :doc:`configuring logging </topics/logging>` appropriately. |
| 117 |
|
| 118 |
.. _filtering-error-reports: |
| 119 |
|
| 120 |
Filtering error reports |
| 121 |
======================= |
| 122 |
|
| 123 |
.. warning:: |
| 124 |
|
| 125 |
Filtering sensitive data is a hard problem, and it's nearly impossible to |
| 126 |
guarantee that sensitive data won't leak into an error report. Therefore, |
| 127 |
error reports should only be available to trusted team members and you |
| 128 |
should avoid transmitting error reports unencrypted over the internet |
| 129 |
(such as through email). |
| 130 |
|
| 131 |
Filtering sensitive information |
| 132 |
------------------------------- |
| 133 |
|
| 134 |
.. currentmodule:: django.views.decorators.debug |
| 135 |
|
| 136 |
Error reports are really helpful for debugging errors, so it is generally |
| 137 |
useful to record as much relevant information about those errors as possible. |
| 138 |
For example, by default Django records the `full traceback`_ for the |
| 139 |
exception raised, each `traceback frame`_’s local variables, and the |
| 140 |
:class:`~django.http.HttpRequest`’s :ref:`attributes<httprequest-attributes>`. |
| 141 |
|
| 142 |
However, sometimes certain types of information may be too sensitive and thus |
| 143 |
may not be appropriate to be kept track of, for example a user's password or |
| 144 |
credit card number. So in addition to filtering out settings that appear to be |
| 145 |
sensitive as described in the :setting:`DEBUG` documentation, Django offers a |
| 146 |
set of function decorators to help you control which information should be |
| 147 |
filtered out of error reports in a production environment (that is, where |
| 148 |
:setting:`DEBUG` is set to ``False``): :func:`sensitive_variables` and |
| 149 |
:func:`sensitive_post_parameters`. |
| 150 |
|
| 151 |
.. _`full traceback`: https://en.wikipedia.org/wiki/Stack_trace |
| 152 |
.. _`traceback frame`: https://en.wikipedia.org/wiki/Stack_frame |
| 153 |
|
| 154 |
.. function:: sensitive_variables(*variables) |
| 155 |
|
| 156 |
If a function (either a view or any regular callback) in your code uses |
| 157 |
local variables susceptible to contain sensitive information, you may |
| 158 |
prevent the values of those variables from being included in error reports |
| 159 |
using the ``sensitive_variables`` decorator:: |
| 160 |
|
| 161 |
from django.views.decorators.debug import sensitive_variables |
| 162 |
|
| 163 |
|
| 164 |
@sensitive_variables("user", "pw", "cc") |
| 165 |
def process_info(user): |
| 166 |
pw = user.pass_word |
| 167 |
cc = user.credit_card_number |
| 168 |
name = user.name |
| 169 |
... |
| 170 |
|
| 171 |
In the above example, the values for the ``user``, ``pw`` and ``cc`` |
| 172 |
variables will be hidden and replaced with stars (``**********``) |
| 173 |
in the error reports, whereas the value of the ``name`` variable will be |
| 174 |
disclosed. |
| 175 |
|
| 176 |
To systematically hide all local variables of a function from error logs, |
| 177 |
do not provide any argument to the ``sensitive_variables`` decorator:: |
| 178 |
|
| 179 |
@sensitive_variables() |
| 180 |
def my_function(): ... |
| 181 |
|
| 182 |
.. admonition:: When using multiple decorators |
| 183 |
|
| 184 |
If the variable you want to hide is also a function argument (e.g. |
| 185 |
'``user``’ in the following example), and if the decorated function has |
| 186 |
multiple decorators, then make sure to place ``@sensitive_variables`` |
| 187 |
at the top of the decorator chain. This way it will also hide the |
| 188 |
function argument as it gets passed through the other decorators:: |
| 189 |
|
| 190 |
@sensitive_variables("user", "pw", "cc") |
| 191 |
@some_decorator |
| 192 |
@another_decorator |
| 193 |
def process_info(user): ... |
| 194 |
|
| 195 |
.. function:: sensitive_post_parameters(*parameters) |
| 196 |
|
| 197 |
If one of your views receives an :class:`~django.http.HttpRequest` object |
| 198 |
with :attr:`POST parameters<django.http.HttpRequest.POST>` susceptible to |
| 199 |
contain sensitive information, you may prevent the values of those |
| 200 |
parameters from being included in the error reports using the |
| 201 |
``sensitive_post_parameters`` decorator:: |
| 202 |
|
| 203 |
from django.views.decorators.debug import sensitive_post_parameters |
| 204 |
|
| 205 |
|
| 206 |
@sensitive_post_parameters("pass_word", "credit_card_number") |
| 207 |
def record_user_profile(request): |
| 208 |
UserProfile.create( |
| 209 |
user=request.user, |
| 210 |
password=request.POST["pass_word"], |
| 211 |
credit_card=request.POST["credit_card_number"], |
| 212 |
name=request.POST["name"], |
| 213 |
) |
| 214 |
... |
| 215 |
|
| 216 |
In the above example, the values for the ``pass_word`` and |
| 217 |
``credit_card_number`` POST parameters will be hidden and replaced with |
| 218 |
stars (``**********``) in the request's representation inside the |
| 219 |
error reports, whereas the value of the ``name`` parameter will be |
| 220 |
disclosed. |
| 221 |
|
| 222 |
To systematically hide all POST parameters of a request in error reports, |
| 223 |
do not provide any argument to the ``sensitive_post_parameters`` decorator:: |
| 224 |
|
| 225 |
@sensitive_post_parameters() |
| 226 |
def my_view(request): ... |
| 227 |
|
| 228 |
All POST parameters are systematically filtered out of error reports for |
| 229 |
certain :mod:`django.contrib.auth.views` views (``login``, |
| 230 |
``password_reset_confirm``, ``password_change``, and ``add_view`` and |
| 231 |
``user_change_password`` in the ``auth`` admin) to prevent the leaking of |
| 232 |
sensitive information such as user passwords. |
| 233 |
|
| 234 |
.. _custom-error-reports: |
| 235 |
|
| 236 |
Custom error reports |
| 237 |
-------------------- |
| 238 |
|
| 239 |
All :func:`sensitive_variables` and :func:`sensitive_post_parameters` do is, |
| 240 |
respectively, annotate the decorated function with the names of sensitive |
| 241 |
variables and annotate the ``HttpRequest`` object with the names of sensitive |
| 242 |
POST parameters, so that this sensitive information can later be filtered out |
| 243 |
of reports when an error occurs. The actual filtering is done by Django's |
| 244 |
default error reporter filter: |
| 245 |
:class:`django.views.debug.SafeExceptionReporterFilter`. This filter uses the |
| 246 |
decorators' annotations to replace the corresponding values with stars |
| 247 |
(``**********``) when the error reports are produced. If you wish to |
| 248 |
override or customize this default behavior for your entire site, you need to |
| 249 |
define your own filter class and tell Django to use it via the |
| 250 |
:setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` setting:: |
| 251 |
|
| 252 |
DEFAULT_EXCEPTION_REPORTER_FILTER = "path.to.your.CustomExceptionReporterFilter" |
| 253 |
|
| 254 |
You may also control in a more granular way which filter to use within any |
| 255 |
given view by setting the ``HttpRequest``’s ``exception_reporter_filter`` |
| 256 |
attribute:: |
| 257 |
|
| 258 |
def my_view(request): |
| 259 |
if request.user.is_authenticated: |
| 260 |
request.exception_reporter_filter = CustomExceptionReporterFilter() |
| 261 |
... |
| 262 |
|
| 263 |
.. currentmodule:: django.views.debug |
| 264 |
|
| 265 |
Your custom filter class needs to inherit from |
| 266 |
:class:`django.views.debug.SafeExceptionReporterFilter` and may override the |
| 267 |
following attributes and methods: |
| 268 |
|
| 269 |
.. class:: SafeExceptionReporterFilter |
| 270 |
|
| 271 |
.. attribute:: cleansed_substitute |
| 272 |
|
| 273 |
The string value to replace sensitive value with. By default it |
| 274 |
replaces the values of sensitive variables with stars |
| 275 |
(``**********``). |
| 276 |
|
| 277 |
.. attribute:: hidden_settings |
| 278 |
|
| 279 |
A compiled regular expression object used to match settings and |
| 280 |
``request.META`` values considered as sensitive. By default equivalent |
| 281 |
to:: |
| 282 |
|
| 283 |
import re |
| 284 |
|
| 285 |
re.compile(r"API|AUTH|TOKEN|KEY|SECRET|PASS|SIGNATURE|HTTP_COOKIE", flags=re.IGNORECASE) |
| 286 |
|
| 287 |
.. versionchanged:: 5.2 |
| 288 |
|
| 289 |
The term ``AUTH`` was added. |
| 290 |
|
| 291 |
.. method:: is_active(request) |
| 292 |
|
| 293 |
Returns ``True`` to activate the filtering in |
| 294 |
:meth:`get_post_parameters` and :meth:`get_traceback_frame_variables`. |
| 295 |
By default the filter is active if :setting:`DEBUG` is ``False``. Note |
| 296 |
that sensitive ``request.META`` values are always filtered along with |
| 297 |
sensitive setting values, as described in the :setting:`DEBUG` |
| 298 |
documentation. |
| 299 |
|
| 300 |
.. method:: get_post_parameters(request) |
| 301 |
|
| 302 |
Returns the filtered dictionary of POST parameters. Sensitive values |
| 303 |
are replaced with :attr:`cleansed_substitute`. |
| 304 |
|
| 305 |
.. method:: get_traceback_frame_variables(request, tb_frame) |
| 306 |
|
| 307 |
Returns the filtered dictionary of local variables for the given |
| 308 |
traceback frame. Sensitive values are replaced with |
| 309 |
:attr:`cleansed_substitute`. |
| 310 |
|
| 311 |
If you need to customize error reports beyond filtering you may specify a |
| 312 |
custom error reporter class by defining the |
| 313 |
:setting:`DEFAULT_EXCEPTION_REPORTER` setting:: |
| 314 |
|
| 315 |
DEFAULT_EXCEPTION_REPORTER = "path.to.your.CustomExceptionReporter" |
| 316 |
|
| 317 |
The exception reporter is responsible for compiling the exception report data, |
| 318 |
and formatting it as text or HTML appropriately. (The exception reporter uses |
| 319 |
:setting:`DEFAULT_EXCEPTION_REPORTER_FILTER` when preparing the exception |
| 320 |
report data.) |
| 321 |
|
| 322 |
Your custom reporter class needs to inherit from |
| 323 |
:class:`django.views.debug.ExceptionReporter`. |
| 324 |
|
| 325 |
.. class:: ExceptionReporter |
| 326 |
|
| 327 |
.. attribute:: html_template_path |
| 328 |
|
| 329 |
Property that returns a :class:`pathlib.Path` representing the absolute |
| 330 |
filesystem path to a template for rendering the HTML representation of |
| 331 |
the exception. Defaults to the Django provided template. |
| 332 |
|
| 333 |
.. attribute:: text_template_path |
| 334 |
|
| 335 |
Property that returns a :class:`pathlib.Path` representing the absolute |
| 336 |
filesystem path to a template for rendering the plain-text |
| 337 |
representation of the exception. Defaults to the Django provided |
| 338 |
template. |
| 339 |
|
| 340 |
.. method:: get_traceback_data() |
| 341 |
|
| 342 |
Return a dictionary containing traceback information. |
| 343 |
|
| 344 |
This is the main extension point for customizing exception reports, for |
| 345 |
example:: |
| 346 |
|
| 347 |
from django.views.debug import ExceptionReporter |
| 348 |
|
| 349 |
|
| 350 |
class CustomExceptionReporter(ExceptionReporter): |
| 351 |
def get_traceback_data(self): |
| 352 |
data = super().get_traceback_data() |
| 353 |
# ... remove/add something here ... |
| 354 |
return data |
| 355 |
|
| 356 |
.. method:: get_traceback_html() |
| 357 |
|
| 358 |
Return HTML version of exception report. |
| 359 |
|
| 360 |
Used for HTML version of debug 500 HTTP error page. |
| 361 |
|
| 362 |
.. method:: get_traceback_text() |
| 363 |
|
| 364 |
Return plain text version of exception report. |
| 365 |
|
| 366 |
Used for plain text version of debug 500 HTTP error page and email |
| 367 |
reports. |
| 368 |
|
| 369 |
As with the filter class, you may control which exception reporter class to use |
| 370 |
within any given view by setting the ``HttpRequest``’s |
| 371 |
``exception_reporter_class`` attribute:: |
| 372 |
|
| 373 |
def my_view(request): |
| 374 |
if request.user.is_authenticated: |
| 375 |
request.exception_reporter_class = CustomExceptionReporter() |
| 376 |
... |
| 377 |
|
| 378 |
.. seealso:: |
| 379 |
|
| 380 |
You can also set up custom error reporting by writing a custom piece of |
| 381 |
:ref:`exception middleware <exception-middleware>`. If you do write custom |
| 382 |
error handling, it's a good idea to emulate Django's built-in error handling |
| 383 |
and only report/log errors if :setting:`DEBUG` is ``False``. |