Skip to content

Commit

Permalink
[3.0.x] Made logging config examples more accessible.
Browse files Browse the repository at this point in the history
- 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>
Backport of fc84848 from master
  • Loading branch information
theGOTOguy authored and carltongibson committed Mar 17, 2020
1 parent 725d7c2 commit 2f5c35c
Showing 1 changed file with 57 additions and 23 deletions.
80 changes: 57 additions & 23 deletions docs/topics/logging.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 2f5c35c

Please sign in to comment.