Fixed #24361 -- Clarified docs on reconfiguring logging.

and the log levels and other properties that you want those components

to have.

Prior to Django 1.5, the :setting:`LOGGING` setting always overwrote the

:ref:`default Django logging configuration <default-logging-configuration>`.

From Django 1.5 forward, it is possible to get the project's logging

configuration merged with Django's defaults, hence you can decide if you want to

add to, or replace the existing configuration.

By default, the :setting:`LOGGING` setting is merged with :ref:`Django's

default logging configuration <default-logging-configuration>` using the

following scheme.

If the ``disable_existing_loggers`` key in the :setting:`LOGGING` dictConfig is

set to ``True`` (which is the default) the default configuration is completely

overridden. Alternatively you can redefine some or all of the loggers by

setting ``disable_existing_loggers`` to ``False``.

set to ``True`` (which is the default) then all loggers from the default

configuration will be disabled. Disabled loggers are not the same as removed;

the logger will still exist, but will silently discard anything logged to it,

not even propagating entries to a parent logger. Thus you should be very

careful using ``'disable_existing_loggers': True``; it's probably not what you

want. Instead, you can set ``disable_existing_loggers`` to ``False`` and

redefine some or all of the default loggers; or you can set

:setting:`LOGGING_CONFIG` to ``None`` and :ref:`handle logging config yourself

<disabling-logging-configuration>`.

Logging is configured as part of the general Django ``setup()`` function.

Therefore, you can be certain that loggers are always ready for use in your

The full documentation for `dictConfig format`_ is the best source of

information about logging configuration dictionaries. However, to give

you a taste of what is possible, here are a couple examples.

you a taste of what is possible, here are several examples.

First, here's a simple configuration which writes all request logging from the

:ref:`django-request-logger` logger to a local file::

If you use this example, be sure to change the ``'filename'`` path to a

location that's writable by the user that's running the Django application.

Second, here's an example of a fairly complex logging setup, configured using

:func:`logging.config.dictConfig`::

Second, here's an example of how to make the logging system print Django's

logging to the console. It overrides the fact that ``django.request`` and

``django.security`` don't propagate their log entries by default. It may be

useful during local development.

By default, this config only sends messages of level ``INFO`` or higher to the

console. Django does not log many such messages. Set the environment variable

``DJANGO_LOG_LEVEL=DEBUG`` to see all of Django's debug logging which is very

verbose as it includes all database queries::

    import os

    LOGGING = {

        'version': 1,

        'disable_existing_loggers': True,

        'disable_existing_loggers': False,

        'handlers': {

            'console': {

                'class': 'logging.StreamHandler',

            },

        },

        'loggers': {

            'django': {

                'handlers': ['console'],

                'level': os.getenv('DJANGO_LOG_LEVEL', 'INFO'),

            },

        },

    }

Finally, here's an example of a fairly complex logging setup::

    LOGGING = {

        'version': 1,

        'disable_existing_loggers': False,

        'formatters': {

            'verbose': {

                'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'

* Identifies the configuration as being in 'dictConfig version 1'

  format. At present, this is the only dictConfig format version.

* Disables all existing logging configurations.

* Defines two formatters:

  * ``simple``, that just outputs the log level name (e.g.,

that takes a single argument. The contents of :setting:`LOGGING` will

be provided as the value of that argument when logging is configured.

.. _disabling-logging-configuration:

Disabling logging configuration

-------------------------------

If you don't want to configure logging at all (or you want to manually

configure logging using your own approach), you can set

:setting:`LOGGING_CONFIG` to ``None``. This will disable the

configuration process.

configuration process for :ref:`Django's default logging

<default-logging-configuration>`. Here's an example that disables Django's

logging configuration and then manually configures logging:

.. snippet::

    :filename: settings.py

.. note::

    Setting :setting:`LOGGING_CONFIG` to ``None`` only means that the

    configuration process is disabled, not logging itself. If you

    disable the configuration process, Django will still make logging

    calls, falling back to whatever default logging behavior is

    defined.

    LOGGING_CONFIG = None

    import logging.config

    logging.config.dictConfig(...)

Setting :setting:`LOGGING_CONFIG` to ``None`` only means that the automatic

configuration process is disabled, not logging itself. If you disable the

configuration process, Django will still make logging calls, falling back to

whatever default logging behavior is defined.

Django's logging extensions

===========================

Django's default logging configuration

======================================

By default, Django configures the ``django.request`` logger so that all messages

with ``ERROR`` or ``CRITICAL`` level are sent to :class:`AdminEmailHandler`, as

long as the :setting:`DEBUG` setting is set to ``False``.

By default, Django configures the following logging:

When :setting:`DEBUG` is ``True``:

* The ``django`` catch-all logger sends all messages at the ``INFO`` level or

  higher to the console. Django doesn't make any such logging calls at this

  time (all logging is at the ``DEBUG`` level or handled by the

  ``django.request`` and ``django.security`` loggers).

* The ``py.warnings`` logger, which handles messages from ``warnings.warn()``,

  sends messages to the console.

When :setting:`DEBUG` is ``False``:

All messages reaching the ``django`` catch-all logger when :setting:`DEBUG` is

``True`` are sent to the console. They are simply discarded (sent to

``NullHandler``) when :setting:`DEBUG` is ``False``.

* The ``django.request`` and ``django.security`` loggers send messages with

  ``ERROR`` or ``CRITICAL`` level to :class:`AdminEmailHandler`. These loggers

  ignore anything at the ``WARNING`` level or below and log entries aren't

  propagated to other loggers (they won't reach the ``django`` catch-all

  logger, even when ``DEBUG`` is ``True``).

See also :ref:`Configuring logging <configuring-logging>` to learn how you can

complement or replace this default logging configuration.