尽管调试的手法有很多，如 print、pdb（断点）、ipython（动态交互） 等，但唯一的王道手法，就是日志。因为，开发环境可以玩各种花样，生产环境则唯有日志可以依靠。为了确保生产环境的日志是完备的，开发环境则应该充分使用日志来调试。

在别的语言，往往需要第三方的日志工具，才能达到生产环境的实用标准。但是在 Python，标准库自带的 logging，就足够好用。

官网：logging --- Python 的日志记录工具 — Python 3.12.10 文档

基本概念

Python 的 logging 模块是一个灵活且强大的日志管理工具，其核心概念包括 Logger、Handler、Filter、Formatter 和 LogRecord。

• Logger（日志记录器）：应用程序直接调用的接口，用于生成日志。有继承性和传播性，根 Logger 名为 ''（空字符串），其它 Logger 名称随意，可以通过 . 来分割，如 'app.module' 。
• Handler（处理器）：决定日志的输出位置（如控制台、文件、网络等），可独立设置级别、过滤器和格式。
• Formatter（格式器）：使用格式字符串（类似 printf 风格），定义日志的输出格式，包括时间、级别、消息等信息。
• Filter（过滤器）：提供更细粒度的日志过滤（而非单纯的日志级别）。
• LogRecord（日志记录对象）：由 Logger 自动创建的类，封装日志的元数据和内容（如时间、级别、消息、文件名等）。它是整个日志系统的输入，也是核心的过程数据，但不是结果；结果往往是一行字符串。

此外，还有一个概念叫日志级别，定义日志的严重程度，用于控制日志的输出粒度。级别从低到高依次为：

• DEBUG：调试信息，适用于开发阶段。
• INFO：常规信息，如程序运行状态。
• WARNING：潜在问题，但程序仍可运行。
• ERROR：严重错误，影响部分功能。
• CRITICAL：致命错误，可能导致程序终止。

（对不同语言，会有类似而不同的设计。比如，某些语言高级里没有 CRITICAL，某些语言低级里会多个TRACE。）

以上概念，虽然是针对 Python 标准库的 logging 模块进行介绍，但相关概念，在其它日志库，乃至其它语言的日志库，都是通用的，可以找到相同、或至少相似的东西。

基本使用

在使用时，分两件事。一是如何调用日志，二是如何配置日志。

有很多方法，但我个人仅推荐如下一种：

from logging import getLogger

LOG = getLogger(__name__)

LOG.debug('Hello world!')

msg = 'world'
LOG.info('Hello %s!', msg)

尽管有人直接使用 logging.debug 这样的形式，但个人不推荐，因为这样会只使用根Logger。也有人会全局只创建一个 Logger，也行，但我也不推荐，因为这会为日志的扩展处理带来额外的麻烦。我推荐在每个需要日志的 Python 文件前面，都加上这两句：

from logging import getLogger

LOG = getLogger(__name__)

然后，这个 LOG 就可以在这个文件中任你使用。它的 name，就是 __name__，也即你当前文件的完整模块名，例如 app.module.submodule.util 。

尽管具体在什么情况下使用 debug 或 info，什么情况下使用 warning 或 error，里面有很深的门道，单独可以写几万字。但是如果没有实践，理解起来会很困难。我只给一个简单的建议：没事的时候，多在本地欣赏一下你写的日志。没错，不是定位问题，就单纯的欣赏。无论角度是好看，还是好用，自己多看两眼。只要作为开发者的你，真正在意它，那几万字的注意事项，你可以自己慢慢悟出来。

基本配置

怎么调用，门槛很低、易会难精。而怎么配置，则是门槛略高、但易精难会。

前面的示例代码，如果在标准环境单独运行，则什么显示都没有。因为默认只显示 warning 级以上。

至少有两种配置方法，这里只推荐一种，dictConfig：

from logging import getLogger
from logging.config import dictConfig

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format':
            '{asctime} {module}.{funcName} {lineno:3} {levelname:7} => {message}',
            'style': '{',
        },
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'formatter': 'verbose',
        },
        'file': {
            'class': 'logging.handlers.RotatingFileHandler',
            'formatter': 'verbose',
            'filename': '/tmp/django.log',
            'maxBytes': 4194304,  # 4 MB
            'backupCount': 10,
            'level': 'DEBUG',
        },
    },
    'loggers': {
        '': {
            'handlers': ['console', 'file'],
            'level': 'DEBUG',
        },
        'django': {
            'handlers': ['console', 'file'],
            'level': 'INFO',
            'propagate': False,
        },
    },
}
dictConfig(LOGGING)

LOG = getLogger(__name__)


def main():
    LOG.debug('Hello world!')
    msg = 'world'
    LOG.info('Hello %s!', msg)

    log = getLogger('django')
    log.debug('Hello world from django!')  # 不会显示
    log.info('Hello world from django!')


main()

dictConfig 的优点是，把所有关键概念全部都串起来。所以，在配置上很方便。

以上内容，写入文件 log.py 中，运行可以得到以下结果：

$ python log.py 
2025-04-27 20:57:13,818 log.main  46 DEBUG   => Hello world!
2025-04-27 20:57:13,818 log.main  48 INFO    => Hello world!
2025-04-27 20:57:13,818 log.main  52 INFO    => Hello world from django!

以上 LOGGING 这个字典的配置，是我个人的常用配置（精简版）。它实现了同一行日志，既可以在前台打印，又可以写入日志文件（示例中是 /tmp/django.log）。

这个配置省略了 Filter 的配置（配置中没有 'filters'），因为在绝大部分时候，这一层都不需要。主要的花样，都是在 Handler 这一级（配置中的 'handlers'）实现的。

在 Logger 这一级，可以为不同名称的日志，选择不同的 Handler 和日志级别。这里给根日志（也就是 ''），选择了 DEBUG 级别，而给 'django' 日志，选择了 INFO 级别，因此有一条日志被“吃”了，没打出来，符合预期。这个配置，不仅仅对 'django'有效，而是对 'django.*' 都有效。通过这一级的配置，不仅可以掌控自研模块的日志，也能对第三方库的日志，进行调控。

另外，可以看出，这是面向 Django 服务的一个日志配置示例。在Django 的 settings.py 文件中，只需要配置 LOGGING 这个模块常量即可完成配置。而对于其它类型的 Python 程序，要确保 dictConfig(LOGGING) 这行代码，在程序的主要功能运行前执行，例如放到 app.py、main.py等入口文件的最前面。

最后，这个示例给出的配置是死的，但由于它是 Python 代码，因此具备灵活的动态性。如果需要其中的什么内容可配置，可以自行开发。

其它配置手法

尽管都不推荐，但也稍微介绍一下其它三种日志配置手法：

1. 代码配置：直接操作日志的各种类，用Python的语法，把这个构造出来，加到那个里面去。过于繁琐，极端情况下可以作为 dictConfig 的补充。
2. 文件配置：在文件里写一个和 dictConfig 同构的配置。太死板了，而且写错了内容后，调试困难。
3. 网络配置：看上去灵活性很高，似乎适合大规模微服务，实际上根本没有这种需求，也千万不要给自己埋雷。

更多日志配置内容，见官网：logging.config --- 日志记录配置 — Python 3.12.10 文档

Handler简介

由于主要的花样，都在 Handler 这一级，因此需要多了解 Handler。

更多内容可参考官网：logging.handlers --- Logging handlers  Python 3.12.10 文档

这些是标准库自带的，而如果还不满意，则可以自己去扩展。通过继承某个类，很容易扩展出需要的功能。

总结

如开篇所说，日志，是生产环境唯一的调试手段。因此，相关内容其实很多，几万字也写不完。

但就功能来讲，logging 这个标准库，已经足够好用。最多需要进行一些手动配置，乃至开发扩展。

后续会再介绍 Python 生态中的一些第三方日志库。