Python loguru 库：替代logging的懒人神器，轻松实现日志记录与轮转

相信很多人对于日志记录又爱又恨，爱的是它确实能够帮助我们在故障时溯源，找到问题的根本原因；恨的是它的配置繁杂，特别是Python标准库logging的配置语法，往往用一次忘一次。

如果你也像我一样，每次新开一个项目，都得重新查阅一遍logging的配置文档，那么这个名为 loguru 的第三方Python库绝对值得一试。它简化了绝大部分日常日志需求，开箱即用，堪称“懒人”开发者的福音。

一、loguru 是什么？

loguru 是一个旨在让 Python 日志记录变得简单愉快的第三方库。它几乎能覆盖标准库 logging 的所有核心功能，并且内置了线程与进程安全的保证。其默认输出格式就非常实用，包含了时间戳、日志级别、模块路径、行号以及日志内容，在终端中还会用不同颜色高亮显示，阅读体验极佳。

二、如何安装

安装 loguru 非常简单，直接使用 pip 命令即可：

pip install loguru

三、官方文档

详细的功能和API说明，请参考其官方文档：https://loguru.readthedocs.io/en/stable/index.html

四、基础与进阶用法

4.1 最简单的日志输出

无需任何配置，导入即可记录日志。

from loguru import logger

logger.debug('这是一条调试信息')

运行上述代码，日志会直接打印到控制台，效果如下图所示：

4.2 将日志写入文件

只需一个 add() 方法，就能轻松地将日志输出到文件。

from loguru import logger

# 添加一个文件接收器，日志将写入`my_app_log.log`文件
logger.add('my_app_log.log')
logger.debug('调试信息')

执行后，当前目录下会生成 my_app_log.log 文件：

文件内容如下图所示，格式清晰：

4.3 五种日志级别

与常见日志库一样，loguru 也支持从调试到严重错误的不同级别，并在控制台以不同颜色区分。

from loguru import logger

logger.debug('调试级别')
logger.info('信息级别')
logger.warning('警告级别')
logger.error('错误级别')
logger.critical('严重级别')

运行效果如下：

4.4 日志文件轮转

为了避免单个日志文件无限增大，必须进行文件轮转。loguru 通过 rotation 参数轻松实现。

from loguru import logger

# 每天凌晨 00:00 创建一个新的日志文件
logger.add('my_app_log_{time}.log', rotation='00:00')

提示：文件名中的 {time} 占位符可以自动替换为时间，方便区分不同时间段的文件。

rotation 的规则非常灵活，除了按时间，还可以：

• 按文件大小：例如 ‘100 MB’、‘0.5 GB’
• 按时间周期：例如 ‘1 week’、‘1 month 2 weeks’

4.5 日志文件压缩

轮转产生大量文件后，可以考虑启用压缩功能，使用 compression 参数。

from loguru import logger

# 每天轮转，并将旧日志文件压缩为zip格式
logger.add('my_app_log_{time}.log', rotation='00:00', compression='zip')

支持的压缩格式包括 “gz”、“bz2”、“xz”、“zip” 等。

4.6 日志留存策略

没必要永久保留所有历史日志，可以使用 retention 参数自动清理旧文件。

from loguru import logger
import datetime

# 策略1：只保留最近15天的日志文件
logger.add('my_app_log_{time}.log', retention='15 days')
# 策略2：只保留最近10个日志文件
logger.add('my_app_log_{time}.log', retention='10')
# 策略3：只保留最近5小时的日志（使用timedelta对象）
logger.add('my_app_log_{time}.log', retention=datetime.timedelta(hours=5))

4.7 输出结构化JSON日志

对于需要接入 ELK 等日志分析系统的场景，可以输出格式化的 JSON 日志。

from loguru import logger

logger.add('my_app_log.log', serialize=True, encoding='utf-8')
logger.debug('调试')

输出的日志将变成单行JSON格式，便于解析：

4.8 多进程安全写入

虽然 loguru 默认线程安全，但在多进程环境下，为了保证日志写入不混乱，建议启用 enqueue 参数。

from loguru import logger

logger.add('my_app_log.log', enqueue=True)
logger.debug('调试')

这个设置对于使用多进程模型的应用（例如某些 运维/DevOps/SRE 脚本或Web服务器）非常关键，能确保日志的完整性和有序性。

五、总结

以上就是 loguru 库应对日常开发中绝大多数日志需求的用法。可以看到，它通过高度封装的API，将原本繁琐的配置简化为几个直观的参数，极大地提升了开发效率和体验。

如果你也厌倦了反复查询 logging 的复杂配置，不妨在下一个Python项目中尝试一下 loguru，它或许能成为你工具箱中又一个趁手的“懒人”神器。更多高级功能和详细配置，欢迎查阅其官方文档进行探索。

希望这篇分享对你有帮助！也欢迎来云栈社区交流更多开发心得和实用工具。