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

Django предоставляет готовую к расширению конфигурацию логирования по умолчанию.

Выполнение базового вызова логирования

Для отправки сообщения об ошибке из вашего кода, необходимо сделать вызов логирования.

Сначала импортируйте библиотеку Python для логирования, а затем получите экземпляр логгера с помощью logging.getLogger(). Укажите getLogger() с именем для идентификации и записей, которые он генерирует. Хорошим вариантом является использование __name__ (подробнее об этом см. Использование именования логгеров ниже), которое предоставит имя текущего модуля Python в виде пути с точками:

import logging

logger = logging.getLogger(__name__)

Хорошей практикой является выполнение этого объявления на уровне модуля.

Затем в функции, например, в представлении, отправьте запись в логгер:

def some_view(request):
    ...
    if some_risky_state:
        logger.warning("Platform is running at risk")

При выполнении этого кода, LogRecord содержащий это сообщение, будет отправлен в логгер. Если вы используете стандартную конфигурацию логирования Django, сообщение будет отображаться в консоли.

Уровень WARNING, используемый в примере выше, является одним из нескольких уровней серьезности логирования: DEBUG, INFO, WARNING, ERROR, CRITICAL. Таким образом, другой пример может быть:

logger.critical("Payment system is not responding")

Настройка конфигурации логирования

Хотя конфигурация логирования Django работает «из коробки», вы можете контролировать, как ваши логи отправляются в различные места — в файлы, внешние сервисы, по электронной почте и т. д. — с помощью дополнительной настройки.

Вы можете настроить:

• отображение логгеров, чтобы определить, какие записи отправляются в какие обработчики
• обработчики, чтобы определить, что они делают с полученными записями
• фильтры, чтобы обеспечить дополнительный контроль над передачей записей и даже изменять записи на месте
• форматеры, чтобы преобразовать LogRecord объекты в строку или другую форму для использования человеком или другой системой

Существует несколько способов настройки логирования. В Django чаще всего используется настройка LOGGING. Настройка использует формат dictConfig и расширяет стандартную конфигурацию логирования.

См. Настройка логирования для объяснения того, как ваши пользовательские настройки объединяются со стандартными настройками Django.

См. Python logging documentation для получения подробной информации об других способах настройки логирования. Для простоты в этом документе будет рассмотрена только настройка через настройку LOGGING.

Базовая конфигурация логгера

При настройке логирования имеет смысл

Создать словарь логирования LOGGING

В вашем settings.py:

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

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

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

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

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"],
        },
    },
}

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

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

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

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

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")

и настроить отображения логгеров соответственно.

Использование иерархии логгеров и распространения

Именование логгеров иерархическое. my_app является родителем my_app.views, который является родителем my_app.views.private. Если не указано иное, отображения логгеров будут распространять обрабатываемые ими записи на своих родителей — запись от логгера в пространстве имен my_app.views.private будет обрабатываться отображением как для my_app, так и для my_app.views.

Для управления этим поведением установите ключ распространения в отображениях, которые вы определяете:

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

propagate по умолчанию True. В этом примере логи от my_app.views.private не будут обрабатываться родителем, но логи от my_app.views будут.

Настройка адаптивного логирования

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

Вы можете настроить ведение журнала, чтобы предоставить вам необходимый уровень детализации, когда он вам нужен. Вместо того, чтобы вручную изменять конфигурацию для достижения этого, лучший способ — применить конфигурацию автоматически в зависимости от среды.

Например, вы можете установить переменную среды DJANGO_LOG_LEVEL соответствующим образом в средах разработки и подготовки, а затем использовать её в отображении логгера следующим образом:

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

- таким образом, если среда не указывает более низкий уровень журнала, эта конфигурация будет передавать только записи уровня серьезности WARNING и выше своему обработчику.

Другие параметры в конфигурации (например, level или formatter параметр обработчиков) можно аналогичным образом управлять.