Debian Codegraph @

docs/ref/logging.txt

raw
1 .. _logging-ref:
2
3 =======
4 Logging
5 =======
6
7 .. seealso::
8
9 * :ref:`logging-how-to`
10 * :ref:`Django logging overview <logging-explanation>`
11
12 .. module:: django.utils.log
13 :synopsis: Logging tools for Django applications
14
15 Django's logging module extends Python's builtin :mod:`logging`.
16
17 Logging is configured as part of the general Django :func:`django.setup`
18 function, so it's always available unless explicitly disabled.
19
20 .. _default-logging-configuration:
21
22 Django's default logging configuration
23 ======================================
24
25 By default, Django uses Python's :ref:`logging.config.dictConfig format
26 <logging-config-dictschema>`.
27
28 Default logging conditions
29 --------------------------
30
31 The full set of default logging conditions are:
32
33 When :setting:`DEBUG` is ``True``:
34
35 * The ``django`` logger sends messages in the ``django`` hierarchy (except
36 ``django.server``) at the ``INFO`` level or higher to the console.
37
38 When :setting:`DEBUG` is ``False``:
39
40 * The ``django`` logger sends messages in the ``django`` hierarchy (except
41 ``django.server``) with ``ERROR`` or ``CRITICAL`` level to
42 :class:`AdminEmailHandler`.
43
44 Independently of the value of :setting:`DEBUG`:
45
46 * The :ref:`django-server-logger` logger sends messages at the ``INFO`` level
47 or higher to the console.
48
49 All loggers except :ref:`django-server-logger` propagate logging to their
50 parents, up to the root ``django`` logger. The ``console`` and ``mail_admins``
51 handlers are attached to the root logger to provide the behavior described
52 above.
53
54 Python's own defaults send records of level ``WARNING`` and higher
55 to the console.
56
57 .. _default-logging-definition:
58
59 Default logging definition
60 --------------------------
61
62 Django's default logging configuration inherits Python's defaults. It's
63 available as ``django.utils.log.DEFAULT_LOGGING`` and defined in
64 :source:`django/utils/log.py`::
65
66 {
67 "version": 1,
68 "disable_existing_loggers": False,
69 "filters": {
70 "require_debug_false": {
71 "()": "django.utils.log.RequireDebugFalse",
72 },
73 "require_debug_true": {
74 "()": "django.utils.log.RequireDebugTrue",
75 },
76 },
77 "formatters": {
78 "django.server": {
79 "()": "django.utils.log.ServerFormatter",
80 "format": "[{server_time}] {message}",
81 "style": "{",
82 }
83 },
84 "handlers": {
85 "console": {
86 "level": "INFO",
87 "filters": ["require_debug_true"],
88 "class": "logging.StreamHandler",
89 },
90 "django.server": {
91 "level": "INFO",
92 "class": "logging.StreamHandler",
93 "formatter": "django.server",
94 },
95 "mail_admins": {
96 "level": "ERROR",
97 "filters": ["require_debug_false"],
98 "class": "django.utils.log.AdminEmailHandler",
99 },
100 },
101 "loggers": {
102 "django": {
103 "handlers": ["console", "mail_admins"],
104 "level": "INFO",
105 },
106 "django.server": {
107 "handlers": ["django.server"],
108 "level": "INFO",
109 "propagate": False,
110 },
111 },
112 }
113
114 See :ref:`configuring-logging` on how to complement or replace this default
115 logging configuration.
116
117 Django logging extensions
118 =========================
119
120 Django provides a number of utilities to handle the particular requirements of
121 logging in a web server environment.
122
123 Loggers
124 -------
125
126 Django provides several built-in loggers.
127
128 .. _django-logger:
129
130 ``django``
131 ~~~~~~~~~~
132
133 The parent logger for messages in the ``django`` :ref:`named logger hierarchy
134 <naming-loggers-hierarchy>`. Django does not post messages using this name.
135 Instead, it uses one of the loggers below.
136
137 .. _django-request-logger:
138
139 ``django.request``
140 ~~~~~~~~~~~~~~~~~~
141
142 Log messages related to the handling of requests. 5XX responses are
143 raised as ``ERROR`` messages; 4XX responses are raised as ``WARNING``
144 messages. Requests that are logged to the ``django.security`` logger aren't
145 logged to ``django.request``.
146
147 Messages to this logger have the following extra context:
148
149 * ``status_code``: The HTTP response code associated with the request.
150
151 * ``request``: The request object that generated the logging message.
152
153 .. _django-server-logger:
154
155 ``django.server``
156 ~~~~~~~~~~~~~~~~~
157
158 Log messages related to the handling of requests received by the server invoked
159 by the :djadmin:`runserver` command. HTTP 5XX responses are logged as ``ERROR``
160 messages, 4XX responses are logged as ``WARNING`` messages, and everything else
161 is logged as ``INFO``.
162
163 Messages to this logger have the following extra context:
164
165 * ``status_code``: The HTTP response code associated with the request.
166
167 * ``request``: The request object (a :py:class:`socket.socket`) that generated the logging message.
168
169 .. _django-template-logger:
170
171 ``django.template``
172 ~~~~~~~~~~~~~~~~~~~
173
174 Log messages related to the rendering of templates.
175
176 * Missing context variables are logged as ``DEBUG`` messages.
177
178 .. _django-db-logger:
179
180 ``django.db.backends``
181 ~~~~~~~~~~~~~~~~~~~~~~
182
183 Messages relating to the interaction of code with the database. For example,
184 every application-level SQL statement executed by a request is logged at the
185 ``DEBUG`` level to this logger.
186
187 Messages to this logger have the following extra context:
188
189 * ``duration``: The time taken to execute the SQL statement.
190 * ``sql``: The SQL statement that was executed.
191 * ``params``: The parameters that were used in the SQL call.
192 * ``alias``: The alias of the database used in the SQL call.
193
194 For performance reasons, SQL logging is only enabled when
195 ``settings.DEBUG`` is set to ``True``, regardless of the logging
196 level or handlers that are installed.
197
198 This logging does not include framework-level initialization (e.g.
199 ``SET TIMEZONE``). Turn on query logging in your database if you wish to view
200 all database queries.
201
202 .. _django-utils-autoreloader-logger:
203
204 ``django.utils.autoreload``
205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
206
207 Log messages related to automatic code reloading during the execution of the
208 Django development server. This logger generates an ``INFO`` message upon
209 detecting a modification in a source code file and may produce ``WARNING``
210 messages during filesystem inspection and event subscription processes.
211
212 .. _django-contrib-auth-logger:
213
214 ``django.contrib.auth``
215 ~~~~~~~~~~~~~~~~~~~~~~~
216
217 .. versionadded:: 4.2.16
218
219 Log messages related to :doc:`contrib/auth`, particularly ``ERROR`` messages
220 are generated when a :class:`~django.contrib.auth.forms.PasswordResetForm` is
221 successfully submitted but the password reset email cannot be delivered due to
222 a mail sending exception.
223
224 .. _django-contrib-gis-logger:
225
226 ``django.contrib.gis``
227 ~~~~~~~~~~~~~~~~~~~~~~
228
229 Log messages related to :doc:`contrib/gis/index` at various points: during the
230 loading of external GeoSpatial libraries (GEOS, GDAL, etc.) and when reporting
231 errors. Each ``ERROR`` log record includes the caught exception and relevant
232 contextual data.
233
234 .. _django-dispatch-logger:
235
236 ``django.dispatch``
237 ~~~~~~~~~~~~~~~~~~~
238
239 This logger is used in :doc:`signals`, specifically within the
240 :mod:`~django.dispatch.Signal` class, to report issues when dispatching a
241 signal to a connected receiver. The ``ERROR`` log record includes the caught
242 exception as ``exc_info`` and adds the following extra context:
243
244 * ``receiver``: The name of the receiver.
245 * ``err``: The exception that occurred when calling the receiver.
246
247 .. _django-security-logger:
248
249 ``django.security.*``
250 ~~~~~~~~~~~~~~~~~~~~~
251
252 The security loggers will receive messages on any occurrence of
253 :exc:`~django.core.exceptions.SuspiciousOperation` and other security-related
254 errors. There is a sub-logger for each subtype of security error, including all
255 ``SuspiciousOperation``\s. The level of the log event depends on where the
256 exception is handled. Most occurrences are logged as a warning, while
257 any ``SuspiciousOperation`` that reaches the WSGI handler will be logged as an
258 error. For example, when an HTTP ``Host`` header is included in a request from
259 a client that does not match :setting:`ALLOWED_HOSTS`, Django will return a 400
260 response, and an error message will be logged to the
261 ``django.security.DisallowedHost`` logger.
262
263 These log events will reach the ``django`` logger by default, which mails error
264 events to admins when ``DEBUG=False``. Requests resulting in a 400 response due
265 to a ``SuspiciousOperation`` will not be logged to the ``django.request``
266 logger, but only to the ``django.security`` logger.
267
268 To silence a particular type of ``SuspiciousOperation``, you can override that
269 specific logger following this example::
270
271 LOGGING = {
272 # ...
273 "handlers": {
274 "null": {
275 "class": "logging.NullHandler",
276 },
277 },
278 "loggers": {
279 "django.security.DisallowedHost": {
280 "handlers": ["null"],
281 "propagate": False,
282 },
283 },
284 # ...
285 }
286
287 Other ``django.security`` loggers not based on ``SuspiciousOperation`` are:
288
289 * ``django.security.csrf``: For :ref:`CSRF failures <csrf-rejected-requests>`.
290
291 ``django.db.backends.schema``
292 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293
294 Logs the SQL queries that are executed during schema changes to the database by
295 the :doc:`migrations framework </topics/migrations>`. Note that it won't log the
296 queries executed by :class:`~django.db.migrations.operations.RunPython`.
297 Messages to this logger have ``params`` and ``sql`` in their extra context (but
298 unlike ``django.db.backends``, not duration). The values have the same meaning
299 as explained in :ref:`django-db-logger`.
300
301 .. _django-contrib-sessions-logger:
302
303 ``django.contrib.sessions``
304 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
305
306 Log messages related to the :doc:`session framework</topics/http/sessions>`.
307
308 * Non-fatal errors occurring when using the
309 :class:`django.contrib.sessions.backends.cached_db.SessionStore` engine are
310 logged as ``ERROR`` messages with the corresponding traceback.
311
312 Handlers
313 --------
314
315 Django provides one log handler in addition to :mod:`those provided by the
316 Python logging module <python:logging.handlers>`.
317
318 .. class:: AdminEmailHandler(include_html=False, email_backend=None, reporter_class=None)
319
320 This handler sends an email to the site :setting:`ADMINS` for each log
321 message it receives.
322
323 If the log record contains a ``request`` attribute, the full details
324 of the request will be included in the email. The email subject will
325 include the phrase "internal IP" if the client's IP address is in the
326 :setting:`INTERNAL_IPS` setting; if not, it will include "EXTERNAL IP".
327
328 If the log record contains stack trace information, that stack
329 trace will be included in the email.
330
331 The ``include_html`` argument of ``AdminEmailHandler`` is used to
332 control whether the traceback email includes an HTML attachment
333 containing the full content of the debug web page that would have been
334 produced if :setting:`DEBUG` were ``True``. To set this value in your
335 configuration, include it in the handler definition for
336 ``django.utils.log.AdminEmailHandler``, like this::
337
338 "handlers": {
339 "mail_admins": {
340 "level": "ERROR",
341 "class": "django.utils.log.AdminEmailHandler",
342 "include_html": True,
343 },
344 }
345
346 Be aware of the :ref:`security implications of logging
347 <logging-security-implications>` when using the ``AdminEmailHandler``.
348
349 By setting the ``email_backend`` argument of ``AdminEmailHandler``, the
350 :ref:`email backend <topic-email-backends>` that is being used by the
351 handler can be overridden, like this::
352
353 "handlers": {
354 "mail_admins": {
355 "level": "ERROR",
356 "class": "django.utils.log.AdminEmailHandler",
357 "email_backend": "django.core.mail.backends.filebased.EmailBackend",
358 },
359 }
360
361 By default, an instance of the email backend specified in
362 :setting:`EMAIL_BACKEND` will be used.
363
364 The ``reporter_class`` argument of ``AdminEmailHandler`` allows providing
365 an ``django.views.debug.ExceptionReporter`` subclass to customize the
366 traceback text sent in the email body. You provide a string import path to
367 the class you wish to use, like this::
368
369 "handlers": {
370 "mail_admins": {
371 "level": "ERROR",
372 "class": "django.utils.log.AdminEmailHandler",
373 "include_html": True,
374 "reporter_class": "somepackage.error_reporter.CustomErrorReporter",
375 },
376 }
377
378 .. method:: send_mail(subject, message, *args, **kwargs)
379
380 Sends emails to admin users. To customize this behavior, you can
381 subclass the :class:`~django.utils.log.AdminEmailHandler` class and
382 override this method.
383
384 Filters
385 -------
386
387 Django provides some log filters in addition to those provided by the Python
388 logging module.
389
390 .. class:: CallbackFilter(callback)
391
392 This filter accepts a callback function (which should accept a single
393 argument, the record to be logged), and calls it for each record that
394 passes through the filter. Handling of that record will not proceed if the
395 callback returns False.
396
397 For instance, to filter out :exc:`~django.http.UnreadablePostError`
398 (raised when a user cancels an upload) from the admin emails, you would
399 create a filter function::
400
401 from django.http import UnreadablePostError
402
403
404 def skip_unreadable_post(record):
405 if record.exc_info:
406 exc_type, exc_value = record.exc_info[:2]
407 if isinstance(exc_value, UnreadablePostError):
408 return False
409 return True
410
411 and then add it to your logging config::
412
413 LOGGING = {
414 # ...
415 "filters": {
416 "skip_unreadable_posts": {
417 "()": "django.utils.log.CallbackFilter",
418 "callback": skip_unreadable_post,
419 },
420 },
421 "handlers": {
422 "mail_admins": {
423 "level": "ERROR",
424 "filters": ["skip_unreadable_posts"],
425 "class": "django.utils.log.AdminEmailHandler",
426 },
427 },
428 # ...
429 }
430
431 .. class:: RequireDebugFalse()
432
433 This filter will only pass on records when settings.DEBUG is False.
434
435 This filter is used as follows in the default :setting:`LOGGING`
436 configuration to ensure that the :class:`AdminEmailHandler` only sends
437 error emails to admins when :setting:`DEBUG` is ``False``::
438
439 LOGGING = {
440 # ...
441 "filters": {
442 "require_debug_false": {
443 "()": "django.utils.log.RequireDebugFalse",
444 },
445 },
446 "handlers": {
447 "mail_admins": {
448 "level": "ERROR",
449 "filters": ["require_debug_false"],
450 "class": "django.utils.log.AdminEmailHandler",
451 },
452 },
453 # ...
454 }
455
456 .. class:: RequireDebugTrue()
457
458 This filter is similar to :class:`RequireDebugFalse`, except that records are
459 passed only when :setting:`DEBUG` is ``True``.