深入理解hynek/structlog与Python标准库logging的集成-优快云博客

深入理解hynek/structlog与Python标准库logging的集成

structlog Simple, powerful, and fast logging for Python. 项目地址: https://gitcode.com/gh_mirrors/st/structlog

概述

在Python生态中，日志记录是一个非常重要的功能。Python标准库提供了logging模块作为基础的日志记录工具，而hynek/structlog则是一个更现代化、更灵活的日志记录库。本文将深入探讨如何将structlog与标准库logging无缝集成，以及如何利用structlog增强标准库的日志功能。

为什么需要集成structlog和标准库logging

在实际项目中，我们经常会遇到以下情况：

项目依赖的第三方库使用标准库logging
团队中部分开发者习惯使用标准库logging
需要保持日志格式的一致性

structlog提供了与标准库logging集成的能力，使得我们可以：

保留现有代码中使用logging的部分
逐步迁移到structlog
统一日志输出格式

基础集成方法

最简单的集成方式

structlog可以作为标准库logging的替代品直接使用：

import structlog

# 替换原来的logging.getLogger
logger = structlog.get_logger()

这种替换方式在structlog正确配置的情况下，可以保持原有功能不变。

标准库logging的基本配置

要让structlog与标准库logging协同工作，至少需要配置logging的基本设置：

import logging
import sys

logging.basicConfig(
    format="%(message)s",
    stream=sys.stdout,
    level=logging.INFO,
)

这段代码会将所有INFO级别及以上的日志输出到标准输出，不做特殊格式化。

structlog的绑定日志器

structlog提供了一个专门用于标准库集成的绑定日志器：

structlog.stdlib.BoundLogger：镜像标准库logging.Logger的方法，并提供正确的类型提示
structlog.stdlib.AsyncBoundLogger：异步版本的绑定日志器（23.1.0版本后推荐使用前缀a的方法）

异步日志记录

在asyncio应用中，可以使用异步日志方法避免阻塞：

await logger.ainfo("异步日志事件")

这些异步方法会在线程池中执行所有处理，虽然会增加计算开销，但能避免应用因日志记录而阻塞。

处理器(Processors)

structlog提供了一系列专门用于标准库集成的处理器：

render_to_log_kwargs：将事件字典转换为logging.Logger方法参数
filter_by_level：根据标准库logging的配置过滤日志级别
add_logger_name：添加logger名称到事件字典
add_log_level：添加日志级别到事件字典
PositionalArgumentsFormatter：处理并格式化位置参数
ExtraAdder：添加logging.LogRecord的额外属性到事件字典

推荐配置方案

方案1：在structlog中完成渲染

这是最简单的方法，structlog完成所有格式化工作，然后传递给标准库logging：

structlog.configure(
    processors=[
        structlog.stdlib.filter_by_level,
        structlog.stdlib.add_logger_name,
        structlog.stdlib.add_log_level,
        structlog.stdlib.PositionalArgumentsFormatter(),
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.StackInfoRenderer(),
        structlog.processors.format_exc_info,
        structlog.processors.UnicodeDecoder(),
        structlog.processors.JSONRenderer()
    ],
    wrapper_class=structlog.stdlib.BoundLogger,
    logger_factory=structlog.stdlib.LoggerFactory(),
    cache_logger_on_first_use=True,
)

方案2：使用logging的格式化器

让structlog只构建事件字典，格式化工作交给标准库logging：

structlog.configure(
    processors=[
        structlog.stdlib.filter_by_level,
        structlog.stdlib.add_logger_name,
        structlog.stdlib.add_log_level,
        structlog.stdlib.PositionalArgumentsFormatter(),
        structlog.processors.StackInfoRenderer(),
        structlog.processors.format_exc_info,
        structlog.processors.UnicodeDecoder(),
        structlog.stdlib.render_to_log_kwargs,
    ],
    logger_factory=structlog.stdlib.LoggerFactory(),
    wrapper_class=structlog.stdlib.BoundLogger,
    cache_logger_on_first_use=True,
)

方案3：使用ProcessorFormatter

最复杂的方案，使用structlog的ProcessorFormatter作为标准库logging的格式化器：

structlog.configure(
    processors=[
        structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
    ],
    logger_factory=structlog.stdlib.LoggerFactory(),
)

formatter = structlog.stdlib.ProcessorFormatter(
    processors=[structlog.dev.ConsoleRenderer()],
)

handler = logging.StreamHandler()
handler.setFormatter(formatter)
root_logger = logging.getLogger()
root_logger.addHandler(handler)
root_logger.setLevel(logging.INFO)