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

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, который использует обработчик Python FileHandler для сохранения журналов уровня 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 обработчиков) могут быть аналогично управляемы.