Refs #32880 -- Improved some how-to notes in logging topic.

1 files changed, 53 insertions, 13 deletions

diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt
index e8c4b48e6a..5c0be8950b 100644
--- a/docs/topics/logging.txt
+++ b/docs/topics/logging.txt
@@ -28,8 +28,8 @@ A Python logging configuration consists of four parts:
 Loggers
 ~~~~~~~
 
-A logger is the entry point into the logging system. Each logger is
-a named bucket to which messages can be written for processing.
+A *logger* is the entry point into the logging system. Each logger is a named
+bucket to which messages can be written for processing.
 
 A logger is configured to have a *log level*. This log level describes
 the severity of the messages that the logger will handle. Python
@@ -117,27 +117,67 @@ of a Python formatting string containing
 :ref:`LogRecord attributes <python:logrecord-attributes>`; however,
 you can also write custom formatters to implement specific formatting behavior.
 
+.. _logging-how-to:
+
 How to use logging
 ==================
 
-Once you have configured your loggers, handlers, filters and
-formatters, you need to place logging calls into your code. Using the
-logging framework works like this::
+Django provides a :ref:`default logging configuration
+<default-logging-configuration>`, that for example generates the messages that
+appear in the console when using the :djadmin:`runserver`.
+
+Make a basic logging call
+-------------------------
+
+Python programmers will often use ``print()`` in their code as a quick and
+convenient debugging tool. Using the logging framework is only a little more
+effort than that, but it's much more elegant and flexible. As well as being
+useful for debugging, logging can also provide you with more - and better
+structured - information about the state and health of your application.
+
+To send a log message from within your code, you place a logging call into it.
+
+.. admonition:: Don't be tempted to use logging calls in ``settings.py``
+
+    The way that Django logging is configured as part of the ``setup()``
+    function means that logging calls placed in ``settings.py`` may not work as
+    expected, because *logging will not be set up at that point*. To explore
+    logging, use a view function as suggested in the example below.
+
+First, import the Python logging library, and then obtain a logger instance
+with :py:func:`logging.getLogger`. The ``getLogger()`` method must be provided
+with a name. A good option is to use ``__name__``, which will provide the name
+of the current Python module (see :ref:`naming-loggers` for use of explicit
+naming)::
 
-    # import the logging library
     import logging
 
-    # Get an instance of a logger
     logger = logging.getLogger(__name__)
 
-    def my_view(request, arg1, arg):
+And then in a function, for example in a view, send a message to the logger::
+
+    def some_view(request):
         ...
-        if bad_mojo:
-            # Log an error message
-            logger.error('Something went wrong!')
+        if some_risky_state:
+            logger.warning('Platform is running at risk')
+
+When this code is executed, that message will be sent to the logger (and if
+you're using Django's default logging configuration, it will appear in the
+console).
+
+The ``WARNING`` level used in the example above is one of several
+:ref:`logging severity levels <topic-logging-parts-loggers>`: ``DEBUG``,
+``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``. So, another example might be::
+
+    logger.critical('Payment system is not responding')
+
+The default logging configuration, which Django inherits from the Python
+logging module, prints all messages of level ``WARNING`` and higher to the
+console. Django's own defaults will *not* pass ``INFO`` or lower severity
+messages from applications other than Django itself to the console - that will
+need to be configured explicitly.
 
-And that's it! Every time the ``bad_mojo`` condition is activated, an
-error log record will be written.
+.. _naming-loggers:
 
 Naming loggers
 --------------