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

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

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

Когда 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,
        },
    },
    # ...
}

Обработчики¶

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

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

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

Если запись журнала содержит атрибут request, в письмо будет включена полная информация о запросе. Тема письма будет включать фразу «internal IP», если IP-адрес клиента находится в настройках INTERNAL_IPS; если нет, она будет включать «EXTERNAL IP».

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

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

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

Будьте внимательны к security implications of logging при использовании AdminEmailHandler.

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

"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 и переопределить этот метод.

Фильтры¶

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

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.