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