日志

参见

• 如何配置和使用日志
• Django logging reference

Python programmers will often use print() in their code as a quick and convenient debugging tool. Using the logging framework is only a little more effort than that, but it’s much more elegant and flexible. As well as being useful for debugging, logging can also provide you with more - and better structured - information about the state and health of your application.

概况

Django uses and extends Python’s builtin logging module to perform system logging. This module is discussed in detail in Python’s own documentation; this section provides a quick overview.

日志框架的组成元素

一份 Python logging 配置有下面四个部分组成：

• Loggers
• Handlers
• 过滤器
• Formatters

Loggers

A logger is the entry point into the logging system. Each logger is a named bucket to which messages can be written for processing.

logger 可以配置 日志级别。日志级别描述了由该 logger 处理的消息的严重性。Python 定义了下面几种日志级别：

• DEBUG：排查故障时使用的低级别系统信息
• INFO：一般的系统信息
• WARNING：描述系统发生了一些小问题的信息
• ERROR：描述系统发生了大问题的信息
• CRITICAL：描述系统发生严重问题的信息

每一条写入 logger 的消息都是一条 日志记录。每一条日志记录也包含 日志级别，代表对应消息的严重程度。日志记录还包含有用的元数据，来描述被记录了日志的事件细节，例如堆栈跟踪或者错误码。

当 logger 处理一条消息时，会将自己的日志级别和这条消息的日志级别做对比。如果消息的日志级别匹配或者高于 logger 的日志级别，它就会被进一步处理。否则这条消息就会被忽略掉。

当 logger 确定了一条消息需要处理之后，会把它传给 Handler。

Handlers

The handler is the engine that determines what happens to each message in a logger. It describes a particular logging behavior, such as writing a message to the screen, to a file, or to a network socket.

和 logger 一样，handler 也有日志级别的概念。如果一条日志记录的级别不匹配或者低于 handler 的日志级别，对应的消息会被 handler 忽略。

一个 logger 可以有多个 handler，每一个 handler 可以有不同的日志级别。这样就可以根据消息的重要性不同，来提供不同格式的输出。例如，你可以添加一个 handler 把 ERROR 和 CRITICAL 消息发到寻呼机，再添加另一个 handler 把所有的消息（包括 ERROR 和 CRITICAL 消息）保存到文件里以便日后分析。

过滤器

A filter is used to provide additional control over which log records are passed from logger to handler.

默认情况下，只要级别匹配，任何日志消息都会被处理。不过，也可以通过添加 filter 来给日志处理的过程增加额外条件。例如，可以添加一个 filter 只允许某个特定来源的 ERROR 消息输出。

Filter 还被用来在日志输出之前对日志记录做修改。例如，可以写一个 filter，当满足一定条件时，把日志记录从 ERROR 降到 WARNING 级别。

Filter 在 logger 和 handler 中都可以添加；多个 filter 可以链接起来使用，来做多重过滤操作。

Formatters

Ultimately, a log record needs to be rendered as text. Formatters describe the exact format of that text. A formatter usually consists of a Python formatting string containing LogRecord attributes; however, you can also write custom formatters to implement specific formatting behavior.

Security implications

The logging system handles potentially sensitive information. For example, the log record may contain information about a web request or a stack trace, while some of the data you collect in your own loggers may also have security implications. You need to be sure you know:

• 会收集什么信息
• where it will subsequently be stored
• how it will be transferred
• 谁可能访问它

To help control the collection of sensitive information, you can explicitly designate certain sensitive information to be filtered out of error reports — read more about how to filter error reports.

AdminEmailHandler

The built-in AdminEmailHandler deserves a mention in the context of security. If its include_html option is enabled, the email message it sends will contain a full traceback, with names and values of local variables at each level of the stack, plus the values of your Django settings (in other words, the same level of detail that is exposed in a web page when DEBUG is True).

It’s generally not considered a good idea to send such potentially sensitive information over email. Consider instead using one of the many third-party services to which detailed logs can be sent to get the best of multiple worlds — the rich information of full tracebacks, clear management of who is notified and has access to the information, and so on.

日志模块的配置

Python 的日志库提供了一些配置方法，可以使用编程接口或者配置文件。Django默认使用 dictConfig format。

In order to configure logging, you use LOGGING to define a dictionary of logging settings. These settings describe the loggers, handlers, filters and formatters that you want in your logging setup, and the log levels and other properties that you want those components to have.

默认情况下 LOGGING 配置和 Django 默认日志配置 按照下面的方式合并在一起：

如果 LOGGING dictConfig 中的 disable_existing_loggers 键被设置为 True （如果该键缺失，则为 dictConfig 默认值），则默认配置中的所有记录器都将被禁用。禁用的记录器与删除的记录器不同；记录器仍将存在，但会默默地丢弃任何记录到它的内容，甚至不会将条目传播到父记录仪。因此，你应该非常小心地使用 'disable_existing_loggers': True；这可能不是你想要的。相反，你可以将 disable_existing_loggers 设置为 False，然后重新定义一些或所有的默认日志记录器；或者你可以将 LOGGING_CONFIG 设置为 None，然后 自己处理日志配置。

logging 被配置成了 Django setup() 函数的一部分。因此，你可以确定的是，logger 一直都可以在项目代码里使用。

示例

dictConfig format 文档是获取日志配置细节的最好资料。不过，为了让你知道能做什么，下面有几个例子。

首先，这里有一个小配置，可以让你把所有的日志信息输出到控制台。

settings.py

import os
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "WARNING",
    },
}

这将配置父 root 记录器，以向控制台处理程序发送 WARNING 级别及以上的消息。通过将级别调整为 INFO 或 DEBUG，可以显示更多的消息。这在开发过程中可能很有用。

接下来我们可以添加更多细粒度的日志记录。下面是一个例子，说明如何让日志系统只从名为 logger 的 django 中打印更多的消息。

settings.py

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

默认情况下，这个配置会从 django 的日志记录器中发送级别为 INFO 或更高的消息到控制台。这个级别和 Django 的默认日志配置是一样的，只是默认配置只在 DEBUG=True 时才显示日志记录。Django 不会记录很多这样的 INFO 级别的消息。不过，有了这个配置，你也可以设置环境变量 DJANGO_LOG_LEVEL=DEBUG 来查看 Django 所有的调试日志，因为它包括了所有的数据库查询，所以非常啰嗦。

你不需要把日志记录到控制台。下面是一个配置，它将所有来自 django 命名的记录器的日志记录写入本地文件。

settings.py

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 应用的用户可写的路径。

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

settings.py

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "verbose": {
            "format": "{levelname} {asctime} {module} {process:d} {thread:d} {message}",
            "style": "{",
        },
        "simple": {
            "format": "{levelname} {message}",
            "style": "{",
        },
    },
    "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，它将任何 INFO （或更高）消息打印到 sys.stderr。该处理程序使用 simple 输出格式。
  • mail_admins, an AdminEmailHandler, which emails any ERROR (or higher) message to the site ADMINS. This handler uses the special filter.

• 配置三个记录器。

  • django，将所有信息传递给 console 处理程序。
  • django.request，它将所有 ERROR 消息传递给 mail_admins 处理程序。此外，这个记录器被标记为 不 传播消息。这意味着写给 django.request 的日志信息不会被 django 日志处理程序处理。
  • myproject.custom，它将所有 INFO 或更高等级的消息传递给两个处理程序——console 和 mail_admins。这意味着所有 INFO 级别（或更高）的消息将被打印到控制台；ERROR 和 CRITICAL 消息也将通过电子邮件输出。

自定义日志记录配置

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

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

禁用日志记录配置

如果你根本不想配置日志记录（或者你想用自己的方法手动配置日志记录），你可以将 LOGGING_CONFIG 设置为 None。这将禁用 Django 的默认日志记录 的配置过程。

将 LOGGING_CONFIG 设置为 None 只是意味着自动配置过程被禁用，而不是日志本身。如果你禁用了配置过程，Django 仍然会进行日志调用，回到默认的日志行为。

下面是一个禁用 Django 的日志配置，然后手动配置日志的例子。

settings.py

LOGGING_CONFIG = None
import logging.config
logging.config.dictConfig(...)

请注意，默认的配置过程只有在设置完全加载后才会调用 LOGGING_CONFIG。相反，在设置文件中手动配置日志记录将立即加载你的日志记录配置。因此，你的日志配置必须出现在它所依赖的任何设置之后。