Python｜日志记录详解（2）

数据科学工厂

引言

到目前为止，您已经了解了名为 "root" 的默认日志记录器，它是日志模块在调用例如 logging.debug()、logging.warning() 等函数时默认使用的记录器。直接使用这个默认记录器是快速理解日志系统如何工作的一个有效方法。

但是，直接与根日志记录器打交道也有其不便之处，因为这样做通常依赖于单一的 basicConfig() 配置，这在配置上可能会比较麻烦，尤其是对于规模较大的项目，您可能需要更多样化的日志配置。

因此，通常推荐的做法是定义一个您自己的自定义日志记录器。这可以通过实例化日志模块中提供的 Logger 类来完成。

实例化 Logger

您可以通过调用logging.getLogger()函数并为记录器提供名称来实例化Logger类：

>>> import logging
>>> logger = logging.getLogger(__name__)
>>> logger.warning("Look at my logger!")
Look at my logger!

尽管您可以选择任何字符串作为日志记录器的名称，但通常推荐的做法是将 __name__ 作为名称参数传递。这样一来，您的日志记录器名称就会自动与 Python 包命名空间中的模块名称保持一致。

当您执行 logger.warn() 操作时，您可能发现输出中缺少了一些常见的日志信息，比如日志记录器的名称或日志的级别。为了对日志进行格式化，您可能会考虑对自定义的日志记录器使用 .basicConfig() 函数。但是请注意，与默认的根日志记录器不同，您不能通过 basicConfig() 来设置自定义日志记录器。实际上，您需要通过使用处理器和格式化器来配置自定义日志记录器，这种方法为您提供了更大的灵活性和定制性。

使用处理器（Handlers）

在您需要为自己的日志记录器设置个性化配置时，处理器就显得尤为重要。比如，您可能想把日志信息发送到标准输出或者写入到一个文件中。

下面是一个示例，演示了如何为自定义的日志记录器添加两个处理器。首先，您需要导入日志模块来创建日志记录器，随后创建两个处理器：

>>> import logging
>>> logger = logging.getLogger(__name__)
>>> console_handler = logging.StreamHandler()
>>> file_handler = logging.FileHandler("app.log", mode="a", encoding="utf-8")

StreamHandler 类负责将日志信息输出到控制台。而 FileHandler 类则负责将日志记录保存到文件中。为了指定日志的存储位置、打开方式以及编码格式，您需要提供相应的文件路径、模式和编码信息。

当您创建了处理器的实例之后，下一步就是将这些处理器添加到您的日志记录器中。这可以通过调用日志记录器的 .addHandler() 方法来实现。

>>> logger.addHandler(console_handler)
>>> logger.addHandler(file_handler)
>>> logger.handlers
[
  <StreamHandler <stderr> (NOTSET)>,
  <FileHandler /Users/RealPython/Desktop/app.log (NOTSET)>
]

您可以通过检查 .handlers 属性来查看日志记录器所包含的所有处理器。在上文示例中，展示了这两个处理器的字符串表达。

处理器的表达形式不仅包括类名，还指明了日志信息的输出位置。对于 StreamHandler 类型的处理器，日志信息会被输出到标准错误流（stderr），这是 Python 默认使用的输出通道。而 FileHandler 类型的处理器则会显示日志记录被保存的具体位置。

在类表达的括号内，标明了处理器的日志级别。目前，这个级别是 NOTSET。NOTSET 意味着处理器的日志级别尚未定义。

>>> logger.warning("Watch out!")
Watch out!

当您调用 logger.warning() 时，两个处理程序都会接管该消息。 StreamHandler 的输出立即显示在您的控制台中。要查看 FileHandler 是否也完成了其工作，请打开 app.log：

Watch out!

太好了！两个处理器都正常工作。仅需一次调用您的自定义日志记录器，您就可以通过不同的处理器将日志消息发送到多个目的地。

日志模块提供了许多针对特定用途设计的实用处理器。例如，RotatingFileHandler 会在文件达到一定大小时自动创建新的日志文件；还有 TimedRotatingFileHandler，它允许您在设定的时间间隔创建新的日志文件。

目前，这些日志消息看起来可能有些简单。正如您之前所了解的，日志记录的强大之处在于它能够通过时间戳、日志级别等元数据来丰富信息内容。这时，格式化器就派上用场了！

添加格式化器到处理器

处理器负责将日志信息发送到您指定的输出目标。而格式化器则允许您通过定义一个字符串格式来控制日志的输出样式，这与您之前在使用 logging.basicConfig() 函数时设置 format 参数的方式相似。

在使用格式化器之前，您同样需要先创建一个类的实例。在这个场景中，您应使用的是日志模块提供的 Formatter 类。

为了直观感受格式化器的功能，您可以回顾之前的代码示例，并在其中加入 logging.Formatter() 的使用。首先，尝试将格式化器添加到 StreamHandler 中，然后进行测试：

>>> import logging
>>> logger = logging.getLogger(__name__)
>>> console_handler = logging.StreamHandler()
>>> file_handler = logging.FileHandler("app.log", mode="a", encoding="utf-8")
>>> logger.addHandler(console_handler)
>>> logger.addHandler(file_handler)
>>> formatter = logging.Formatter(
...    "{asctime} - {levelname} - {message}",
...     style="{",
...     datefmt="%Y-%m-%d %H:%M",
... )

>>> console_handler.setFormatter(formatter)
>>> logger.warning("Stay calm!")
2024-07-22 15:58 - WARNING - Stay calm!

在这段文字中，您创建了一个格式化器实例，它会在日志输出中包含时间戳、日志级别和日志内容。通过调用 .setFormatter() 方法并传入格式化器实例，您就能为指定的处理器设置日志的显示格式。

请注意，.setFormatter() 与 .addHandler() 是不同的方法；.addHandler() 属于 Logger 类，而 .setFormatter() 属于 Handler 类。

在将 console_handler 和 file_handler 都添加到日志器后，当您调用 logger.warning() 时，警告信息不仅会输出到控制台，也会记录在 app.log 文件中。但由于只有 console_handler 被设置了格式化器，所以 app.log 文件中的日志条目没有应用样式。

通过为不同的处理器定义和设置各具特色的格式化器，您可以决定日志消息中包含的附加信息量。而且，您的选择可以更加灵活！例如，您可以在控制台中仅显示调试级别的消息，而将更严重的日志级别记录到文件中，或者根据需要进行相反的设置。

设置自定义日志器的日志级别

就像使用 logging.basicConfig() 进行配置一样，您也可以为每个处理器单独设置日志级别。这在做日志配置时非常有用，特别是当您为同一个日志器配置了多个处理器，并且希望它们各自有不同的日志记录严重性级别。

举个例子，在开发应用的过程中，您可能希望将 DEBUG 级别及以上的日志输出到控制台，而将 WARNING 级别及以上的日志存储到文件中。

首先，您需要创建一个自定义的日志器，并查看其默认的日志级别是什么。

>>> import logging
>>> logger = logging.getLogger(__name__)
>>> logger.level
0

>>> logger
<Logger __main__ (WARNING)>

>>> logger.parent
<RootLogger root (WARNING)>

您的自定义级别的默认日志级别是0，代表NOTSET。尽管如此，记录器的字符串表示形式仍显示“警告”日志级别。这是因为如果您尚未手动设置日志级别，自定义记录器会继承其父记录器的日志级别。

除了查看记录器的字符串表示形式之外，您还可以调用 .getEffectiveLevel() 方法：

>>> logger.getEffectiveLevel()
30

.getEffectiveLevel()的返回值是一个整数，代表日志级别。以下是日志级别的数字表示形式的概述：

![](/Users/yi/Library/Application Support/typora-user-images/image-20240825195656663.png)

您可以使用数值或日志级别字符串来设置自定义记录器的日志级别：

>>> logger.setLevel(10)
>>> logger
<Logger __main__ (DEBUG)>

>>> logger.setLevel("INFO")
>>> logger
<Logger __main__ (INFO)>

您可以使用 .setLevel() 方法来设置记录器的日志级别。您添加到记录器的任何处理程序都将识别此日志级别：

>>> formatter = logging.Formatter("{levelname} - {message}", style="{")
>>> console_handler = logging.StreamHandler()
>>> console_handler.setFormatter(formatter)
>>> logger.addHandler(console_handler)
>>> logger.debug("Just checking in!")
>>> logger.info("Just checking in, again!")
INFO - Just checking in, again!

由于 logger 的日志级别设置为 INFO，因此您添加到 logger 的 console_handler 不会显示日志级别低于 INFO 的日志。

你可能会说你还没有设置console_handler的日志级别，你是对的。此时，console_log 的级别为 NOTSET：

>>> console_handler
<StreamHandler <stderr> (NOTSET)>

但即使将处理程序的日志级别设置为低于关联的记录器，也不会显示低于记录器日志级别的消息：

>>> console_handler.setLevel("DEBUG")
>>> logger.debug("Just checking in!")
>>> console_handler
<StreamHandler <stderr> (DEBUG)>

即使您允许 console_log 显示 DEBUG 及以上级别的日志记录，调试消息仍然不显示。记录器及其处理程序的这种行为一开始可能会令人困惑。

考虑到这种行为，在开发过程中将记录器的日志级别设置为 DEBUG 并让每个处理程序决定其最低日志级别会很有帮助：

>>> import logging
>>> logger = logging.getLogger(__name__)
>>> logger.setLevel("DEBUG")
>>> formatter = logging.Formatter("{levelname} - {message}", style="{")

>>> console_handler = logging.StreamHandler()
>>> console_handler.setLevel("DEBUG")
>>> console_handler.setFormatter(formatter)
>>> logger.addHandler(console_handler)

>>> file_handler = logging.FileHandler("app.log", mode="a", encoding="utf-8")
>>> file_handler.setLevel("WARNING")
>>> file_handler.setFormatter(formatter)
>>> logger.addHandler(file_handler)

>>> logger.debug("Just checking in!")
DEBUG - Just checking in!

>>> logger.warning("Stay curious!")
WARNING - Stay curious!

>>> logger.error("Stay put!")
ERROR - Stay put!

在上面的示例中，您为 console_handler 和 file_handler 设置不同的日志级别。由于console_handler的日志级别为DEBUG，因此可以在控制台看到所有日志。如果您查看 file_handler 写入的 app.log 文件，则可以验证 WARNING 和 ERROR 日志是否已保存到该文件中：

WARNING - Stay curious!
ERROR - Stay put!

通过使用不同的日志级别，您可以决定信息记录的位置。值得注意的是，处理器记录的日志级别不会低于其关联日志器的设置级别。也就是说，处理器只会记录等于或高于设定级别的日志。

设置日志级别意味着所有低于该级别的日志消息都会被忽略，而所有等于或高于该级别的日志消息都会被记录。如果您希望只记录特定级别的日志，可以通过为处理器添加过滤器来实现更精细的控制。

过滤日志

如果您对程序生成的警告级别日志感兴趣，可能也会对更严重的级别，如错误或临界错误感兴趣。通常，您可以使用特定的处理器来收集某一级别及以上的所有日志记录。

但在某些情况下，您可能需要对特定级别的日志消息进行特别处理。这时，使用过滤器就显得非常有帮助。过滤器对象的工作原理如下：过滤器逻辑会检查对象是否具有过滤器属性：如果有，它将调用该过滤器的 filter() 方法。如果没有，它将调用该对象，并将记录作为单一参数传递。过滤器的返回值应与 filter() 方法的返回值一致。

创建日志过滤器有三种方法：

您可以定义一个 logging.Filter() 的子类并重写其 .filter() 方法，
或者创建一个包含 .filter() 方法的类，
或者定义一个具有 .filter() 方法的可调用对象。

对于子类和类，.filter() 方法应该接受一个日志记录并返回布尔值。在这个方法内部，您可以设置条件判断来检查传入的记录。

可调用对象可以是一个只接受一个参数（即日志记录）的简单函数，该参数由处理器传入，函数返回布尔值。使用可调用对象是创建简单过滤器的最便捷方式，这也是我们将要进一步探讨的方法。

理论已经就绪，接下来是将日志过滤器应用于实践的时候了。您将创建一个过滤器，确保控制台输出的处理器只展示 DEBUG 级别的日志消息。

>>> import logging
>>> def show_only_debug(record):
...     return record.levelname == "DEBUG"
...

>>> logger = logging.getLogger(__name__)
>>> logger.setLevel("DEBUG")
>>> formatter = logging.Formatter("{levelname} - {message}", style="{")

>>> console_handler = logging.StreamHandler()
>>> console_handler.setLevel("DEBUG")
>>> console_handler.setFormatter(formatter)
>>> console_handler.addFilter(show_only_debug)
>>> logger.addHandler(console_handler)

>>> file_handler = logging.FileHandler("app.log", mode="a", encoding="utf-8")
>>> file_handler.setLevel("WARNING")
>>> file_handler.setFormatter(formatter)
>>> logger.addHandler(file_handler)

>>> logger.debug("Just checking in!")
DEBUG - Just checking in!

>>> logger.warning("Stay curious!")
>>> logger.error("Stay put!")

首先，定义一个名为 show_only_debug() 的函数，它接受一个记录参数。传入的日志条目将是一个 LogRecord 类的实例。

在 show_only_debug() 函数内部，如果日志条目的 .levelname 属性值为 "DEBUG"，则函数返回 True，表示这条日志应该被显示。如果日志级别不是 DEBUG，函数返回 False，意味着该日志条目将被过滤器拦截，不会被输出。

要为处理器添加过滤器，需要使用 Handler 类的 .addFilter() 方法。.addFilter() 方法需要一个过滤器对象作为参数。在上述代码示例中，您将 show_only_debug() 函数作为参数传递，以将其设置为 console_handler 的过滤器。

对于 console_handler，您已经将其日志级别设置为 DEBUG。在没有其他配置的情况下，该处理器将输出所有 DEBUG 级别和更高级别的日志。但是，由于您添加了过滤器，现在它只会显示 DEBUG 级别的日志，而忽略更高级别的日志。而 file_handler 由于没有设置过滤器，它将正常记录所有设定级别和更高级别的日志。

通过这种方式，您的自定义日志器可以变得非常灵活，能够精确地输出您希望看到的信息。自定义日志器可以简单至仅使用根日志器，但通过结合使用处理器、格式化器和过滤器，您可以将自定义日志器打造成为您代码的精准信息记录者。

总结

Python 的日志模块以其高度的灵活性而著称。它的设计贴近实际应用，能够直接满足您的使用需求。无论是为小型项目添加基础日志功能，还是构建一个能够随着编程项目扩展的自定义日志器，日志模块都能胜任。

在本教程中，您掌握了以下内容：

如何使用 Python 的日志模块
如何配置基础的日志设置
如何应用不同的日志级别
如何利用格式化器来定制日志消息的格式
如何通过处理器来改变日志的输出方向
如何使用过滤器来明确日志记录的规则

微信扫一扫分享文章

Python｜日志记录详解（2）

引言

实例化 Logger

使用处理器（Handlers）

添加格式化器到处理器

设置自定义日志器的日志级别

过滤日志

总结

相关帖子

单细胞分析：质控实战（五）

Python｜日志记录详解（1）

数据科学工厂 LV5