2
0
Эх сурвалжийг харах

Made logging config examples more accessible.

- Show an initial example configuring the root logger to output to the console.
- Then add more logging from the `django` named logger.
- Then show the file and more complex examples.

Adjusted surrounding text for reading flow.

Co-authored-by: Carlton Gibson <carlton.gibson@noumenal.es>
Ben Li-Sauerwine 5 жил өмнө
parent
commit
fc84848cd9
1 өөрчлөгдсөн 57 нэмэгдсэн , 23 устгасан
  1. 57 23
      docs/topics/logging.txt

+ 57 - 23
docs/topics/logging.txt

@@ -238,43 +238,36 @@ The full documentation for :ref:`dictConfig format <logging-config-dictschema>`
 is the best source of information about logging configuration dictionaries.
 However, to give you a taste of what is possible, here are several examples.
 
-First, here's a configuration which writes all logging from the
-:ref:`django-logger` logger to a local file:
+To begin, here's a small configuration that will allow you to output all log
+messages to the console:
 
 .. code-block:: python
     :caption: settings.py
 
+    import os
+
     LOGGING = {
         'version': 1,
         'disable_existing_loggers': False,
         'handlers': {
-            'file': {
-                'level': 'DEBUG',
-                'class': 'logging.FileHandler',
-                'filename': '/path/to/django/debug.log',
+            'console': {
+                'class': 'logging.StreamHandler',
             },
         },
-        'loggers': {
-            'django': {
-                'handlers': ['file'],
-                'level': 'DEBUG',
-                'propagate': True,
-            },
+        'root': {
+            'handlers': ['console'],
+            'level': 'WARNING',
         },
     }
 
-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 how to make the logging system print Django's
-logging to the console. It may be useful during local development.
+This configures the parent ``root`` logger to send messages with the
+``WARNING`` level and higher to the console handler. By adjusting the level to
+``INFO`` or ``DEBUG`` you can display more messages. This may be useful during
+development.
 
-By default, this config only sends messages of level ``INFO`` or higher to the
-console (same as Django's default logging config, except that the default only
-displays log records when ``DEBUG=True``). Django does not log many such
-messages. With this config, however, you can also 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:
+Next we can add more fine-grained logging. Here's an example of how to make the
+logging system print more messages from just the :ref:`django-logger` named
+logger:
 
 .. code-block:: python
     :caption: settings.py
@@ -289,14 +282,55 @@ verbose as it includes all database queries:
                 'class': 'logging.StreamHandler',
             },
         },
+        'root': {
+            'handlers': ['console'],
+            'level': 'WARNING',
+        },
         'loggers': {
             'django': {
                 'handlers': ['console'],
                 'level': os.getenv('DJANGO_LOG_LEVEL', 'INFO'),
+                'propagate': False,
+            },
+        },
+    }
+
+By default, this config sends messages from the ``django`` logger of level
+``INFO`` or higher to the console. This is the same level as Django's default
+logging config, except that the default config only displays log records when
+``DEBUG=True``. Django does not log many such ``INFO`` level messages. With
+this config, however, you can also 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.
+
+You don't have to log to the console. Here's a configuration which writes all
+logging from the :ref:`django-logger` named logger to a local file:
+
+.. code-block:: python
+    :caption: settings.py
+
+    LOGGING = {
+        'version': 1,
+        'disable_existing_loggers': False,
+        'handlers': {
+            'file': {
+                'level': 'DEBUG',
+                'class': 'logging.FileHandler',
+                'filename': '/path/to/django/debug.log',
+            },
+        },
+        'loggers': {
+            'django': {
+                'handlers': ['file'],
+                'level': 'DEBUG',
+                'propagate': True,
             },
         },
     }
 
+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.
+
 Finally, here's an example of a fairly complex logging setup:
 
 .. code-block:: python