Viewing github.com/django/django-stable-4.1.x/docs/howto/logging.txt

```
.. _logging-how-to:
```
```
================================
```
```
How to configure and use logging
```
```
================================
```
```
.. seealso::
```

    * :ref:`Django logging reference <logging-ref>`

    * :ref:`Django logging overview <logging-explanation>`

Django provides a working :ref:`default logging configuration

<default-logging-configuration>` that is readily extended.

```
Make a basic logging call
```
```
=========================
```

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`. Provide the ``getLogger()`` method with a

name to identify it and the records it emits. A good option is to use

``__name__`` (see :ref:`naming-loggers` below for more on this) which will

provide the name of the current Python module as a dotted path::

```
    import logging
```

    logger = logging.getLogger(__name__)

It's a good convention to perform this declaration at module level.

And then in a function, for example in a view, send a record to the logger::

```
    def some_view(request):
```
```
        ...
```
```
        if some_risky_state:
```

            logger.warning('Platform is running at risk')

When this code is executed, a :py:class:`~logging.LogRecord` containing that

message will be sent to the logger. If you're using Django's default logging

configuration, the message 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')

```
.. important::
```

    Records with a level lower than ``WARNING`` will not appear in the console

    by default. Changing this behavior requires additional configuration.

```
Customize logging configuration
```
```
===============================
```

Although Django's logging configuration works out of the box, you can control

exactly how your logs are sent to various destinations - to log files, external

services, email and so on - with some additional configuration.

```
You can configure:
```

* logger mappings, to determine which records are sent to which handlers

* handlers, to determine what they do with the records they receive

* filters, to provide additional control over the transfer of records, and

```
  even modify records in-place
```

* formatters, to convert :class:`~logging.LogRecord` objects to a string or

  other form for consumption by human beings or another system

There are various ways of configuring logging. In Django, the

:setting:`LOGGING` setting is most commonly used. The setting uses the

:ref:`dictConfig format <logging-config-dictschema>`, and extends the

:ref:`default logging configuration <default-logging-definition>`.

See :ref:`configuring-logging` for an explanation of how your custom settings

```
are merged with Django's defaults.
```

See the :mod:`Python logging documentation <python:logging.config>` for

details of other ways of configuring logging. For the sake of simplicity, this

documentation will only consider configuration via the ``LOGGING`` setting.

```
.. _basic-logger-configuration:
```
```
Basic logging configuration
```
```
---------------------------
```

When configuring logging, it makes sense to

```
Create a ``LOGGING`` dictionary
```
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
```
```
In your ``settings.py``::
```
```
    LOGGING = {
```

        'version': 1,                       # the dictConfig format version

        'disable_existing_loggers': False,  # retain the default loggers

```
    }
```

It nearly always makes sense to retain and extend the default logging

configuration by setting ``disable_existing_loggers`` to ``False``.

```
Configure a handler
```
```
~~~~~~~~~~~~~~~~~~~
```

This example configures a single handler named ``file``, that uses Python's

:class:`~logging.FileHandler` to save logs of level ``DEBUG`` and higher to the

file ``general.log`` (at the project root):

```
.. code-block:: python
```
```
    :emphasize-lines: 3-8
```
```
    LOGGING = {
```
```
        [...]
```
```
        'handlers': {
```
```
            'file': {
```

                'class': 'logging.FileHandler',

                'filename': 'general.log',

```
            },
```
```
        },
```
```
    }
```

Different handler classes take different configuration options. For more

information on available handler classes, see the

:class:`~django.utils.log.AdminEmailHandler` provided by Django and the various

:py:mod:`handler classes <logging.handlers>` provided by Python.

Logging levels can also be set on the handlers (by default, they accept log

messages of all levels). Using the example above, adding:

```
.. code-block:: python
```
```
    :emphasize-lines: 4
```
```
    {
```

        'class': 'logging.FileHandler',

```
        'filename': 'general.log',
```
```
        'level': 'DEBUG',
```
```
    }
```

would define a handler configuration that only accepts records of level

```
``DEBUG`` and higher.
```
```
Configure a logger mapping
```
```
~~~~~~~~~~~~~~~~~~~~~~~~~~
```

To send records to this handler, configure a logger mapping to use it for

```
example:
```
```
.. code-block:: python
```
```
    :emphasize-lines: 3-8
```
```
    LOGGING = {
```
```
        [...]
```
```
        'loggers': {
```
```
            '': {
```
```
                'level': 'DEBUG',
```
```
                'handlers': ['file'],
```
```
            },
```
```
        },
```
```
    }
```

The mapping's name determines which log records it will process. This

configuration (``''``) is *unnamed*. That means that it will process records

from *all* loggers (see :ref:`naming-loggers` below on how to use the mapping

name to determine the loggers for which it will process records).

It will forward messages of levels ``DEBUG`` and higher to the handler named

```
``file``.
```

Note that a logger can forward messages to multiple handlers, so the relation

between loggers and handlers is many-to-many.

```
If you execute::
```

    logger.debug('Attempting to connect to API')

in your code, you will find that message in the file ``general.log`` in the

```
root of the project.
```
```
Configure a formatter
```
```
~~~~~~~~~~~~~~~~~~~~~
```

By default, the final log output contains the message part of each :class:`log

record <logging.LogRecord>`. Use a formatter if you want to include additional

data. First name and define your formatters - this example defines

formatters named ``verbose`` and ``simple``:

```
.. code-block:: python
```
```
    :emphasize-lines: 3-12
```
```
    LOGGING = {
```
```
        [...]
```
```
        'formatters': {
```
```
            'verbose': {
```

                'format': '{name} {levelname} {asctime} {module} {process:d} {thread:d} {message}',

```
                'style': '{',
```
```
            },
```
```
            'simple': {
```

                'format': '{levelname} {message}',

```
                'style': '{',
```
```
            },
```
```
        },
```
```
    }
```

The ``style`` keyword allows you to specify ``{`` for :meth:`str.format` or

``$`` for :class:`string.Template` formatting; the default is ``$``.

See :ref:`logrecord-attributes` for the :class:`~logging.LogRecord` attributes

```
you can include.
```

To apply a formatter to a handler, add a ``formatter`` entry to the handler's

dictionary referring to the formatter by name, for example:

```
.. code-block:: python
```
```
    :emphasize-lines: 5
```
```
    'handlers': {
```
```
        'file': {
```

            'class': 'logging.FileHandler',

```
            'filename': 'general.log',
```
```
            'formatter': 'verbose',
```
```
        },
```
```
    },
```
```
.. _naming-loggers:
```
```
Use logger namespacing
```
```
~~~~~~~~~~~~~~~~~~~~~~
```

The unnamed logging configuration ``''`` captures logs from any Python

application. A named logging configuration will capture logs only from loggers

```
with matching names.
```

The namespace of a logger instance is defined using

:py:func:`~logging.getLogger`. For example in ``views.py`` of ``my_app``::

    logger = logging.getLogger(__name__)

will create a logger in the ``my_app.views`` namespace. ``__name__`` allows you

to organize log messages according to their provenance within your project's

applications automatically. It also ensures that you will not experience name

```
collisions.
```

A logger mapping named ``my_app.views`` will capture records from this logger:

```
.. code-block:: python
```
```
    :emphasize-lines: 4
```
```
    LOGGING = {
```
```
        [...]
```
```
        'loggers': {
```
```
            'my_app.views': {
```
```
                ...
```
```
            },
```
```
        },
```
```
    }
```

A logger mapping named ``my_app`` will be more permissive, capturing records

from loggers anywhere within the ``my_app`` namespace (including

``my_app.views``, ``my_app.utils``, and so on):

```
.. code-block:: python
```
```
    :emphasize-lines: 4
```
```
    LOGGING = {
```
```
        [...]
```
```
        'loggers': {
```
```
            'my_app': {
```
```
                ...
```
```
            },
```
```
        },
```
```
    }
```

You can also define logger namespacing explicitly::

    logger = logging.getLogger('project.payment')

and set up logger mappings accordingly.

```
.. _naming-loggers-hierarchy:
```

Using logger hierarchies and propagation

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Logger naming is *hierarchical*. ``my_app`` is the parent of ``my_app.views``,

which is the parent of ``my_app.views.private``. Unless specified otherwise,

logger mappings will propagate the records they process to their parents - a

record from a logger in the ``my_app.views.private`` namespace will be handled

by a mapping for both ``my_app`` and ``my_app.views``.

To manage this behavior, set the propagation key on the mappings you define::

```
    LOGGING = {
```
```
        [...]
```
```
        'loggers': {
```
```
            'my_app': {
```
```
                [...]
```
```
            },
```
```
            'my_app.views': {
```
```
                [...]
```
```
            },
```
```
            'my_app.views.private': {
```
```
                [...]
```
```
                'propagate': False,
```
```
            },
```
```
        },
```
```
    }
```

``propagate`` defaults to ``True``. In this example, the logs from

``my_app.views.private`` will not be handled by the parent, but logs from

```
``my_app.views`` will.
```
```
Configure responsive logging
```
```
----------------------------
```

Logging is most useful when it contains as much information as possible, but

not information that you don't need - and how much you need depends upon what

you're doing. When you're debugging, you need a level of information that would

be excessive and unhelpful if you had to deal with it in production.

You can configure logging to provide you with the level of detail you need,

when you need it. Rather than manually change configuration to achieve this, a

better way is to apply configuration automatically according to the

```
environment.
```

For example, you could set an environment variable ``DJANGO_LOG_LEVEL``

appropriately in your development and staging environments, and make use of it

```
in a logger mapping thus::
```

    'level': os.getenv('DJANGO_LOG_LEVEL', 'WARNING')

\- so that unless the environment specifies a lower log level, this

configuration will only forward records of severity ``WARNING`` and above to

```
its handler.
```

Other options in the configuration (such as the ``level`` or ``formatter``

option of handlers) can be similarly managed.