Python 3.12 日志核心：深入理解 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() 中完成。

动态属性管理

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

工厂模式

我们可以通过 logging.makeLogRecord(dict) 工厂方法创建实例，这在调试或模拟日志场景下很有用：

import logging

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

关键方法

getMessage() 负责合并 msg 与 args 生成最终日志消息。如果存在 args，则使用 % 运算符进行格式化；当 args 为空元组、空字典或 None 时，不进行格式化。该方法在格式化器（Formatter）中被调用，用于获取消息部分。

def getMessage(self):
    """
    Return the message for this LogRecord.
    Return the message for this LogRecord after merging any user-supplied arguments with the message.
    """
    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 实现

下面是一个扩展 LogRecord 以添加自定义字段的完整示例。我们通过自定义工厂函数和过滤器来实现业务级日志增强。

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()

执行上述代码将输出包含自定义 ID 和字段的日志信息（此处应显示包含自定义字段的日志输出）。

性能优化建议

在实际开发中，为了保持高性能，建议在 Filter 中尽早过滤低级别日志，避免不必要的计算和对象创建。

总结

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