Debian Codegraph @

docs/howto/error-reporting.txt

raw
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``.