3. Python 日志模块(logging)深度解析：Logger、Handler、Formatter、Filter 四大核心组件的工作原理

在生产环境中，日志是系统可靠性的基石。Python 标准库 logging 模块采用组件化架构，将日志记录、输出格式、目的地路由和过滤解耦为四个核心对象。理解这四大组件的工作原理，是构建可观测性系统和 ErrorHandler 报警联动的基础。

3.1 Logger：日志记录器

Logger 是应用程序直接使用的接口对象，负责创建日志记录（LogRecord）并将其传递给 Handler 链。每个 Logger 实例都有一个名称，名称采用层级命名空间（如 app.service.module），支持父子继承关系。

import logging

# 创建模块级 Logger
logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)

# 日志记录方法
logger.debug("调试信息：变量 x = %s", x)
logger.info("用户 %s 登录成功", username)
logger.warning("磁盘使用率超过 80%%")
logger.error("数据库连接失败: %s", err)
logger.critical("系统内存耗尽，即将退出")

3.2 Handler：日志处理器

Handler 决定日志记录的最终去向。Python 内置了丰富的 Handler 实现，覆盖控制台、文件、网络、系统日志等场景。一个 Logger 可以绑定多个 Handler，实现日志的多路输出。

import logging
from logging.handlers import RotatingFileHandler, SMTPHandler

# 创建 Logger
logger = logging.getLogger("myapp")
logger.setLevel(logging.DEBUG)

# 控制台 Handler
console = logging.StreamHandler()
console.setLevel(logging.INFO)

# 文件 Handler（按大小轮转）
file_handler = RotatingFileHandler(
    "app.log", maxBytes=10*1024*1024, backupCount=5
)
file_handler.setLevel(logging.DEBUG)

# 邮件 Handler（仅错误级别）
mail_handler = SMTPHandler(
    mailhost=("smtp.example.com", 587),
    fromaddr="alerts@example.com",
    toaddrs=["ops@example.com"],
    subject="应用错误报警",
    credentials=("user", "password"),
    secure=()
)
mail_handler.setLevel(logging.ERROR)

# 绑定 Handler
logger.addHandler(console)
logger.addHandler(file_handler)
logger.addHandler(mail_handler)

3.3 Formatter：日志格式化器

Formatter 负责将 LogRecord 对象转换为可读的字符串。通过格式化字符串模板，可以精确控制日志输出的内容、顺序和样式。标准库提供了丰富的格式化字段。

常用格式化字段一览：

import logging

# 创建 Formatter
formatter = logging.Formatter(
    fmt="%(asctime)s | %(levelname)-8s | %(name)s:%(filename)s:%(lineno)d | %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S"
)

# 应用到 Handler
handler = logging.StreamHandler()
handler.setFormatter(formatter)

# 输出示例：
# 2025-01-15 14:30:22 | ERROR    | myapp:server.py:42 | 连接超时

3.4 Filter：日志过滤器

Filter 提供比日志级别更细粒度的控制能力。通过实现 filter(record) 方法，可以基于 LogRecord 的属性动态决定是否处理该日志。Filter 可以绑定到 Logger 或 Handler 上。

import logging

class SensitiveDataFilter(logging.Filter):
    """过滤包含敏感信息的日志记录"""
    def __init__(self, keywords=None):
        super().__init__()
        self.keywords = keywords or ["password", "", "secret"]

    def filter(self, record):
        # 检查日志消息是否包含敏感词
        msg = record.getMessage().lower()
        for kw in self.keywords:
            if kw in msg:
                return False  # 丢弃该记录
        return True

class ModuleFilter(logging.Filter):
    """仅允许特定模块的日志通过"""
    def __init__(self, allowed_modules):
        super().__init__()
        self.allowed_modules = allowed_modules

    def filter(self, record):
        return record.name in self.allowed_modules

# 使用示例
logger = logging.getLogger("myapp")
logger.setLevel(logging.DEBUG)

# 绑定到 Logger（全局过滤）
logger.addFilter(SensitiveDataFilter())

# 绑定到 Handler（仅影响该 Handler）
console = logging.StreamHandler()
console.addFilter(ModuleFilter(["myapp.api", "myapp.core"]))
logger.addHandler(console)

3.5 四大组件联动配置示例

以下是一个完整的生产级日志配置，展示四大组件如何协同工作：

import logging
import logging.config
import json

# 使用字典配置（推荐生产环境）
LOGGING_CONFIG = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "detailed": {
            "format": "%(asctime)s | %(levelname)-8s | %(name)s:%(filename)s:%(lineno)d | %(message)s",
            "datefmt": "%Y-%m-%d %H:%M:%S"
        },
        "simple": {
            "format": "%(levelname)s: %(message)s"
        }
    },
    "filters": {
        "sensitive_filter": {
            "()": SensitiveDataFilter,
            "keywords": ["password", ""]
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "level": "INFO",
            "formatter": "simple",
            "filters": ["sensitive_filter"]
        },
        "file": {
            "class": "logging.handlers.RotatingFileHandler",
            "level": "DEBUG",
            "formatter": "detailed",
            "filename": "app.log",
            "maxBytes": 10485760,
            "backupCount": 5
        },
        "error_mail": {
            "class": "logging.handlers.SMTPHandler",
            "level": "ERROR",
            "formatter": "detailed",
            "mailhost": ("smtp.example.com", 587),
            "fromaddr": "alerts@example.com",
            "toaddrs": ["ops@example.com"],
            "subject": "应用错误报警",
            "credentials": ("user", "password"),
            "secure": ()
        }
    },
    "loggers": {
        "myapp": {
            "level": "DEBUG",
            "handlers": ["console", "file", "error_mail"],
            "propagate": False
        },
        "myapp.api": {
            "level": "INFO",
            "handlers": ["console"],
            "propagate": True  # 向上传递给 myapp
        }
    },
    "root": {
        "level": "WARNING",
        "handlers": ["console"]
    }
}

# 应用配置
logging.config.dictConfig(LOGGING_CONFIG)

# 使用
logger = logging.getLogger("myapp.api")
logger.info("API 请求处理完成")  # 输出到 console
logger.error("数据库连接失败")   # 输出到 console + file + error_mail

3.6 核心组件对比总结