Python 3.12 logging 模块 LogRecord 详解

LogRecord 基本概念

LogRecord 是 Python logging 模块中代表一条日志事件的数据容器。简单来说，它就像一张'记录单'，每当程序调用日志方法（如 logger.info()）时，logging 会自动创建一个 LogRecord 对象，并把所有相关信息都装进去，包括：日志消息内容、日志级别（DEBUG/INFO 等）、产生日志的时间戳、源代码位置（文件名、行号、函数名）、当前线程/进程 ID、异常信息（如果有）、其他自定义属性（通过 extra 添加）。 这个'记录单'随后会被传递给日志处理器（Handler）和格式化器（Formatter），最终被转换成我们看到的输出文本。

LogRecord 类机制解析

LogRecord是logging模块的核心类，用于封装日志事件的所有信息。每次记录事件时，系统都会生成 LogRecord 实例。其包含与所记录事件相关的全部信息。 传递的主要信息位于 msg 和 args 中，通过str(msg) % args组合形成记录的消息字段，实际的消息格式化在 getMessage() 中完成。

1. 动态属性管理

• 属性存储：通过__init__动态存储字段（如msg, levelname等）
• 延迟格式化：如message属性在访问时通过getMessage()，解析msg与args
• 默认属性集：包含多个字段信息（如name，pathname，lineno，exc_info, sinfo等）

2. 工厂模式

通过logging.makeLogRecord(dict)工厂方法创建实例：

record_dict = {
    "name": "demo",
    "level": 20,
    "pathname": "/app/main.py",
    "msg": "User %s logged in",
    "args": ("Alice",)
}
record = logging.makeLogRecord(record_dict)

3. 关键方法

getMessage()：合并msg与args生成最终日志消息

def getMessage(self):
    """ Return the message for this LogRecord.
        Return the message for this LogRecord after merging any user-supplied arguments with the message.
        如果存在 args，则使用 % 运算符进行格式化，并返回最终消息字符串。
        当 args 为空元组或空字典或 None 时，也为假，不进行格式化）。
        该方法在格式化器（Formatter）中被调用，用于获取消息部分
    """
    msg = str(self.msg)
    if self.args:
        msg = msg % self.args
    return msg

LogRecord 生命周期

1. 创建：由Logger.log()调用Logger.makeRecord()生成
2. 处理：经由Filter、Formatter等组件
3. 输出：通过Handler写入目标（文件/网络等）

完整 Demo 实现

import logging
import logging.config
import time

class CustomLogRecord(logging.LogRecord):
    """扩展 LogRecord 以添加自定义字段"""
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.custom_id = hash(time.time())  # 添加唯一 ID

def custom_record_factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs):
    """自定义 LogRecord 工厂函数"""
    record = CustomLogRecord(name, level, fn, lno, msg, args, exc_info, func, sinfo)
    return record

# 定义一个过滤器，为记录添加默认的 custom_field
class DefaultCustomFieldFilter(logging.Filter):
    def __init__(self, default_value="d"):
        super().__init__()
        self.default_value = default_value

    def filter(self, record):
        if not hasattr(record, 'custom_field'):
            record.custom_field = self.default_value
        return True  # 返回 True 表示记录通过

# 配置日志系统
logging_config = {
    "version": 1,
    "formatters": {
        "detailed": {
            "format": "[%(asctime)s][%(levelname)s][%(name)s]-[ID=%(custom_id)s]-%(message)s # custom:%(custom_field)s",
            "datefmt": "%Y-%m-%d %H:%M:%S"
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "detailed",
            "level": "DEBUG",
            "filters": ["default_custom_field"]
        }
    },
    "loggers": {
        "demo": {
            "handlers": ["console"],
            "level": "DEBUG"
        }
    },
    "filters": {
        "default_custom_field": {
            "()": DefaultCustomFieldFilter,
            "default_value": ""
        }
    }
}

def main():
    # 应用配置并设置自定义工厂
    logging.config.dictConfig(logging_config)
    logging.setLogRecordFactory(custom_record_factory)
    logger = logging.getLogger("demo")

    # 标准日志记录
    logger.info("Service started")

    # 添加自定义字段
    logger.debug("Debug with extra", extra={"custom_field": "debug_value"})

    # 异常处理示例
    try:
        1 / 0
    except Exception as e:
        logger.error("Math error occurred", exc_info=True)

if __name__ == "__main__":
    main()

关键输出解析

执行上述代码将输出自定义字段及日志信息。

性能优化建议

1. 避免冗余计算：在Filter中尽早过滤低级别日志

总结

LogRecord作为日志系统的核心载体，通过灵活的属性和工厂机制支持深度定制。结合 Python 3.12 的优化特性（如 PEP 657 精确错误定位），可构建高性能、可扩展的日志架构。实际开发中应善用extra参数和自定义工厂实现业务级日志增强。