Python 日志组件Loguru使用指南

logging 与 loguru 的核心差异

• 配置复杂度

  • 标准 logging 需手动实例化命名的 Logger，并配置 Handler、Formatter 和 Filter。

  • Loguru 通过 add() 简化配置步骤，开箱即用。

• 默认输出流
  两者默认均输出到 sys.stderr（POSIX 标准指定 stderr 为诊断输出流），避免与 stdout 的应用输出混淆，且处理编码问题更友好（如 python my_app.py | other_app 管道场景）。

---

迁移

替换 getLogger() 函数

# 标准 logging
import logging
logger = logging.getLogger(__name__)

# Loguru
from loguru import logger  # 自动记录上下文 __name__

 替换 Logger 对象

Loguru 通过 bind() 绑定上下文，替代多 Logger 实例：

# 标准 logging 的多日志器
logger_a = logging.getLogger("a")
logger_b = logging.getLogger("b")

# Loguru 绑定不同上下文
logger_a = logger.bind(name="a")
logger_b = logger.bind(name="b")

# 按名称过滤日志
logger.add("a.log", filter=lambda r: r["extra"].get("name") == "a")
logger.add("b.log", filter=lambda r: r["extra"].get("name") == "b")

替换 Handler、Filter、Formatter

标准配置：

# 标准 logging 配置
logger.setLevel(logging.DEBUG)
fh = logging.FileHandler("spam.log")
fh.setLevel(logging.DEBUG)
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
fh.setFormatter(formatter)
logger.addHandler(fh)

Loguru 简化版：

# Loguru 等效配置
fmt = "{time} - {name} - {level} - {message}"
logger.add("spam.log", level="DEBUG", format=fmt)

替换 LogRecord 对象

Loguru 使用 record 字典存储日志详情（对应 LogRecord 属性），可在处理器中访问：

def advanced_sink(message):
    record = message.record
    if record["level"].no >= 50:
        print(f"Critical error in {record['file'].path}", file=sys.stderr)

logger.add(advanced_sink)

 替换 % 风格格式化

仅支持 {} 风格：

# 标准 logging
logger.debug("变量值: %s", var)

# Loguru
logger.debug("变量值: {}", var)  # 类似 str.format()

替换 exc_info 参数

使用 opt(exception=True) 捕获异常堆栈：

# 标准 logging
logger.debug("错误:", exc_info=True)

# Loguru
logger.opt(exception=True).debug("错误:")  # 自动捕获完整堆栈（生产环境慎用）

替换 extra 参数与 LoggerAdapter

通过 bind() 添加上下文：

# 标准 logging
logger.info("协议错误", extra={"clientip": "192.168.0.1", "user": "fbloggs"})

# Loguru
logger.bind(clientip="192.168.0.1", user="fbloggs").info("协议错误")

# 格式化时引用
fmt = "{time} {extra[clientip]} {extra[user]} {message}"

 替换 isEnabledFor() 方法

使用惰性求值优化性能：