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

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 параметр обработчиков) могут быть аналогичным образом управляемы.