默认日志记录条件¶

完整的默认日志记录条件如下

当 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,
        },
    },
    # ...
}

处理程序¶

除了 Python logging 模块 提供的 那些 之外，Django 提供了一个日志处理程序。

class AdminEmailHandler(include_html=False, email_backend=None, reporter_class=None)¶

此处理程序为它接收的每条日志消息向网站 ADMINS 发送一封电子邮件。

如果日志记录包含 request 属性，则请求的完整详细信息将包含在电子邮件中。如果客户端的 IP 地址位于 INTERNAL_IPS 设置中，则电子邮件主题将包含短语“内部 IP”；如果不是，则它将包含“外部 IP”。

如果日志记录包含堆栈跟踪信息，则该堆栈跟踪将包含在电子邮件中。

AdminEmailHandler 的 include_html 参数用于控制回溯电子邮件是否包含一个 HTML 附件，其中包含如果 DEBUG 为 True，则会生成的调试网页的全部内容。要在配置中设置此值，请将其包含在 django.utils.log.AdminEmailHandler 的处理程序定义中，如下所示

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

使用 AdminEmailHandler 时，请注意 日志记录的安全影响。

通过设置 AdminEmailHandler 的 email_backend 参数，可以覆盖处理程序正在使用的 电子邮件后端，如下所示

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

默认情况下，将使用 EMAIL_BACKEND 中指定的电子邮件后端的实例。

AdminEmailHandler 的 reporter_class 参数允许提供一个 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 时才传递记录。