Как настроить и использовать логирование

Создать словарь LOGGING

В файле settings.py:

LOGGING = {
    "version": 1,  # the dictConfig format version
    "disable_existing_loggers": False,  # retain the default loggers
}

Почти всегда имеет смысл сохранить и расширить конфигурацию логирования по умолчанию, установив disable_existing_loggers в значение False.

Настроить обработчик

В этом примере настраивается один обработчик с именем file, который использует класс Python FileHandler, чтобы сохранять в файл general.log (в корневом каталоге проекта) журналы уровня DEBUG и выше:

LOGGING = {
    # ...
    "handlers": {
        "file": {
            "class": "logging.FileHandler",
            "filename": "general.log",
        },
    },
}

Для разных классов обработчиков требуются разные параметры конфигурации. Сведения о доступных классах обработчиков см. в описании AdminEmailHandler, предоставляемого Django, и различных handler classes, предоставляемых Python.

Уровни логирования также можно задавать для обработчиков (по умолчанию они принимают сообщения журнала любого уровня). Если использовать пример выше и добавить:

{
    "class": "logging.FileHandler",
    "filename": "general.log",
    "level": "DEBUG",
}

то будет определена конфигурация обработчика, принимающего только записи уровня DEBUG и выше.

Настроить сопоставление логгера

Чтобы отправлять записи этому обработчику, настройте сопоставление логгера, использующее его, например:

LOGGING = {
    # ...
    "loggers": {
        "": {
            "level": "DEBUG",
            "handlers": ["file"],
        },
    },
}

Имя сопоставления определяет, какие записи журнала оно будет обрабатывать. Эта конфигурация ('') не имеет имени. Это означает, что она будет обрабатывать записи всех логгеров (о том, как использовать имя сопоставления для определения логгеров, записи которых оно будет обрабатывать, см. ниже в разделе Используйте пространства имён логгеров).

Оно будет передавать обработчику с именем file сообщения уровня DEBUG и выше.

Обратите внимание, что логгер может передавать сообщения нескольким обработчикам, поэтому связь между логгерами и обработчиками является «многие ко многим».

Если выполнить в коде:

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

это сообщение появится в файле general.log в корневом каталоге проекта.

Настроить форматировщик

По умолчанию конечный вывод журнала содержит только текст сообщения из каждого log record. Если нужно включить дополнительные данные, используйте форматировщик. Сначала задайте имена и определите форматировщики — в этом примере определяются форматировщики с именами verbose и simple:

LOGGING = {
    # ...
    "formatters": {
        "verbose": {
            "format": "{name} {levelname} {asctime} {module} {process:d} {thread:d} {message}",
            "style": "{",
        },
        "simple": {
            "format": "{levelname} {message}",
            "style": "{",
        },
    },
}

Ключевое слово style позволяет указать { для форматирования с помощью str.format() или $ для форматирования с помощью string.Template; по умолчанию используется $.

Доступные для включения атрибуты LogRecord перечислены в разделе Атрибуты LogRecord.

Чтобы применить форматировщик к обработчику, добавьте в словарь обработчика запись formatter со ссылкой на форматировщик по имени, например:

"handlers": {
    "file": {
        "class": "logging.FileHandler",
        "filename": "general.log",
        "formatter": "verbose",
    },
}

Используйте пространства имён логгеров

Конфигурация логирования без имени '' перехватывает журналы любого приложения Python. Именованная конфигурация логирования перехватывает журналы только от логгеров с соответствующими именами.

Пространство имён экземпляра логгера задаётся с помощью getLogger(). Например, в views.py из my_app:

logger = logging.getLogger(__name__)

создаст логгер в пространстве имён my_app.views. __name__ позволяет автоматически упорядочивать сообщения журнала по их происхождению в приложениях вашего проекта. Это также гарантирует, что имена не будут конфликтовать.

Сопоставление логгера с именем my_app.views перехватит записи от этого логгера:

LOGGING = {
    # ...
    "loggers": {
        "my_app.views": {...},
    },
}

Сопоставление логгера с именем my_app будет менее строгим и перехватит записи от логгеров в любом месте пространства имён my_app (включая my_app.views, my_app.utils и т. д.):

LOGGING = {
    # ...
    "loggers": {
        "my_app": {...},
    },
}

Также можно явно задать пространство имён логгера:

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

и соответствующим образом настроить сопоставления логгеров.

LOGGING = {
    # ...
    "loggers": {
        "my_app": {
            # ...
        },
        "my_app.views": {
            # ...
        },
        "my_app.views.private": {
            # ...
            "propagate": False,
        },
    },
}