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

Основные компоненты

Конфигурация ведения журнала в 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 версии 1». На данный момент это единственная версия формата dictConfig.

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

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

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

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

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

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

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

  • console — StreamHandler, который выводит в sys.stderr все сообщения уровня INFO или выше. Этот обработчик использует формат вывода simple.
  • mail_admins — AdminEmailHandler, который отправляет по электронной почте администраторам сайта ADMINS все сообщения уровня ERROR или выше. Этот обработчик использует фильтр 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(...)

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