mirror of
https://github.com/django/django.git
synced 2024-12-22 09:05:43 +00:00
Refs #32880 -- Moved logging reference to new document.
Completed a first step in moving reference and how-to material out of the topic document.
This commit is contained in:
Daniele Procida
Mariusz Felisiak
parent
8bca838f4a
commit
e3d55eeb14
@ -13,7 +13,8 @@ request_logger = logging.getLogger('django.request')
|
||||
# Default logging for Django. This sends an email to the site admins on every
|
||||
# HTTP 500 error. Depending on DEBUG, all other log records are either sent to
|
||||
# the console (DEBUG=True) or discarded (DEBUG=False) by means of the
|
||||
# require_debug_true filter.
|
||||
# require_debug_true filter. This configuration is quoted in
|
||||
# docs/ref/logging.txt; please amend it there if edited here.
|
||||
DEFAULT_LOGGING = {
|
||||
'version': 1,
|
||||
'disable_existing_loggers': False,
|
||||
|
||||
@ -16,6 +16,7 @@ API Reference
|
||||
exceptions
|
||||
files/index
|
||||
forms/index
|
||||
logging
|
||||
middleware
|
||||
migration-operations
|
||||
models/index
|
||||
|
||||
379
docs/ref/logging.txt
Normal file
379
docs/ref/logging.txt
Normal file
@ -0,0 +1,379 @@
|
||||
.. _logging_ref:
|
||||
|
||||
=======
|
||||
Logging
|
||||
=======
|
||||
|
||||
.. module:: django.utils.log
|
||||
:synopsis: Logging tools for Django applications
|
||||
|
||||
Django's logging module extends Python's builtin :mod:`logging`.
|
||||
|
||||
Logging is configured as part of the general Django :func:`django.setup`
|
||||
function, so it's always available unless explicitly disabled.
|
||||
|
||||
.. _default-logging-configuration:
|
||||
|
||||
Django's default logging configuration
|
||||
======================================
|
||||
|
||||
By default, Django uses Python's :ref:`logging.config.dictConfig format
|
||||
<logging-config-dictschema>`.
|
||||
|
||||
Default logging conditions
|
||||
--------------------------
|
||||
|
||||
The full set of default logging conditions are:
|
||||
|
||||
When :setting:`DEBUG` is ``True``:
|
||||
|
||||
* The ``django`` logger sends messages in the ``django`` hierarchy (except
|
||||
``django.server``) at the ``INFO`` level or higher to the console.
|
||||
|
||||
When :setting:`DEBUG` is ``False``:
|
||||
|
||||
* The ``django`` logger sends messages in the ``django`` hierarchy (except
|
||||
``django.server``) with ``ERROR`` or ``CRITICAL`` level to
|
||||
:class:`AdminEmailHandler`.
|
||||
|
||||
Independently of the value of :setting:`DEBUG`:
|
||||
|
||||
* The :ref:`django-server-logger` logger sends messages at the ``INFO`` level
|
||||
or higher to the console.
|
||||
|
||||
All loggers except :ref:`django-server-logger` propagate logging to their
|
||||
parents, up to the root ``django`` logger. The ``console`` and ``mail_admins``
|
||||
handlers are attached to the root logger to provide the behavior described
|
||||
above.
|
||||
|
||||
Default logging definition
|
||||
--------------------------
|
||||
|
||||
The default configuration is available as ``django.utils.log.DEFAULT_LOGGING``
|
||||
and defined in :source:`django/utils/log.py`::
|
||||
|
||||
{
|
||||
'version': 1,
|
||||
'disable_existing_loggers': False,
|
||||
'filters': {
|
||||
'require_debug_false': {
|
||||
'()': 'django.utils.log.RequireDebugFalse',
|
||||
},
|
||||
'require_debug_true': {
|
||||
'()': 'django.utils.log.RequireDebugTrue',
|
||||
},
|
||||
},
|
||||
'formatters': {
|
||||
'django.server': {
|
||||
'()': 'django.utils.log.ServerFormatter',
|
||||
'format': '[{server_time}] {message}',
|
||||
'style': '{',
|
||||
}
|
||||
},
|
||||
'handlers': {
|
||||
'console': {
|
||||
'level': 'INFO',
|
||||
'filters': ['require_debug_true'],
|
||||
'class': 'logging.StreamHandler',
|
||||
},
|
||||
'django.server': {
|
||||
'level': 'INFO',
|
||||
'class': 'logging.StreamHandler',
|
||||
'formatter': 'django.server',
|
||||
},
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'filters': ['require_debug_false'],
|
||||
'class': 'django.utils.log.AdminEmailHandler'
|
||||
}
|
||||
},
|
||||
'loggers': {
|
||||
'django': {
|
||||
'handlers': ['console', 'mail_admins'],
|
||||
'level': 'INFO',
|
||||
},
|
||||
'django.server': {
|
||||
'handlers': ['django.server'],
|
||||
'level': 'INFO',
|
||||
'propagate': False,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
See :ref:`configuring-logging` on how to complement or replace this default
|
||||
logging configuration.
|
||||
|
||||
Django logging extensions
|
||||
=========================
|
||||
|
||||
Django provides a number of utilities to handle the particular requirements of
|
||||
logging in a web server environment.
|
||||
|
||||
Loggers
|
||||
-------
|
||||
|
||||
Django provides several built-in loggers.
|
||||
|
||||
.. _django-logger:
|
||||
|
||||
``django``
|
||||
~~~~~~~~~~
|
||||
|
||||
The parent logger for messages in the ``django`` :ref:`named logger hierarchy
|
||||
<naming-loggers-hierarchy>`. Django does not post messages using this name.
|
||||
Instead, it uses one of the loggers below.
|
||||
|
||||
.. _django-request-logger:
|
||||
|
||||
``django.request``
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Log messages related to the handling of requests. 5XX responses are
|
||||
raised as ``ERROR`` messages; 4XX responses are raised as ``WARNING``
|
||||
messages. Requests that are logged to the ``django.security`` logger aren't
|
||||
logged to ``django.request``.
|
||||
|
||||
Messages to this logger have the following extra context:
|
||||
|
||||
* ``status_code``: The HTTP response code associated with the request.
|
||||
|
||||
* ``request``: The request object that generated the logging message.
|
||||
|
||||
.. _django-server-logger:
|
||||
|
||||
``django.server``
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Log messages related to the handling of requests received by the server invoked
|
||||
by the :djadmin:`runserver` command. HTTP 5XX responses are logged as ``ERROR``
|
||||
messages, 4XX responses are logged as ``WARNING`` messages, and everything else
|
||||
is logged as ``INFO``.
|
||||
|
||||
Messages to this logger have the following extra context:
|
||||
|
||||
* ``status_code``: The HTTP response code associated with the request.
|
||||
|
||||
* ``request``: The request object that generated the logging message.
|
||||
|
||||
.. _django-template-logger:
|
||||
|
||||
``django.template``
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Log messages related to the rendering of templates.
|
||||
|
||||
* Missing context variables are logged as ``DEBUG`` messages.
|
||||
|
||||
.. _django-db-logger:
|
||||
|
||||
``django.db.backends``
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Messages relating to the interaction of code with the database. For example,
|
||||
every application-level SQL statement executed by a request is logged at the
|
||||
``DEBUG`` level to this logger.
|
||||
|
||||
Messages to this logger have the following extra context:
|
||||
|
||||
* ``duration``: The time taken to execute the SQL statement.
|
||||
* ``sql``: The SQL statement that was executed.
|
||||
* ``params``: The parameters that were used in the SQL call.
|
||||
|
||||
For performance reasons, SQL logging is only enabled when
|
||||
``settings.DEBUG`` is set to ``True``, regardless of the logging
|
||||
level or handlers that are installed.
|
||||
|
||||
This logging does not include framework-level initialization (e.g.
|
||||
``SET TIMEZONE``) or transaction management queries (e.g. ``BEGIN``,
|
||||
``COMMIT``, and ``ROLLBACK``). Turn on query logging in your database if you
|
||||
wish to view all database queries.
|
||||
|
||||
.. _django-security-logger:
|
||||
|
||||
``django.security.*``
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The security loggers will receive messages on any occurrence of
|
||||
:exc:`~django.core.exceptions.SuspiciousOperation` and other security-related
|
||||
errors. There is a sub-logger for each subtype of security error, including all
|
||||
``SuspiciousOperation``\s. The level of the log event depends on where the
|
||||
exception is handled. Most occurrences are logged as a warning, while
|
||||
any ``SuspiciousOperation`` that reaches the WSGI handler will be logged as an
|
||||
error. For example, when an HTTP ``Host`` header is included in a request from
|
||||
a client that does not match :setting:`ALLOWED_HOSTS`, Django will return a 400
|
||||
response, and an error message will be logged to the
|
||||
``django.security.DisallowedHost`` logger.
|
||||
|
||||
These log events will reach the ``django`` logger by default, which mails error
|
||||
events to admins when ``DEBUG=False``. Requests resulting in a 400 response due
|
||||
to a ``SuspiciousOperation`` will not be logged to the ``django.request``
|
||||
logger, but only to the ``django.security`` logger.
|
||||
|
||||
To silence a particular type of ``SuspiciousOperation``, you can override that
|
||||
specific logger following this example::
|
||||
|
||||
'handlers': {
|
||||
'null': {
|
||||
'class': 'logging.NullHandler',
|
||||
},
|
||||
},
|
||||
'loggers': {
|
||||
'django.security.DisallowedHost': {
|
||||
'handlers': ['null'],
|
||||
'propagate': False,
|
||||
},
|
||||
},
|
||||
|
||||
Other ``django.security`` loggers not based on ``SuspiciousOperation`` are:
|
||||
|
||||
* ``django.security.csrf``: For :ref:`CSRF failures <csrf-rejected-requests>`.
|
||||
|
||||
``django.db.backends.schema``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Logs the SQL queries that are executed during schema changes to the database by
|
||||
the :doc:`migrations framework </topics/migrations>`. Note that it won't log the
|
||||
queries executed by :class:`~django.db.migrations.operations.RunPython`.
|
||||
Messages to this logger have ``params`` and ``sql`` in their extra context (but
|
||||
unlike ``django.db.backends``, not duration). The values have the same meaning
|
||||
as explained in :ref:`django-db-logger`.
|
||||
|
||||
Handlers
|
||||
--------
|
||||
|
||||
Django provides one log handler in addition to those provided by the
|
||||
Python logging module.
|
||||
|
||||
.. class:: AdminEmailHandler(include_html=False, email_backend=None, reporter_class=None)
|
||||
|
||||
This handler sends an email to the site :setting:`ADMINS` for each log
|
||||
message it receives.
|
||||
|
||||
If the log record contains a ``request`` attribute, the full details
|
||||
of the request will be included in the email. The email subject will
|
||||
include the phrase "internal IP" if the client's IP address is in the
|
||||
:setting:`INTERNAL_IPS` setting; if not, it will include "EXTERNAL IP".
|
||||
|
||||
If the log record contains stack trace information, that stack
|
||||
trace will be included in the email.
|
||||
|
||||
The ``include_html`` argument of ``AdminEmailHandler`` is used to
|
||||
control whether the traceback email includes an HTML attachment
|
||||
containing the full content of the debug Web page that would have been
|
||||
produced if :setting:`DEBUG` were ``True``. To set this value in your
|
||||
configuration, include it in the handler definition for
|
||||
``django.utils.log.AdminEmailHandler``, like this::
|
||||
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'class': 'django.utils.log.AdminEmailHandler',
|
||||
'include_html': True,
|
||||
},
|
||||
},
|
||||
|
||||
Be aware of the :ref:`security implications of logging
|
||||
<logging-security-implications>` when using the ``AdminEmailHandler``.
|
||||
|
||||
By setting the ``email_backend`` argument of ``AdminEmailHandler``, the
|
||||
:ref:`email backend <topic-email-backends>` that is being used by the
|
||||
handler can be overridden, like this::
|
||||
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'class': 'django.utils.log.AdminEmailHandler',
|
||||
'email_backend': 'django.core.mail.backends.filebased.EmailBackend',
|
||||
},
|
||||
},
|
||||
|
||||
By default, an instance of the email backend specified in
|
||||
:setting:`EMAIL_BACKEND` will be used.
|
||||
|
||||
The ``reporter_class`` argument of ``AdminEmailHandler`` allows providing
|
||||
an ``django.views.debug.ExceptionReporter`` subclass to customize the
|
||||
traceback text sent in the email body. You provide a string import path to
|
||||
the class you wish to use, like this::
|
||||
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'class': 'django.utils.log.AdminEmailHandler',
|
||||
'include_html': True,
|
||||
'reporter_class': 'somepackage.error_reporter.CustomErrorReporter',
|
||||
},
|
||||
},
|
||||
|
||||
.. method:: send_mail(subject, message, *args, **kwargs)
|
||||
|
||||
Sends emails to admin users. To customize this behavior, you can
|
||||
subclass the :class:`~django.utils.log.AdminEmailHandler` class and
|
||||
override this method.
|
||||
|
||||
Filters
|
||||
-------
|
||||
|
||||
Django provides some log filters in addition to those provided by the Python
|
||||
logging module.
|
||||
|
||||
.. class:: CallbackFilter(callback)
|
||||
|
||||
This filter accepts a callback function (which should accept a single
|
||||
argument, the record to be logged), and calls it for each record that
|
||||
passes through the filter. Handling of that record will not proceed if the
|
||||
callback returns False.
|
||||
|
||||
For instance, to filter out :exc:`~django.http.UnreadablePostError`
|
||||
(raised when a user cancels an upload) from the admin emails, you would
|
||||
create a filter function::
|
||||
|
||||
from django.http import UnreadablePostError
|
||||
|
||||
def skip_unreadable_post(record):
|
||||
if record.exc_info:
|
||||
exc_type, exc_value = record.exc_info[:2]
|
||||
if isinstance(exc_value, UnreadablePostError):
|
||||
return False
|
||||
return True
|
||||
|
||||
and then add it to your logging config::
|
||||
|
||||
'filters': {
|
||||
'skip_unreadable_posts': {
|
||||
'()': 'django.utils.log.CallbackFilter',
|
||||
'callback': skip_unreadable_post,
|
||||
},
|
||||
},
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'filters': ['skip_unreadable_posts'],
|
||||
'class': 'django.utils.log.AdminEmailHandler',
|
||||
},
|
||||
},
|
||||
|
||||
.. class:: RequireDebugFalse()
|
||||
|
||||
This filter will only pass on records when settings.DEBUG is False.
|
||||
|
||||
This filter is used as follows in the default :setting:`LOGGING`
|
||||
configuration to ensure that the :class:`AdminEmailHandler` only sends
|
||||
error emails to admins when :setting:`DEBUG` is ``False``::
|
||||
|
||||
'filters': {
|
||||
'require_debug_false': {
|
||||
'()': 'django.utils.log.RequireDebugFalse',
|
||||
},
|
||||
},
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'filters': ['require_debug_false'],
|
||||
'class': 'django.utils.log.AdminEmailHandler',
|
||||
},
|
||||
},
|
||||
|
||||
.. class:: RequireDebugTrue()
|
||||
|
||||
This filter is similar to :class:`RequireDebugFalse`, except that records are
|
||||
passed only when :setting:`DEBUG` is ``True``.
|
||||
@ -2,16 +2,16 @@
|
||||
Logging
|
||||
=======
|
||||
|
||||
.. module:: django.utils.log
|
||||
:synopsis: Logging tools for Django applications
|
||||
.. seealso::
|
||||
|
||||
:ref:`Django logging reference <logging_ref>`.
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
Django uses Python's builtin :mod:`logging` module to perform system logging.
|
||||
The usage of this module is discussed in detail in Python's own documentation.
|
||||
However, if you've never used Python's logging framework (or even if you have),
|
||||
here's a quick primer.
|
||||
Django uses and extends Python's builtin :mod:`logging` module to perform
|
||||
system logging. This module is discussed in detail in Python's own
|
||||
documentation; this section provides a quick overview.
|
||||
|
||||
The cast of players
|
||||
-------------------
|
||||
@ -196,6 +196,11 @@ any dot-separated name to identify your logger::
|
||||
# Get an instance of a specific named logger
|
||||
logger = logging.getLogger('project.interesting.stuff')
|
||||
|
||||
.. _naming-loggers-hierarchy:
|
||||
|
||||
Logger hierarchy
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The dotted paths of logger names define a hierarchy. The
|
||||
``project.interesting`` logger is considered to be a parent of the
|
||||
``project.interesting.stuff`` logger; the ``project`` logger
|
||||
@ -465,9 +470,9 @@ This logging configuration does the following things:
|
||||
(or higher) message to ``sys.stderr``. This handler uses the ``simple``
|
||||
output format.
|
||||
|
||||
* ``mail_admins``, an :class:`AdminEmailHandler`, which emails any ``ERROR``
|
||||
(or higher) message to the site :setting:`ADMINS`. This handler uses the
|
||||
``special`` filter.
|
||||
* ``mail_admins``, an :class:`~django.utils.log.AdminEmailHandler`, which
|
||||
emails any ``ERROR`` (or higher) message to the site :setting:`ADMINS`.
|
||||
This handler uses the ``special`` filter.
|
||||
|
||||
* Configures three loggers:
|
||||
|
||||
@ -532,314 +537,6 @@ configuring the logging in your settings file will load your logging config
|
||||
immediately. As such, your logging config must appear *after* any settings on
|
||||
which it depends.
|
||||
|
||||
Django logging extension reference
|
||||
==================================
|
||||
|
||||
Django provides a number of utilities to handle the unique
|
||||
requirements of logging in a web server environment.
|
||||
|
||||
Loggers
|
||||
-------
|
||||
|
||||
Django provides several built-in loggers.
|
||||
|
||||
.. _django-logger:
|
||||
|
||||
``django``
|
||||
~~~~~~~~~~
|
||||
|
||||
The catch-all logger for messages in the ``django`` hierarchy. No messages are
|
||||
posted using this name but instead using one of the loggers below.
|
||||
|
||||
.. _django-request-logger:
|
||||
|
||||
``django.request``
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Log messages related to the handling of requests. 5XX responses are
|
||||
raised as ``ERROR`` messages; 4XX responses are raised as ``WARNING``
|
||||
messages. Requests that are logged to the ``django.security`` logger aren't
|
||||
logged to ``django.request``.
|
||||
|
||||
Messages to this logger have the following extra context:
|
||||
|
||||
* ``status_code``: The HTTP response code associated with the
|
||||
request.
|
||||
|
||||
* ``request``: The request object that generated the logging
|
||||
message.
|
||||
|
||||
.. _django-server-logger:
|
||||
|
||||
``django.server``
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Log messages related to the handling of requests received by the server invoked
|
||||
by the :djadmin:`runserver` command. HTTP 5XX responses are logged as ``ERROR``
|
||||
messages, 4XX responses are logged as ``WARNING`` messages, and everything else
|
||||
is logged as ``INFO``.
|
||||
|
||||
Messages to this logger have the following extra context:
|
||||
|
||||
* ``status_code``: The HTTP response code associated with the request.
|
||||
|
||||
* ``request``: The request object that generated the logging message.
|
||||
|
||||
.. _django-template-logger:
|
||||
|
||||
``django.template``
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Log messages related to the rendering of templates.
|
||||
|
||||
* Missing context variables are logged as ``DEBUG`` messages.
|
||||
|
||||
.. _django-db-logger:
|
||||
|
||||
``django.db.backends``
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Messages relating to the interaction of code with the database. For example,
|
||||
every application-level SQL statement executed by a request is logged at the
|
||||
``DEBUG`` level to this logger.
|
||||
|
||||
Messages to this logger have the following extra context:
|
||||
|
||||
* ``duration``: The time taken to execute the SQL statement.
|
||||
* ``sql``: The SQL statement that was executed.
|
||||
* ``params``: The parameters that were used in the SQL call.
|
||||
|
||||
For performance reasons, SQL logging is only enabled when
|
||||
``settings.DEBUG`` is set to ``True``, regardless of the logging
|
||||
level or handlers that are installed.
|
||||
|
||||
This logging does not include framework-level initialization (e.g.
|
||||
``SET TIMEZONE``) or transaction management queries (e.g. ``BEGIN``,
|
||||
``COMMIT``, and ``ROLLBACK``). Turn on query logging in your database if you
|
||||
wish to view all database queries.
|
||||
|
||||
.. _django-security-logger:
|
||||
|
||||
``django.security.*``
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The security loggers will receive messages on any occurrence of
|
||||
:exc:`~django.core.exceptions.SuspiciousOperation` and other security-related
|
||||
errors. There is a sub-logger for each subtype of security error, including all
|
||||
``SuspiciousOperation``\s. The level of the log event depends on where the
|
||||
exception is handled. Most occurrences are logged as a warning, while
|
||||
any ``SuspiciousOperation`` that reaches the WSGI handler will be logged as an
|
||||
error. For example, when an HTTP ``Host`` header is included in a request from
|
||||
a client that does not match :setting:`ALLOWED_HOSTS`, Django will return a 400
|
||||
response, and an error message will be logged to the
|
||||
``django.security.DisallowedHost`` logger.
|
||||
|
||||
These log events will reach the ``django`` logger by default, which mails error
|
||||
events to admins when ``DEBUG=False``. Requests resulting in a 400 response due
|
||||
to a ``SuspiciousOperation`` will not be logged to the ``django.request``
|
||||
logger, but only to the ``django.security`` logger.
|
||||
|
||||
To silence a particular type of ``SuspiciousOperation``, you can override that
|
||||
specific logger following this example::
|
||||
|
||||
'handlers': {
|
||||
'null': {
|
||||
'class': 'logging.NullHandler',
|
||||
},
|
||||
},
|
||||
'loggers': {
|
||||
'django.security.DisallowedHost': {
|
||||
'handlers': ['null'],
|
||||
'propagate': False,
|
||||
},
|
||||
},
|
||||
|
||||
Other ``django.security`` loggers not based on ``SuspiciousOperation`` are:
|
||||
|
||||
* ``django.security.csrf``: For :ref:`CSRF failures <csrf-rejected-requests>`.
|
||||
|
||||
``django.db.backends.schema``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Logs the SQL queries that are executed during schema changes to the database by
|
||||
the :doc:`migrations framework </topics/migrations>`. Note that it won't log the
|
||||
queries executed by :class:`~django.db.migrations.operations.RunPython`.
|
||||
Messages to this logger have ``params`` and ``sql`` in their extra context (but
|
||||
unlike ``django.db.backends``, not duration). The values have the same meaning
|
||||
as explained in :ref:`django-db-logger`.
|
||||
|
||||
Handlers
|
||||
--------
|
||||
|
||||
Django provides one log handler in addition to those provided by the
|
||||
Python logging module.
|
||||
|
||||
.. class:: AdminEmailHandler(include_html=False, email_backend=None, reporter_class=None)
|
||||
|
||||
This handler sends an email to the site :setting:`ADMINS` for each log
|
||||
message it receives.
|
||||
|
||||
If the log record contains a ``request`` attribute, the full details
|
||||
of the request will be included in the email. The email subject will
|
||||
include the phrase "internal IP" if the client's IP address is in the
|
||||
:setting:`INTERNAL_IPS` setting; if not, it will include "EXTERNAL IP".
|
||||
|
||||
If the log record contains stack trace information, that stack
|
||||
trace will be included in the email.
|
||||
|
||||
The ``include_html`` argument of ``AdminEmailHandler`` is used to
|
||||
control whether the traceback email includes an HTML attachment
|
||||
containing the full content of the debug Web page that would have been
|
||||
produced if :setting:`DEBUG` were ``True``. To set this value in your
|
||||
configuration, include it in the handler definition for
|
||||
``django.utils.log.AdminEmailHandler``, like this::
|
||||
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'class': 'django.utils.log.AdminEmailHandler',
|
||||
'include_html': True,
|
||||
}
|
||||
},
|
||||
|
||||
Be aware of the :ref:`security implications of logging
|
||||
<logging-security-implications>` when using the ``AdminEmailHandler``.
|
||||
|
||||
By setting the ``email_backend`` argument of ``AdminEmailHandler``, the
|
||||
:ref:`email backend <topic-email-backends>` that is being used by the
|
||||
handler can be overridden, like this::
|
||||
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'class': 'django.utils.log.AdminEmailHandler',
|
||||
'email_backend': 'django.core.mail.backends.filebased.EmailBackend',
|
||||
}
|
||||
},
|
||||
|
||||
By default, an instance of the email backend specified in
|
||||
:setting:`EMAIL_BACKEND` will be used.
|
||||
|
||||
The ``reporter_class`` argument of ``AdminEmailHandler`` allows providing
|
||||
an ``django.views.debug.ExceptionReporter`` subclass to customize the
|
||||
traceback text sent in the email body. You provide a string import path to
|
||||
the class you wish to use, like this::
|
||||
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'class': 'django.utils.log.AdminEmailHandler',
|
||||
'include_html': True,
|
||||
'reporter_class': 'somepackage.error_reporter.CustomErrorReporter'
|
||||
}
|
||||
},
|
||||
|
||||
.. method:: send_mail(subject, message, *args, **kwargs)
|
||||
|
||||
Sends emails to admin users. To customize this behavior, you can
|
||||
subclass the :class:`~django.utils.log.AdminEmailHandler` class and
|
||||
override this method.
|
||||
|
||||
Filters
|
||||
-------
|
||||
|
||||
Django provides some log filters in addition to those provided by the Python
|
||||
logging module.
|
||||
|
||||
.. class:: CallbackFilter(callback)
|
||||
|
||||
This filter accepts a callback function (which should accept a single
|
||||
argument, the record to be logged), and calls it for each record that
|
||||
passes through the filter. Handling of that record will not proceed if the
|
||||
callback returns False.
|
||||
|
||||
For instance, to filter out :exc:`~django.http.UnreadablePostError`
|
||||
(raised when a user cancels an upload) from the admin emails, you would
|
||||
create a filter function::
|
||||
|
||||
from django.http import UnreadablePostError
|
||||
|
||||
def skip_unreadable_post(record):
|
||||
if record.exc_info:
|
||||
exc_type, exc_value = record.exc_info[:2]
|
||||
if isinstance(exc_value, UnreadablePostError):
|
||||
return False
|
||||
return True
|
||||
|
||||
and then add it to your logging config::
|
||||
|
||||
'filters': {
|
||||
'skip_unreadable_posts': {
|
||||
'()': 'django.utils.log.CallbackFilter',
|
||||
'callback': skip_unreadable_post,
|
||||
}
|
||||
},
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'filters': ['skip_unreadable_posts'],
|
||||
'class': 'django.utils.log.AdminEmailHandler'
|
||||
}
|
||||
},
|
||||
|
||||
.. class:: RequireDebugFalse()
|
||||
|
||||
This filter will only pass on records when settings.DEBUG is False.
|
||||
|
||||
This filter is used as follows in the default :setting:`LOGGING`
|
||||
configuration to ensure that the :class:`AdminEmailHandler` only sends
|
||||
error emails to admins when :setting:`DEBUG` is ``False``::
|
||||
|
||||
'filters': {
|
||||
'require_debug_false': {
|
||||
'()': 'django.utils.log.RequireDebugFalse',
|
||||
}
|
||||
},
|
||||
'handlers': {
|
||||
'mail_admins': {
|
||||
'level': 'ERROR',
|
||||
'filters': ['require_debug_false'],
|
||||
'class': 'django.utils.log.AdminEmailHandler'
|
||||
}
|
||||
},
|
||||
|
||||
.. class:: RequireDebugTrue()
|
||||
|
||||
This filter is similar to :class:`RequireDebugFalse`, except that records are
|
||||
passed only when :setting:`DEBUG` is ``True``.
|
||||
|
||||
.. _default-logging-configuration:
|
||||
|
||||
Django's default logging configuration
|
||||
======================================
|
||||
|
||||
By default, Django configures the following logging:
|
||||
|
||||
When :setting:`DEBUG` is ``True``:
|
||||
|
||||
* The ``django`` logger sends messages in the ``django`` hierarchy (except
|
||||
``django.server``) at the ``INFO`` level or higher to the console.
|
||||
|
||||
When :setting:`DEBUG` is ``False``:
|
||||
|
||||
* The ``django`` logger sends messages in the ``django`` hierarchy (except
|
||||
``django.server``) with ``ERROR`` or ``CRITICAL`` level to
|
||||
:class:`AdminEmailHandler`.
|
||||
|
||||
Independent of the value of :setting:`DEBUG`:
|
||||
|
||||
* The :ref:`django-server-logger` logger sends messages at the ``INFO`` level
|
||||
or higher to the console.
|
||||
|
||||
All loggers except :ref:`django-server-logger` propagate logging to their
|
||||
parents, up to the root ``django`` logger. The ``console`` and ``mail_admins``
|
||||
handlers are attached to the root logger to provide the behavior described
|
||||
above.
|
||||
|
||||
See also :ref:`Configuring logging <configuring-logging>` to learn how you can
|
||||
complement or replace this default logging configuration defined in
|
||||
:source:`django/utils/log.py`.
|
||||
|
||||
.. _logging-security-implications:
|
||||
|
||||
Security implications
|
||||
@ -862,12 +559,12 @@ read more about how to :ref:`filter error reports <filtering-error-reports>`.
|
||||
``AdminEmailHandler``
|
||||
---------------------
|
||||
|
||||
The built-in :class:`AdminEmailHandler` deserves a mention in the context of
|
||||
security. If its ``include_html`` option is enabled, the email message it sends
|
||||
will contain a full traceback, with names and values of local variables at each
|
||||
level of the stack, plus the values of your Django settings (in other words,
|
||||
the same level of detail that is exposed in a web page when :setting:`DEBUG` is
|
||||
``True``).
|
||||
The built-in :class:`~django.utils.log.AdminEmailHandler` deserves a mention in
|
||||
the context of security. If its ``include_html`` option is enabled, the email
|
||||
message it sends will contain a full traceback, with names and values of local
|
||||
variables at each level of the stack, plus the values of your Django settings
|
||||
(in other words, the same level of detail that is exposed in a web page when
|
||||
:setting:`DEBUG` is ``True``).
|
||||
|
||||
It's generally not considered a good idea to send such potentially sensitive
|
||||
information over email. Consider instead using one of the many third-party
|
||||
|
||||
Loading…
Reference in New Issue
Block a user