[1.8.x] Fixed #24361 -- Clarified docs on reconfiguring logging.

Thanks Tuttle for the report and draft patch, and Carl Meyer for
help and review.

Backport of c633667da3 from master

docs/topics/logging.txt

@@ -212,16 +212,20 @@ handlers, filters and formatters that you want in your logging setup,
 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
@@ -234,7 +238,7 @@ Examples
 
 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::
@@ -261,12 +265,39 @@ First, here's a simple configuration which writes all request logging from the
 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'
@@ -321,8 +352,6 @@ This logging configuration does the following things:
 * 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.,
@@ -390,20 +419,30 @@ use a different configuration process, you can use any other callable
 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:
 
-.. 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.
+.. snippet::
+    :filename: settings.py
+
+    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
 ===========================
@@ -652,13 +691,25 @@ logging module.
 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:
 
-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``.
+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``:
+
+* 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.