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

Условия ведения журнала по умолчанию

Полный набор условий ведения журнала по умолчанию:

Если DEBUG имеет значение True:

• Логгер django отправляет сообщения из иерархии django (кроме django.server) уровня INFO и выше в консоль.

Если DEBUG имеет значение False:

• Логгер django отправляет сообщения из иерархии django (кроме django.server) уровня ERROR или CRITICAL в AdminEmailHandler.

Независимо от значения DEBUG:

• Логгер django.server отправляет сообщения уровня INFO и выше в консоль.

Все логгеры, кроме django.server, передают сообщения родительским логгерам вплоть до корневого логгера django. Обработчики console и mail_admins привязаны к корневому логгеру и обеспечивают описанное выше поведение.

Собственные настройки Python по умолчанию отправляют записи уровня WARNING и выше в консоль.

Определение ведения журнала по умолчанию

Конфигурация ведения журнала Django по умолчанию наследует настройки Python. Она доступна как django.utils.log.DEFAULT_LOGGING и определена в файле django/utils/log.py:

{
    "version": 1,
    "disable_existing_loggers": False,
    "filters": {
        "require_debug_false": {
            "()": "django.utils.log.RequireDebugFalse",
        },
        "require_debug_true": {
            "()": "django.utils.log.RequireDebugTrue",
        },
    },
    "formatters": {
        "django.server": {
            "()": "django.utils.log.ServerFormatter",
            "format": "[{server_time}] {message}",
            "style": "{",
        }
    },
    "handlers": {
        "console": {
            "level": "INFO",
            "filters": ["require_debug_true"],
            "class": "logging.StreamHandler",
        },
        "django.server": {
            "level": "INFO",
            "class": "logging.StreamHandler",
            "formatter": "django.server",
        },
        "mail_admins": {
            "level": "ERROR",
            "filters": ["require_debug_false"],
            "class": "django.utils.log.AdminEmailHandler",
        },
    },
    "loggers": {
        "django": {
            "handlers": ["console", "mail_admins"],
            "level": "INFO",
        },
        "django.server": {
            "handlers": ["django.server"],
            "level": "INFO",
            "propagate": False,
        },
    },
}

О том, как дополнить эту конфигурацию ведения журнала по умолчанию или заменить её, см. раздел Настройка ведения журнала.

Логгеры

Django предоставляет несколько встроенных логгеров.

LOGGING = {
    # ...
    "handlers": {
        "null": {
            "class": "logging.NullHandler",
        },
    },
    "loggers": {
        "django.security.DisallowedHost": {
            "handlers": ["null"],
            "propagate": False,
        },
    },
    # ...
}

Обработчики

Помимо those provided by the Python logging module, модуль ведения журнала Python, Django предоставляет один обработчик журнала.

class AdminEmailHandler(include_html=False, email_backend=None, reporter_class=None) [исходный код]

Этот обработчик отправляет письмо администраторам сайта, указанным в настройке ADMINS, для каждого полученного сообщения журнала.

Если запись журнала содержит атрибут request, в письмо будут включены полные сведения о запросе. Если IP-адрес клиента указан в настройке INTERNAL_IPS, тема письма будет содержать фразу «внутренний IP-адрес»; в противном случае — «ВНЕШНИЙ IP-АДРЕС».

Если запись журнала содержит информацию о трассировке стека, она будет включена в письмо.

Аргумент include_html класса AdminEmailHandler позволяет управлять тем, будет ли к письму с трассировкой добавлено HTML-вложение с полным содержимым отладочной веб-страницы, которая была бы создана, если бы настройка DEBUG имела значение True. Чтобы задать это значение в конфигурации, укажите его в определении обработчика django.utils.log.AdminEmailHandler, например:

"handlers": {
    "mail_admins": {
        "level": "ERROR",
        "class": "django.utils.log.AdminEmailHandler",
        "include_html": True,
    },
}

При использовании AdminEmailHandler учитывайте последствия ведения журнала для безопасности.

С помощью аргумента email_backend класса AdminEmailHandler можно переопределить почтовый бэкенд, используемый обработчиком, например:

"handlers": {
    "mail_admins": {
        "level": "ERROR",
        "class": "django.utils.log.AdminEmailHandler",
        "email_backend": "django.core.mail.backends.filebased.EmailBackend",
    },
}

По умолчанию используется экземпляр почтового бэкенда, указанного в настройке EMAIL_BACKEND.

Аргумент reporter_class класса AdminEmailHandler позволяет указать подкласс django.views.debug.ExceptionReporter для настройки текста трассировки стека, отправляемого в теле письма. Укажите строковый путь импорта к нужному классу, например:

"handlers": {
    "mail_admins": {
        "level": "ERROR",
        "class": "django.utils.log.AdminEmailHandler",
        "include_html": True,
        "reporter_class": "somepackage.error_reporter.CustomErrorReporter",
    },
}

send_mail(subject, message, *args, **kwargs) [исходный код]

Отправляет письма администраторам. Чтобы настроить это поведение, можно создать подкласс AdminEmailHandler и переопределить этот метод.

Фильтры

Помимо фильтров модуля ведения журнала Python, Django предоставляет несколько собственных фильтров журнала.

class CallbackFilter(callback) [исходный код]

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

Например, чтобы исключить из писем администраторам ошибки UnreadablePostError (возникающие, когда пользователь отменяет загрузку), создайте функцию фильтрации:

from django.http import UnreadablePostError


def skip_unreadable_post(record):
    if record.exc_info:
        exc_type, exc_value = record.exc_info[:2]
        if isinstance(exc_value, UnreadablePostError):
            return False
    return True

а затем добавьте её в конфигурацию ведения журнала:

LOGGING = {
    # ...
    "filters": {
        "skip_unreadable_posts": {
            "()": "django.utils.log.CallbackFilter",
            "callback": skip_unreadable_post,
        },
    },
    "handlers": {
        "mail_admins": {
            "level": "ERROR",
            "filters": ["skip_unreadable_posts"],
            "class": "django.utils.log.AdminEmailHandler",
        },
    },
    # ...
}

class RequireDebugFalse [исходный код]

Этот фильтр пропускает записи, только если settings.DEBUG имеет значение False.

В конфигурации LOGGING по умолчанию этот фильтр используется следующим образом, чтобы гарантировать, что AdminEmailHandler отправляет администраторам письма об ошибках только тогда, когда DEBUG имеет значение False:

LOGGING = {
    # ...
    "filters": {
        "require_debug_false": {
            "()": "django.utils.log.RequireDebugFalse",
        },
    },
    "handlers": {
        "mail_admins": {
            "level": "ERROR",
            "filters": ["require_debug_false"],
            "class": "django.utils.log.AdminEmailHandler",
        },
    },
    # ...
}

class RequireDebugTrue [исходный код]

Этот фильтр похож на RequireDebugFalse, но пропускает записи только тогда, когда DEBUG имеет значение True.