diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt index 80348e360b..47a3c698d6 100644 --- a/docs/topics/logging.txt +++ b/docs/topics/logging.txt @@ -238,8 +238,73 @@ The full documentation for :ref:`dictConfig format ` 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': { + 'console': { + 'class': 'logging.StreamHandler', + }, + }, + 'root': { + 'handlers': ['console'], + 'level': 'WARNING', + }, + } + +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. + +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 + + import os + + LOGGING = { + 'version': 1, + 'disable_existing_loggers': False, + 'handlers': { + 'console': { + '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 @@ -266,37 +331,6 @@ First, here's a configuration which writes all 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 how to make the logging system print Django's -logging to the console. It may be useful during local 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: - -.. code-block:: python - :caption: settings.py - - import os - - LOGGING = { - 'version': 1, - '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: .. code-block:: python