diff options
author | Ben Li-Sauerwine <bsauerwine@gmail.com> | 2020-03-17 06:51:05 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-03-17 11:51:05 +0100 |
commit | fc84848cd9509409e420b21b6db697f22f2c82a4 (patch) | |
tree | 404f3901e2770f897ca8b424d51ff04ea876ffce /docs/topics/logging.txt | |
parent | 0538da08c576a5528312ade546c2f7c63489b811 (diff) | |
download | django-fc84848cd9509409e420b21b6db697f22f2c82a4.tar.gz |
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>
Diffstat (limited to 'docs/topics/logging.txt')
-rw-r--r-- | docs/topics/logging.txt | 80 |
1 files changed, 57 insertions, 23 deletions
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,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 |