預設記錄條件¶

預設記錄條件的完整設定如下：

當 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 logging 模組提供的篩選器之外，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 時才會傳遞記錄。