Loguru 简易入门

简易入门

一、简易应用

from loguru import logger
# 如果与工程中原有的 logger 重名，可设定一个别名
from loguru import logger as mylogger

# 同步保存日志到文件
logger.add('runtime.log')

logger.debug('this is a debug message')
logger.info('this is info message')
logger.warning('this is warning message')
logger.error('this is error message')
logger.info('this is info message')
logger.success('this is success message!')
logger.critical('this is critical message!')

二、add方法

def add(
        self,
        sink,
        *,
        level=_defaults.LOGURU_LEVEL,
        format=_defaults.LOGURU_FORMAT,
        filter=_defaults.LOGURU_FILTER,
        colorize=_defaults.LOGURU_COLORIZE,
        serialize=_defaults.LOGURU_SERIALIZE,
        backtrace=_defaults.LOGURU_BACKTRACE,
        diagnose=_defaults.LOGURU_DIAGNOSE,
        enqueue=_defaults.LOGURU_ENQUEUE,
        catch=_defaults.LOGURU_CATCH,
        **kwargs
    ):
    pass

skin参数可以传入多种不同的数据结构，如下：

• sink 可以传入一个 file 对象，例如 sys.stderr 或者 open('file.log', 'w') 都可以。
• sink 可以直接传入一个 str 字符串或者 pathlib.Path 对象，其实就是代表文件路径的，如果识别到是这种类型，它会自动创建对应路径的日志文件并将日志输出进去。
• sink 可以是一个方法，可以自行定义输出实现。
• sink 可以是一个 logging 模块的 Handler，比如 FileHandler、StreamHandler 等等，或者上文中我们提到的 CMRESHandler 照样也是可以的，这样就可以实现自定义 Handler 的配置。
• sink 还可以是一个自定义的类，具体的实现规范可以参见官方文档。https://loguru.readthedocs.io/en/stable/api/logger.html#sink

其他参数例如 format、filter、level 等等。其实它们的概念和格式和 logging 模块都是基本一样的了，例如这里使用 format、filter、level 来规定输出的格式：

logger.add('runtime.log', format="{time} {level} {message}", filter="my_module", level="INFO"，encoding="utf-8")

三、rotation 配置

# log文件超过500M时会新建一个log文件，日志文件名自动以创建时间命名
logger.add('runtime_{time}.log', rotation="500 MB")  

# 每天0点新建一个log文件
logger.add('runtime_{time}.log', rotation='00:00') 

#每隔一周创建一个 log 文件
logger.add('runtime_{time}.log', rotation='1 week') 

四、retention 配置

很多情况下，一些非常久远的 log 对我们来说并没有什么用处了，它白白占据了一些存储空间，不清除掉就会非常浪费。retention 这个参数可以配置日志的最长保留时间。

logger.add('runtime.log', retention='10 days') # 保留最新10天的log

五、compression 配置

loguru 还可以配置文件的压缩格式，比如使用 zip 文件格式保存，示例如下：

logger.add('runtime.log', compression='zip') # 使用zip文件格式保存

六、异常捕获

对函数使用 @logger.catch 装饰器，当函数执行时如果发生异常，loguru 将自动捕获该异常并记录到日志；未触发异常时则不会记录日志。

@logger.catch
def my_function(x, y, z):
    # An error? It's caught anyway!
    return 1 / (x + y + z)

提高篇

日志级别

from loguru import logger

# 五种日志级别，自动着色，等级由低到高
logger.debug("这是一条调试信息")
logger.info("服务器启动成功")
logger.success("任务处理完成 🎉")
logger.warning("磁盘空间不足 80%")
logger.error("数据库连接失败")

# 自动输出到 stderr，带颜色、时间、模块名
# 输出：2026-05-25 08:00:00.123 | INFO     | __main__:module:5 - 服务器启动成功

完全没有 logging.getLogger()、setLevel()、addHandler() 这些繁琐步骤，导入即用。

配置输出目标（add / remove）

loguru 的核心 API 是 logger.add() 和 logger.remove()：

from loguru import logger

# 默认输出到 stderr（彩色），但我们可以：

# 写入文件，每天一个，保留 7 天
logger.add("app_{time:YYYY-MM-DD}.log",
           rotation="1 day",
           retention="7 days",
           level="INFO")

# 错误日志单独存
logger.add("error_{time:YYYY-MM-DD}.log",
           rotation="1 day",
           retention="30 days",
           level="ERROR")

# 控制台也保留（默认就是 stderr，不需要重复 add）
# 如果想清掉默认的 stderr 输出：
# logger.remove()  # 移除所有 handler
# logger.add(sys.stderr, level="WARNING")  # 只输出 WARNING 以上

日志旋转（rotation）与保留（retention）

loguru 的旋转策略非常灵活：

from loguru import logger

# 按文件大小旋转：超过 100MB 自动归档
logger.add("app.log", rotation="100 MB")

# 按时间旋转
logger.add("app.log", rotation="1 day")       # 每天
logger.add("app.log", rotation="1 week")      # 每周
logger.add("app.log", rotation="12:00")       # 每天中午 12 点

# 保留策略
logger.add("app.log", retention="10 days")    # 保留 10 天
logger.add("app.log", retention=5)            # 保留 5 个文件
logger.add("app.log", retention="1 month")    # 保留 1 个月

# 压缩归档
logger.add("app_{time}.log.gz", rotation="1 day", compression="gz")
logger.add("app_{time}.zip", rotation="1 day", compression="zip")

# 异步写入（高并发场景推荐）
logger.add("app.log", enqueue=True)  # 使用线程安全队列，非阻塞

日志格式化

from loguru import logger

# 自定义格式（使用 {extra} 字典）
logger.add("app.log", format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}")

# 带模块名、行号
logger.add("app.log",
    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
           "<level>{level: <8}</level> | "
           "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
           "<level>{message}</level>")

# 使用颜色标签
logger.add("app.log",
    colorize=True,
    format="<red>{level}</red> - <green>{message}</green>")

异常追溯（Backtrace）

loguru 的异常捕获能力远超标准库：

from loguru import logger

# 方式一：catch 装饰器 —— 自动捕获函数内所有异常
@logger.catch
def divide(a, b):
    return a / b

divide(1, 0)  # 会被 loguru 捕获，输出完整的变量状态

# 方式二：在 except 块中记录
try:
    result = 1 / 0
except ZeroDivisionError:
    logger.exception("计算失败")  # 自动记录完整 traceback

# 方式三：强制显示变量值（最强大的功能！）
@logger.catch
def complex_calc(x, y, z):
    temp = x * y
    result = temp / z  # 如果 z=0，错误输出会显示所有局部变量值
    return result

complex_calc(10, 20, 0)
# 输出会包含：x=10, y=20, z=0, temp=200

绑定上下文（bind / contextualize）

from loguru import logger

# 绑定固定字段（如请求 ID）
logger_with_user = logger.bind(user_id=12345, request_id="abc-def")
logger_with_user.info("用户登录成功")
# 输出会包含 user_id=12345 和 request_id=abc-def

# 上下文管理器 —— 自动绑定和清理
def handle_request(user_id):
    with logger.contextualize(user_id=user_id):
        logger.info("开始处理请求")
        do_work()
        logger.info("请求处理完成")
    # 离开 with 块后自动清除 user_id 上下文

# 绑定字段非常适合与结构化日志配合
logger.add("app.json", format="{extra[user_id]} - {message}")
logger.bind(user_id=42).info("数据库查询完成")

结构化日志（JSON 输出）

适合日志分析平台（ELK、Datadog 等）：

from loguru import logger
import sys

# 移除默认 handler
logger.remove()

# 添加 JSON 格式输出
logger.add(sys.stdout, serialize=True)

# 或输出到文件
logger.add("structured.log", serialize=True)

# 所有日志都会变成 JSON 行
logger.info("用户注册", user_id=1001, email="test@example.com")
# 输出: {"text": "用户注册", "record": {"level": "INFO", "time": ..., "extra": {"user_id": 1001, "email": "test@example.com"}}}

过滤与级别控制

from loguru import logger

# 按级别过滤
logger.add("app.log", level="WARNING")  # 只记录 WARNING 及以上

# 按模块名过滤
logger.add("app.log", filter=lambda record: "myapp" in record["name"])

# 按自定义函数过滤
def sensitive_filter(record):
    # 不记录敏感信息
    return "password" not in str(record["message"])

logger.add("app.log", filter=sensitive_filter)

# 动态修改级别
logger.disable("httpx")  # 关闭 httpx 库的日志
logger.enable("myapp")   # 只开启 myapp 的日志