Python logging 怎样按模块切分日志级别

Python logging 按模块切分日志级别，关键不是给每个文件随手调用一次 basicConfig()，而是让模块名形成稳定的 logger 层级，再分别设置 logger、handler 和 propagate。例如可以让 myapp.web 只输出 INFO 以上，让 myapp.worker 保留 DEBUG 细节，而 root logger 只做 WARNING 兜底。

最稳妥的做法是：业务模块只用 logging.getLogger(__name__)，集中配置一次；模块自己的 handler 负责独立输出时，把 propagate 设为 False，否则同一条记录可能继续冒泡到 root logger。

先把 logger 名称设计成模块树

每个模块都使用自己的名字创建 logger，不要在业务代码里直接使用 root logger：

import logging

# 使用模块名作为 logger 名称，让配置可以按包层级匹配
logger = logging.getLogger(__name__)

def load_profile(user_id: str) -> dict:
    # DEBUG 只记录排查所需的输入上下文，不把敏感凭据写入日志
    logger.debug("开始读取用户配置 user_id=%s", user_id)
    try:
        profile = {"user_id": user_id, "theme": "light"}
    except KeyError:
        # 异常日志保留堆栈，便于定位真正的调用位置
        logger.exception("用户配置字段缺失 user_id=%s", user_id)
        raise
    return profile

假设文件位于 myapp/web.py、myapp/worker.py 和 myapp/data.py，那么 __name__ 通常会得到 myapp.web、myapp.worker 和 myapp.data。点号就是层级分隔符，配置 myapp 时可以覆盖其子模块，配置更具体的 myapp.worker 时又可以单独收紧或放宽。

先分清 logger level 和 handler level

这两个级别经常被混为一谈，但它们处在不同位置：

因此，想看到 worker 的 DEBUG，不能只把文件 handler 设为 DEBUG；worker logger 本身也必须允许 DEBUG 记录产生。反过来，如果 logger 允许 DEBUG，但控制台 handler 是 INFO，DEBUG 仍然不会出现在控制台，却可以进入另一个更低阈值的 handler。

用 dictConfig 给模块分配不同级别

配置集中放在启动入口，业务模块只负责发日志。下面的配置把 web 的普通运行信息送到控制台，把 worker 的详细信息送到独立文件，并让 root logger 处理没有单独配置的模块：

import logging.config

LOGGING = {
    "version": 1,
    # 保留第三方库已有 logger，避免配置时全部静默
    "disable_existing_loggers": False,
    "formatters": {
        "standard": {
            "format": "%(asctime)s %(name)s %(levelname)s %(message)s"
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "level": "INFO",
            "formatter": "standard",
            "stream": "ext://sys.stdout"
        },
        "worker_file": {
            "class": "logging.FileHandler",
            "level": "DEBUG",
            "formatter": "standard",
            "filename": "worker.log",
            "encoding": "utf-8"
        }
    },
    "loggers": {
        "myapp.web": {
            "level": "INFO",
            "handlers": ["console"],
            # web 已经有专属 handler，避免再次交给 root 输出
            "propagate": False
        },
        "myapp.worker": {
            "level": "DEBUG",
            "handlers": ["worker_file"],
            # worker 的 DEBUG 只进入自己的文件
            "propagate": False
        }
    },
    "root": {
        "level": "WARNING",
        "handlers": ["console"]
    }
}

# 在应用启动阶段统一安装配置，业务模块不要重复调用 basicConfig
logging.config.dictConfig(LOGGING)

这份配置的取舍是“模块级优先、root 级兜底”：myapp.web 的 DEBUG 会先被 logger 阈值挡住，INFO 及以上交给控制台；myapp.worker 的 DEBUG 交给文件；其他模块没有专属配置时，按照 root 的 WARNING 处理。FileHandler 的文件路径应由部署配置决定，生产环境还要结合轮转 handler 或日志收集系统管理容量。

出现缺失或重复日志时怎么排查

先看代码创建出来的 logger 名称，再看它的有效级别和 handler。一个常见误区是只修改了父 logger 的级别，却忘记子 logger 已经显式设置了更高阈值；另一个误区是子 logger 与 root 都挂了控制台 handler，同时 propagate 仍为 True，结果一条记录打印两次。

import logging

logger = logging.getLogger("myapp.worker")

# 这些属性用于诊断配置状态，不是业务日志内容
print("name=", logger.name)
print("effective_level=", logger.getEffectiveLevel())
print("handlers=", [type(item).__name__ for item in logger.handlers])
print("propagate=", logger.propagate)

可以按下面的顺序判断：

1. 日志缺失：先确认调用的 logger 名称是否和 dictConfig 中的键一致，再比较 logger 的有效级别和消息级别。
2. 只在文件出现：检查控制台 handler 的级别是否高于该消息，或该模块是否关闭了向父级传播。
3. 重复出现：检查模块和 root 是否都挂了相同目的地的 handler；如果模块需要独立 handler，通常将 propagate 设为 False。
4. 第三方库太吵：针对它的完整 logger 名称设置 WARNING 或更高，而不是粗暴关闭整个 root logger。

小结：按模块切分日志的配置清单

• 模块代码统一使用 logging.getLogger(__name__)，不要到处调用 root logger。
• logger level 决定记录是否产生，handler level 决定记录去哪里。
• 模块已有专属 handler 时明确设置 propagate=False，避免重复输出。
• 把配置集中在启动入口，给没有专属规则的模块保留 root WARNING 兜底。

常见问题

为什么把 handler 设成 DEBUG 仍然看不到 DEBUG？

因为 logger 可能在更早的位置以 INFO 或 WARNING 过滤掉了记录。先降低对应 logger 的级别，再检查 handler。

子模块一定要单独配置吗？

不一定。若一组模块使用同一策略，可以只配置共同的父 logger，让子 logger 继续传播；只有需要不同阈值或目的地时才配置具体子模块。

库代码应该自己添加 FileHandler 吗？

通常不应该。库应使用有辨识度的 logger 名称，必要时使用 NullHandler，把 handler 和输出目的地交给最终应用配置。

参考资料：https://docs.python.org/3/howto/logging.html、https://docs.python.org/3/library/logging.html、https://docs.python.org/3/library/logging.config.html