Python logging.setLogRecordFactory 怎样统一注入关联字段

如果一个 Python 服务希望每条日志都带上 request_id，把字段写进每一次 logger.info(..., extra=...) 很快就会变成重复劳动。logging.setLogRecordFactory() 提供了更靠近记录创建的位置：先保留现有工厂，再给新建的 LogRecord 补充字段，Formatter 只负责把字段输出。

官方文档：https://docs.python.org/3/library/logging.html#logging.setLogRecordFactory

适合使用它的场景是“同一进程内的大多数日志都需要同一种基础字段”。如果字段只属于一个调用范围，LoggerAdapter 往往更直接；如果只是筛选某个 Handler 的记录，则应优先考虑 Filter。

先看 LogRecord 工厂位于哪里

普通日志调用会创建 LogRecord，记录随后交给 Logger 层级和 Handler 处理。工厂的职责是创建这条记录，因此可以在记录诞生时增加自定义属性。它不是日志开关，也不替代 Formatter 的排版职责。

官方文档给出的关键做法是先调用 getLogRecordFactory() 保存旧工厂，然后在包装函数里委托给它。这样已有的工厂链不会被直接截断，也能给其他扩展留下组合空间。

用工厂统一补充基础字段

下面的例子把固定的服务名和当前请求 ID 放入每条新记录。示例使用 ContextVar 保存请求范围的值，避免用一个进程级可变字符串承载并发请求。

import contextvars
import logging

# 用上下文变量保存当前请求的关联 ID，未进入请求时使用占位值。
request_id_var = contextvars.ContextVar("request_id", default="-")
old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    # 先委托旧工厂，保留标准字段和其他工厂已经加入的属性。
    record = old_factory(*args, **kwargs)
    # 只写入自定义字段，避免覆盖 name、levelno 等标准字段。
    record.service = "billing-api"
    record.request_id = request_id_var.get()
    return record

logging.setLogRecordFactory(record_factory)
logging.basicConfig(
    level=logging.INFO,
    format="%(levelname)s service=%(service)s request_id=%(request_id)s %(message)s",
)
logger = logging.getLogger(__name__)

def handle_request(request_id):
    # set 返回 token，退出请求后用它恢复上一个上下文值。
    token = request_id_var.set(request_id)
    try:
        logger.info("开始处理请求")
    finally:
        # 恢复上下文，避免后续代码沿用本次请求的 ID。
        request_id_var.reset(token)

这个例子的关键不是把字符串写进 Formatter，而是让 Formatter 读取一个已经存在于 LogRecord 上的属性。这样所有沿用同一 logging 配置的模块都可以共享字段格式，同时调用方不需要逐条传 extra。

字段值应该来自哪里

工厂适合注入“每条记录都有默认值”的基础字段，例如服务名、进程标识或请求 ID 的占位值；真正的请求 ID 仍要由请求入口设置。同步代码可以用 token 方式恢复，异步代码则应让上下文变量随任务上下文传递，并在边界处明确设置和恢复。

def run_with_request(request_id, work):
    # 进入一段请求范围，并保存进入前的上下文状态。
    token = request_id_var.set(request_id)
    try:
        return work()
    except Exception:
        # 记录异常时仍能读取当前 request_id，便于定位请求范围。
        logger.exception("请求处理失败")
        raise
    finally:
        # 无论成功还是失败，都恢复调用方的上下文。
        request_id_var.reset(token)

不要把用户输入直接写进日志格式字符串，也不要把访问令牌、密码等敏感内容当作关联字段。关联字段的目标是串起同一请求的记录，不是复制完整请求上下文。

factory、LoggerAdapter、Filter 到底怎么选

可以按字段出现的位置做选择：

例如，第三方库的日志不应该被业务请求对象强行包装时，统一基础字段可以放在 factory；某个子系统有自己的租户号时，使用 LoggerAdapter 更容易控制范围；只有审计 Handler 需要脱敏或补充展示字段时，Filter 更合适。

工厂链和字段冲突要提前处理

setLogRecordFactory 的影响范围较大，常见风险有三类。

• 覆盖旧工厂：直接把工厂换成自己的函数，可能丢掉前面已经注入的属性；应先取得旧工厂并委托。
• 覆盖标准字段：不要重写 name、levelno、pathname 等 LogRecord 属性；自定义字段使用稳定且不冲突的命名。
• 格式要求过严：Formatter 如果要求每条记录都具备字段，而某些外部记录没有该字段，输出阶段可能因格式化失败；给字段默认值或按 Handler 分开格式化。

def install_factory(field_name, default_value):
    # 允许在已有工厂链上再包一层，而不是替换整条链。
    previous = logging.getLogRecordFactory()

    def chained_factory(*args, **kwargs):
        # 先生成完整记录，再只补充约定的自定义字段。
        record = previous(*args, **kwargs)
        if not hasattr(record, field_name):
            setattr(record, field_name, default_value)
        return record

    logging.setLogRecordFactory(chained_factory)

多层包装时应约定字段命名和安装顺序。安装逻辑最好只在应用初始化阶段执行一次，避免每次热加载都再包一层。

什么时候不该用全局工厂

如果只有少量调用需要字段，直接使用 extra 或 LoggerAdapter 更清晰；如果字段需要根据某一个 Handler 的目的地变化，Filter 的范围更小；如果只是把字段排版成 JSON 或文本，Formatter 就足够了。

工厂函数会位于大量日志调用的公共路径上，所以不要在其中做网络请求、磁盘读写、复杂序列化或不可控的锁等待。字段获取也要尽量是常数级操作。对于敏感字段，优先注入不可逆的内部标识或经过脱敏的值，并控制日志权限和保留期限。

最后用一张清单确认采用边界

1. 是否确实需要大多数 LogRecord 都拥有这个字段？如果不是，先考虑 LoggerAdapter 或 extra。
2. 是否保存并委托了旧 factory？如果应用或依赖已经安装工厂链，不能直接覆盖。
3. 字段是否避开标准属性名，并且为缺失上下文提供默认值？
4. Formatter、Filter 和 Handler 的职责是否仍然清楚？不要把输出格式逻辑塞进工厂。
5. 工厂路径是否足够轻量，且没有记录敏感信息？

一句话概括：setLogRecordFactory 适合统一“记录创建时就应该存在”的基础字段；请求范围的值由上下文提供，局部范围由 LoggerAdapter 控制，输出和筛选交给 Formatter、Filter 与 Handler。

相关问题

factory 能不能直接返回自定义 LogRecord 子类？

可以把可调用对象设置为工厂，但仍要保证调用签名和返回对象满足 logging 后续处理所需的记录接口。大多数场景只需包装旧 factory 并增加属性。

为什么 Formatter 里写了 request_id 却报字段不存在？

Formatter 只负责读取记录属性，不会自动创建字段。需要让每条经过该 Handler 的记录都带默认值，或把不同来源的记录分到不同格式化策略。

LoggerAdapter 和 factory 能一起用吗？

可以。factory 提供公共默认字段，LoggerAdapter 负责某个调用范围的额外上下文；两者要避免使用同名字段，并明确哪一层拥有最终值。