Loguru 配置与使用

Loguru 是 Python 中一个轻量级、功能强大的日志库，致力于让日志记录变得更简单。相比 Python 的内置日志模块 logging，Loguru 更易于配置，支持链式调用、颜色高亮和日志分级等丰富功能。

安装与使用

pip install loguru

loguru 不用像 logging 那样做很多配置操作，直接从 loguru 导入 logger 即可，需要注意的是，此 logger 是经过实例化后的全局唯一 logger 对象，意味着即使创建多个 logger 对象最终也是写入到这个全局的 logger 中。

from loguru import logger

logger.info("hello world")

详细用法

from loguru import logger


def main():
    # 自定义日志格式，指定 level 宽度为 8
    log_format = "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<8} | {name}:{function}:{line} - {message}"

    # 文件输出
    logger.add(
        sink="logs/log_{time}.log",
        format=log_format,  # 日志显示格式
        rotation='500 MB',  # 日志文件最大限制 500mb
        retention="7 days",  # 最长保留 7 天
        compression="zip",  # 压缩形式保存
        encoding='utf-8',  # 编码
        level="INFO",  # 日志级别
    )
    logger.debug("debug log")
    logger.info("info log")
    logger.warning("warning log")
    logger.error("error log")
    logger.critical("critical log")


if __name__ == '__main__':
    main()

运行之后日志内容如下

filename: log_xxx.log
2025-07-20 22:18:42.047 | INFO     | __main__:main:21 - info log
2025-07-20 22:18:42.048 | WARNING  | __main__:main:22 - warning log
2025-07-20 22:18:42.048 | ERROR    | __main__:main:23 - error log
2025-07-20 22:18:42.048 | CRITICAL | __main__:main:24 - critical log

add 方法参数说明

参数	值	含义
sink	文件对象/字符串/Path对象/日志handler	负责接收格式化的日志并输出到相应对象
format	如："{time} {level} {message}"	自定义日志格式
rotation	如：500 MB、1 week、00:00	超过设定的规则上限就会创建另一份日志
retention	1 week、30 days、2 months	超过存储时间就会清空
level	INFO、DEBUG、ERROR 等	日志级别
compression	"zip"、"tar.gz"、"gz"、"tar"等	压缩格式（日志文件很大时可以节省空间）
serialize	bool 类型	为 True 表示将日志序列化成 JSON 格式

logger.add 方法常用配置参数说明

• sink：日志输出的目标，可以是文件路径（字符串）、sys.stdout（控制台）、sys.stderr等。
• level ：设置日志的最低等级，只有大于等于该等级的日志才会输出。支持的日志等级包括 TRACE、DEBUG、INFO、WARNING、ERROR、CRITICAL。
• format：日志的输出格式，支持通过 {} 占位符指定内容，如 {time}、{level}、{message} 等。可以通过指定宽度和对齐方式来控制字段的显示格式。
• rotation：日志轮转条件，可以是以下之一：
  • 时间间隔：如 "1 day" 表示每日轮转，"1 week" 表示每周轮转。
  • 文件大小：如 "500 MB" 表示当日志文件超过 500MB 时自动轮转。
  • 自定义函数：自定义判断条件函数，每次写入前都会执行此函数来决定是否轮转。
• retention：日志保留策略，用于自动清理旧日志文件。可以是时间间隔（如 "7 days"）或自定义函数，满足条件的日志文件会被删除。
• enqueue：布尔值，True 表示使用队列在单独线程中异步写入日志，适合多线程或多进程环境，避免竞争条件。
• serialize：布尔值，True 表示将日志序列化为 JSON 格式，便于结构化存储和分析。适用于 JSON 日志分析工具。
• backtrace：布尔值，True 时在异常日志中显示完整回溯信息，包括导致错误的初始位置，适用于调试复杂错误。
• diagnose：布尔值，True 时会在异常回溯中显示更多调试信息，比如局部变量值。一般在开发和调试阶段启用。
• catch：布尔值，True 时会捕获和记录 sink 中的任何异常，而不会中断应用程序。
• filter ：可以是字典或函数，用于过滤日志输出。可以针对特定模块或函数设置不同的日志策略。例如：filter={"module_name": "INFO"} 表示该模块只记录 INFO 及以上级别的日志。
• colorize：布尔值，True 时在控制台启用彩色日志输出（仅适用于控制台输出），帮助快速区分日志等级。

API 文档参考：https://loguru.readthedocs.io/en/stable/api/logger.html

关于日志严重程度等级排序

evel name	Severity value	Logger method
TRACE	5	logger.trace()
DEBUG	10	logger.debug()
INFO	20	logger.info()
SUCCESS	25	logger.success()
WARNING	30	logger.warning()
ERROR	40	logger.error()
CRITICAL	50	logger.critical()

filter

现在有这样一个需求：我想把错误日志输出到 error.log 中，消息包含 hello 的输出到 hello.log 中，那么我们可以使用 filter 来过滤

from loguru import logger

logger.add('logs/service.log', encoding="utf-8")
logger.add('logs/error.log', encoding="utf-8", filter=lambda x: 'ERROR' in str(x['level']).upper())
logger.add('logs/hello.log', encoding="utf-8", filter=lambda x: 'hello' in str(x['message']))

logger.debug("详细调试信息")
logger.error("错误信息")
logger.info("普通信息")
logger.error("hello world")

filename: error.log
2025-07-20 22:26:56.834 | ERROR    | __main__:<module>:8 - 错误信息
2025-07-20 22:26:56.834 | ERROR    | __main__:<module>:10 - hello world

filename: hello.log
2025-07-20 22:26:56.834 | ERROR    | __main__:<module>:10 - hello world

filename: service.log
2025-07-20 22:26:56.834 | DEBUG    | __main__:<module>:7 - 详细调试信息
2025-07-20 22:26:56.834 | ERROR    | __main__:<module>:8 - 错误信息
2025-07-20 22:26:56.834 | INFO     | __main__:<module>:9 - 普通信息
2025-07-20 22:26:56.834 | ERROR    | __main__:<module>:10 - hello world

import logging
from loguru import logger

# 项目日志配置
console_log_level = logging.DEBUG
trace_msg_log_format = "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<8} | {trace_msg} | {name}:{function}:{line} - {message}"
default_log_format = "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<8} | {name}:{function}:{line} - {message}"
console_log_format = ("<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
                      "<level>{level:<8}</level> | "
                      "<level>{name}:{function}:{line} - {message}</level>")
log_format = "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<8} | {name}:{function}:{line} - {message}"

"""
这里设置了三个日志输出 sink，分别是

- 控制台：日志等级 `debug` 及以上
- 服务日志文件：日志等级 `INFO` 及以上
  - 日志文件最长保留 7 天
  - 每天 0 点新创建一个 log 文件
- 服务错误日志：日志等级 `Error` 及以上
  - 日志文件最长保留 30 天
  - 超过 10 MB 就自动新建文件扩充
"""


## 配置案例

def setup_logging():
    """
    配置项目日志信息：

    Returns:
        None
    """
    logging_conf = {
        "console_handler": {
            "level": console_log_level,
            "format": console_log_format
        },
        "server_handler": {
            "sink": "logs/server.log",
            "level": "INFO",
            "rotation": "00:00",  # 项目服务综合日志滚动配置（每天 0 点新创建一个 log 文件）
            "retention": "7 days",  # 综合日志文件最长保留 7 天
            "enqueue": True,
            "backtrace": False,
            "diagnose": False,
            "format": log_format
        },
        "error_handler": {
            "sink": "logs/error.log",
            "level": "ERROR",
            "rotation": "10 MB",  # 错误日志 超过 10 MB 就自动新建文件扩充
            "retention": "30 days",  # 错误日志保存 30 天
            "enqueue": True,
            "backtrace": True,
            "diagnose": True,
            "format": log_format
        },
    }

    for log_handler, _log_conf in logging_conf.items():
        logger.add(**_log_conf)

    logger.info("setup logging success")

这里设置了三个日志输出 sink，分别是

• 控制台：日志等级 debug 及以上
• 服务日志文件：日志等级 INFO 及以上
  • 日志文件最长保留 7 天
  • 每天 0 点新创建一个 log 文件
• 服务错误日志：日志等级 Error 及以上
  • 日志文件最长保留 30 天
  • 超过 10 MB 就自动新建文件扩充

参考

• https://github.com/Delgan/loguru
• https://loguru.readthedocs.io/en/stable/overview.html
• https://juejin.cn/post/7433636476005040179
• https://juejin.cn/post/7156589053968646151