Ticket #24361: dj-doc-logging.patch

docs/topics/logging.txt

@@ -219 +219 @@
 add to, or replace the existing configuration.
 
 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.  Alternatively you can redefine some or all
+of the loggers by setting ``disable_existing_loggers`` to ``False``.
+
+.. note::
+    There is a catch in the way the Python Logger class is implemented: Any
+    *disabled logger* defined by the Django's default logging configuration
+    is also not propagating events to its parent. If you want to build your
+    logging configuration from scratch, then it is not enough to set
+    ``disable_existing_loggers`` to ``True``.  Refer to
+    :ref:`disabling-logging-configuration` for an example.
 
 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
@@ -390 +398 @@
 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
 -------------------------------
 
@@ -405 +415 @@
     calls, falling back to whatever default logging behavior is
     defined.
 
+Here's an example how to make the logging system under Django to log
+everything to console without having the disabled (but still existing)
+loggers to swallow events.  You may want to activate this when using the
+``runserver``::
+
+    LOGGING_CONFIG = None
+    LOGGING = {
+        'version': 1,
+        'handlers': {
+            'console': {
+                'level': os.getenv('LOGLEVEL', 'INFO'),
+                'class': 'logging.StreamHandler',
+                'formatter': 'debugging',
+            },
+        },
+        'formatters': {
+            'debugging': {
+                'format': '%(name)s %(levelname)s %(module)s:%(lineno)s: %(message)s'
+            },
+        },
+        # A catch-all root logger.
+        'root': {
+            'handlers': ['console'],
+            'level': 'DEBUG',
+        },
+    }
+
+    import logging.config
+    logging.config.dictConfig(LOGGING)
+
+By setting the ``LOGLEVEL=DEBUG`` environment variable, you'll see the
+database queries among other stuff.
+
+
 Django's logging extensions
 ===========================