记录¶

玩家的演员¶

Python日志记录配置包括四个部分：

• 记录器

• 处理程序

• 过滤器

• 格式化

命名记录器¶

对 logging.getLogger() 的调用获得（如果必要的话）创建记录器的实例。日志记录器实例由名称标识。此名称用于标识记录器以进行配置。

按照惯例，记录器名称通常是 __name__，包含记录器的python模块的名称。这允许您基于每个模块过滤和处理日志记录调用。但是，如果您有其他方式组织记录消息，您可以提供任何点分隔的名称来标识记录器:

# Get an instance of a specific named logger
logger = logging.getLogger('project.interesting.stuff')

记录器名称的虚线路径定义层次结构。 project.interesting 记录器被认为是 project.interesting.stuff 记录器的父节点； project 记录器是 project.interesting 记录器的父级。

为什么层次结构很重要？好吧，因为记录器可以设置为 propagate，他们的记录调用到他们的父母。这样，您可以在记录器树的根目录中定义一组处理程序，并捕获记录器子树中的所有日志记录调用。在 project 命名空间中定义的日志处理程序将捕获在 project.interesting 和 project.interesting.stuff 日志记录器上发出的所有日志消息。

这种传播可以在每个记录器的基础上进行控制。如果不想将特定的记录器传播到其父节点，则可以关闭此行为。

记录呼叫¶

记录器实例包含每个默认日志级别的条目方法：

• logger.debug()

• logger.info()

• logger.warning()

• logger.error()

• logger.critical()

还有两个其他日志记录可用：

• logger.log()：手动发出具有特定日志级别的日志记录消息。

• logger.exception()：创建包装当前异常堆栈帧的 ERROR 级别日志记录消息。

例子¶

dictConfig格式 的完整文档是有关日志配置字典的最佳信息来源。然而，给你一个可能的味道，这里有几个例子。

首先，这里有一个简单的配置，将所有日志记录从 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应用程序的用户可写入的位置。

第二，这里有一个例子，让日志系统打印Django的日志到控制台。它可能在地方发展中有用。

默认情况下，此配置仅向控制台发送级别 INFO 或更高级别的消息（与Django的默认日志记录配置相同，除非默认值仅在 DEBUG=True 时显示日志记录）。 Django不记录很多这样的消息。但是，使用此配置，您还可以设置环境变量 DJANGO_LOG_LEVEL=DEBUG 以查看Django的所有调试日志记录，这非常详细，因为它包括所有数据库查询:

import os

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django': {
            'handlers': ['console'],
            'level': os.getenv('DJANGO_LOG_LEVEL', 'INFO'),
        },
    },
}

最后，这里有一个相当复杂的日志设置的例子:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
        },
        'simple': {
            'format': '%(levelname)s %(message)s'
        },
    },
    '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格式化字符串，用于描述要在每个日志行上输出的详细信息。可以输出的详细信息的完整列表可以在 Formatter Objects 中找到。

  • verbose，它输出日志级别名称，日志消息，以及生成日志消息的时间，进程，线程和模块。

• 定义两个过滤器：

  • project.logging.SpecialFilter，使用别名 special。如果此过滤器需要其他参数，则它们可以作为过滤器配置字典中的附加键。在这种情况下，当实例化 SpecialFilter 时，参数 foo 将被赋予值 bar。

  • django.utils.log.RequireDebugTrue，当 DEBUG 为 True 时传递记录。

• 定义两个处理程序：

  • console，一个StreamHandler，它将打印任何 DEBUG （或更高）消息到stderr。此处理程序使用 simple 输出格式。

  • mail_admins，一个AdminEmailHandler，它将电子邮件任何 ERROR （或更高）消息到网站管理员。此处理程序使用 special 过滤器。

• 配置三个记录器：

  • django，它将所有消息传递给 console 处理程序。

  • django.request，它将所有 ERROR 消息传递给 mail_admins 处理程序。此外，此记录器被标记为 not 传播消息。这意味着写入 django.request 的日志消息不会被 django 记录器处理。

  • myproject.custom，它传递所有在 INFO 或更高的消息，也通过 special 过滤器到两个处理程序 - console 和 mail_admins。这意味着所有 INFO 级别消息（或更高级别）将被打印到控制台； ERROR 和 CRITICAL 消息也将通过电子邮件输出。

自定义日志配置¶

如果不想使用Python的dictConfig格式配置记录器，可以指定自己的配置方案。

LOGGING_CONFIG 设置定义将用于配置Django的记录器的可调用。默认情况下，它指向Python的 logging.config.dictConfig() 函数。但是，如果要使用不同的配置过程，可以使用任何其他可调用，只需要一个参数。当配置日志记录时，LOGGING 的内容将作为该参数的值提供。

禁用日志配置¶

如果您不想完全配置日志记录（或者您想使用自己的方法手动配置日志记录），您可以将 LOGGING_CONFIG 设置为 None。这将禁用 Django默认日志记录 的配置过程。这里有一个例子，禁用Django的日志配置，然后手动配置日志记录：

LOGGING_CONFIG = None

import logging.config
logging.config.dictConfig(...)

将 LOGGING_CONFIG 设置为 None 仅意味着禁用自动配置过程，而不是记录自身。如果禁用配置过程，Django仍将进行日志调用，回退到定义的任何默认日志记录行为。

记录器¶

Django提供了几个内置的记录器。

'handlers': {
    'null': {
        'class': 'logging.NullHandler',
    },
},
'loggers': {
    'django.security.DisallowedHost': {
        'handlers': ['null'],
        'propagate': False,
    },
},

处理程序¶

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

class AdminEmailHandler(include_html=False, email_backend=None)[源代码]¶

此处理程序向网站管理员发送电子邮件，以接收每个日志消息。

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

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

AdminEmailHandler 的 include_html 参数用于控制追溯电子邮件是否包括包含调试网页的完整内容的HTML附件，如果 DEBUG 是 True，则该附件将被产生。要在配置中设置此值，请将其包含在 django.utils.log.AdminEmailHandler 的处理程序定义中，如下所示：

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

请注意，此电子邮件的HTML版本包含完整的追溯，在堆栈的每个级别具有局部变量的名称和值，以及您的Django设置的值。此信息可能非常敏感，您可能不想通过电子邮件发送。考虑使用诸如 Sentry 之类的东西来获得两个世界中最好的 - 完整追踪的丰富信息以及 not 通过电子邮件发送信息的安全性。您还可以明确指定要从错误报告中滤除某些敏感信息 - 了解有关 Filtering error reports 的更多信息。

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

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

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

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

然后将其添加到您的日志记录配置：

'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 时向管理员发送错误电子邮件：

'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 时传递。