Ведение журнала

Участники процесса

Настройка ведения журнала Python состоит из четырёх частей:

• Журнализаторы
• Обработчики
• Фильтры
• Форматизаторы

AdminEmailHandler

В контексте безопасности стоит упомянуть встроенный AdminEmailHandler. Если его опция include_html включена, электронное сообщение, которое он отправляет, будет содержать полную трассировку стека, с именами и значениями локальных переменных на каждом уровне стека, а также значениями ваших настроек Django (другими словами, тот же уровень подробностей, что и на веб-странице, когда DEBUG установлен в True).

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

Примеры

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

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

import os

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "WARNING",
    },
}

Эта конфигурация настраивает родительский root логгер на отправку сообщений с уровнем WARNING и выше в обработчик консоли. Изменив уровень на INFO или DEBUG, вы можете отображать больше сообщений. Это может быть полезно во время разработки.

Далее мы можем добавить более точное журналирование. Вот пример того, как сделать систему журналирования для вывода больше сообщений только из логгера с именем django:

import os

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "WARNING",
    },
    "loggers": {
        "django": {
            "handlers": ["console"],
            "level": os.getenv("DJANGO_LOG_LEVEL", "INFO"),
            "propagate": False,
        },
    },
}

По умолчанию эта конфигурация отправляет сообщения из логгера django уровня INFO или выше в консоль. Это тот же уровень, что и в стандартной конфигурации Django, за исключением того, что стандартная конфигурация отображает записи журнала только при DEBUG=True. Django не регистрирует много сообщений уровня INFO. Однако с этой конфигурацией вы также можете установить переменную среды DJANGO_LOG_LEVEL=DEBUG, чтобы увидеть весь отладочный журнал Django, который очень подробный, поскольку включает все запросы к базе данных.

Вы не обязаны регистрировать в консоли. Вот конфигурация, которая записывает все журналы из логгера с именем django в локальный файл:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "file": {
            "level": "DEBUG",
            "class": "logging.FileHandler",
            "filename": "/path/to/django/debug.log",
        },
    },
    "loggers": {
        "django": {
            "handlers": ["file"],
            "level": "DEBUG",
            "propagate": True,
        },
    },
}

Если вы используете этот пример, убедитесь, что изменили путь 'filename' на расположение, доступное для записи пользователем, который запускает приложение Django.

Наконец, вот пример довольно сложной настройки журналирования:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "verbose": {
            "format": "{levelname} {asctime} {module} {process:d} {thread:d} {message}",
            "style": "{",
        },
        "simple": {
            "format": "{levelname} {message}",
            "style": "{",
        },
    },
    "filters": {
        "special": {
            "()": "project.logging.SpecialFilter",
            "foo": "bar",
        },
        "require_debug_true": {
            "()": "django.utils.log.RequireDebugTrue",
        },
    },
    "handlers": {
        "console": {
            "level": "INFO",
            "filters": ["require_debug_true"],
            "class": "logging.StreamHandler",
            "formatter": "simple",
        },
        "mail_admins": {
            "level": "ERROR",
            "class": "django.utils.log.AdminEmailHandler",
            "filters": ["special"],
        },
    },
    "loggers": {
        "django": {
            "handlers": ["console"],
            "propagate": True,
        },
        "django.request": {
            "handlers": ["mail_admins"],
            "level": "ERROR",
            "propagate": False,
        },
        "myproject.custom": {
            "handlers": ["console", "mail_admins"],
            "level": "INFO",
            "filters": ["special"],
        },
    },
}

Эта конфигурация журналирования выполняет следующие действия:

• Определяет конфигурацию как в формате 'dictConfig version 1'. В настоящее время это единственный поддерживаемый формат dictConfig.

• Определяет два форматировщика:

  • simple, который выводит имя уровня журнала (например, DEBUG) и сообщение журнала.

    Строка format — это обычная строка форматирования Python, описывающая детали, которые должны выводиться в каждой строке журнала. Полный список деталей, которые можно вывести, можно найти в Объектах форматировщика.

  • verbose, который выводит имя уровня журнала, сообщение журнала, а также время, процесс, поток и модуль, генерирующие сообщение журнала.

• Определяет два фильтра:

  • project.logging.SpecialFilter, используя псевдоним special. Если этому фильтру требуются дополнительные аргументы, они могут быть предоставлены как дополнительные ключи в словаре конфигурации фильтра. В этом случае аргументу foo будет присвоено значение bar при создании экземпляра SpecialFilter.
  • django.utils.log.RequireDebugTrue, который пропускает записи, когда DEBUG равен True.

• Определяет два обработчика:

  • console, StreamHandler, который выводит любое сообщение уровня INFO (или выше) в sys.stderr. Этот обработчик использует формат вывода simple.
  • mail_admins, AdminEmailHandler, который отправляет электронное письмо с любым сообщением уровня ERROR (или выше) на адрес сайта ADMINS. Этот обработчик использует фильтр special.

• Настраивает три логгера:

  • django, который передает все сообщения в обработчик console.
  • django.request, который передает все сообщения уровня ERROR в обработчик mail_admins. Кроме того, этот логгер помечен как не передающий сообщения. Это означает, что сообщения журнала, записанные в django.request, не будут обрабатываться логгером django.
  • myproject.custom, который передает все сообщения уровня INFO или выше, которые также проходят фильтр special, в два обработчика — console и mail_admins. Это означает, что все сообщения уровня INFO (или выше) будут выведены в консоль; сообщения уровня ERROR и CRITICAL также будут выведены по электронной почте.

Настройка журналирования вручную

Если вы не хотите использовать формат dictConfig Python для настройки логгера, вы можете указать свою собственную схему конфигурации.

Настройка LOGGING_CONFIG определяет вызываемый объект, который будет использоваться для настройки логгеров Django. По умолчанию он указывает на функцию Python logging.config.dictConfig(). Однако, если вы хотите использовать другой процесс конфигурации, вы можете использовать любой другой вызываемый объект, который принимает один аргумент. Содержимое LOGGING будет передано в качестве значения этого аргумента при настройке журналирования.

Отключение конфигурации журналирования

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

Установка LOGGING_CONFIG в значение None означает только то, что процесс автоматической настройки отключен, а не само журналирование. Если вы отключите процесс конфигурации, Django по-прежнему будет делать вызовы журналирования, возвращаясь к поведению, заданному по умолчанию.

Вот пример, который отключает конфигурацию журналирования Django и затем вручную настраивает журналирование:

LOGGING_CONFIG = None

import logging.config

logging.config.dictConfig(...)

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