【Python】Loguru库：轻量级、易操作且功能强大的日志工具库详解

loguru 是一个轻量、易用且功能强大的 Python 日志库，旨在简化日志记录。它提供了一个直观的 API，支持彩色日志输出、文件写入、异步日志、结构化日志等功能，相比 Python 标准库的 logging 模块，loguru 配置更简单，输出更美观，适合快速开发和复杂应用。

以下是对 loguru 库的详细介绍，包括其功能、用法和实际应用。

1. loguru 库的作用

简化日志记录：无需复杂配置，开箱即用。

彩色输出：支持终端彩色日志，便于调试。

灵活的日志目标：支持输出到终端、文件、数据库等。

异步支持：异步写入日志，适合高并发应用。

结构化日志：支持 JSON 或自定义格式，方便日志解析。

异常追踪：自动捕获并格式化异常堆栈信息。

上下文支持：动态添加上下文信息（如用户 ID、请求 ID）。

2. 安装与环境要求

Python 版本：支持 Python 3.5+（推荐 3.8+）。

依赖：无强制依赖，可选依赖：

colorama：Windows 下的彩色输出。

aiologger：异步日志支持。

安装命令：

pip install loguru

验证安装：

from loguru import logger
print(logger.__version__)  # 示例输出: 0.7.2

3. 核心功能与用法

loguru 的核心是 logger 对象，提供简单的方法（如 info、debug、error）记录日志。以下是主要功能和示例。

3.1 基本日志记录

使用默认 logger 记录日志，无需配置。

from loguru import logger

logger.debug("This is a debug message")
logger.info("This is an info message")
logger.warning("This is a warning")
logger.error("This is an error")

输出示例（终端，带颜色）：

2025-05-07 12:34:56.123 | DEBUG    | __main__:<module>:3 - This is a debug message
2025-05-07 12:34:56.124 | INFO     | __main__:<module>:4 - This is an info message
2025-05-07 12:34:56.124 | WARNING  | __main__:<module>:5 - This is a warning
2025-05-07 12:34:56.125 | ERROR    | __main__:<module>:6 - This is an error

说明：

默认输出到终端，包含时间、级别、模块名、行号和消息。

颜色根据日志级别区分（DEBUG 蓝色，ERROR 红色等）。

3.2 日志级别

支持多种日志级别：TRACE、DEBUG、INFO、SUCCESS、WARNING、ERROR、CRITICAL。

logger.trace("Detailed tracing")
logger.success("Operation completed")
logger.critical("Critical error occurred")

说明：

默认级别为 DEBUG，可通过 logger.level 配置。

3.3 日志文件输出

将日志写入文件，支持轮换、压缩和保留。

from loguru import logger

# 添加文件输出
logger.add("app.log", rotation="500 MB", retention="10 days", compression="zip")

logger.info("This will be written to app.log")

说明：

rotation：日志文件大小或时间达到阈值时轮换（如 500 MB 或 1 week）。

retention：保留最近的文件（如 10 days 或 5 files）。

compression：支持 zip、gz 等格式压缩旧日志。

3.4 格式化日志

自定义日志格式，使用 {} 占位符。

logger.add(
    "custom.log",
    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}",
    level="INFO"
)

logger.info("Custom format log")

输出示例（custom.log）：

2025-05-07 12:34:56 | INFO | Custom format log

说明：

支持 {time}、 {level}、 {message}、 {file}、 {line} 等占位符。

time 格式支持 Python 的 strftime 语法。

3.5 异常追踪

自动捕获并格式化异常堆栈。

from loguru import logger

try:
    1 / 0
except ZeroDivisionError:
    logger.exception("An error occurred")

输出示例：

2025-05-07 12:34:56.123 | ERROR    | __main__:<module>:5 - An error occurred
Traceback (most recent call last):
  File "<stdin>", line 3, in <module>
ZeroDivisionError: division by zero

说明：

logger.exception 记录异常和完整堆栈信息。

3.6 上下文绑定

动态添加上下文信息（如用户 ID）。

from loguru import logger

# 绑定上下文
logger_with_user = logger.bind(user_id=123)
logger_with_user.info("User action")

# 动态上下文
logger.info("Processing request", request_id="abc123")

输出示例：

2025-05-07 12:34:56.123 | INFO     | __main__:<module>:4 - User action {'user_id': 123}
2025-05-07 12:34:56.124 | INFO     | __main__:<module>:6 - Processing request {'request_id': 'abc123'}

说明：

bind 创建带固定上下文的 logger。

上下文信息以字典形式附加到日志。

3.7 异步日志

支持异步写入，适合高并发应用。

from loguru import logger

logger.add("async.log", enqueue=True, level="INFO")
logger.info("This is written asynchronously")

说明：

enqueue=True 将日志写入任务放入队列，由后台线程处理。

减少主线程阻塞，提高性能。

3.8 结构化日志（JSON）

输出 JSON 格式日志，便于解析。

from loguru import logger

logger.add(
    "json.log",
    serialize=True,
    format="{time} | {level} | {message} | {extra}"
)
logger.bind(data={"key": "value"}).info("Structured log")

输出示例（json.log）：

{"time": "2025-05-07T12:34:56.123456+00:00", "level": "INFO", "message": "Structured log", "extra": {"data": {"key": "value"}}}

说明：

serialize=True 输出 JSON 格式。

适合与日志分析工具（如 ELK、Loki）集成。

3.9 移除日志目标

动态移除日志输出。

from loguru import logger

sink_id = logger.add("temp.log")
logger.info("This goes to temp.log")
logger.remove(sink_id)
logger.info("This only goes to console")

说明：

add 返回 sink ID，可通过 remove 删除。

4. 性能与特点

高效性：异步和多线程支持，适合高负载场景。

易用性：比 logging 配置简单，默认输出美观。

灵活性：支持多种输出目标、格式和上下文。

局限性：

非标准库，可能增加项目依赖。

高级配置（如动态级别切换）需额外实现。

跨平台：Windows 下需 colorama 支持彩色输出。

5. 实际应用场景

Web 应用：记录请求信息、错误和性能指标。

数据管道：跟踪数据处理流程和异常。

机器学习：记录模型训练过程中的参数和损失。

微服务：生成结构化日志，集成到日志系统（如 ELK）。

调试工具：快速添加调试日志，分析程序行为。

示例（FastAPI 集成）：

from fastapi import FastAPI
from loguru import logger
import uvicorn

app = FastAPI()

@app.get("/hello")
async def hello(name: str):
    logger_with_context = logger.bind(user=name)
    logger_with_context.info("Processing request")
    try:
        if not name:
            raise ValueError("Name is empty")
        return {"message": f"Hello, {name}!"}
    except Exception as e:
        logger_with_context.exception("Request failed")
        raise

if __name__ == "__main__":
    logger.add("api.log", rotation="1 MB", retention="7 days")
    uvicorn.run(app, host="0.0.0.0", port=8000)

输出示例（api.log）：

2025-05-07 12:34:56.123 | INFO     | __main__:hello:7 - Processing request {'user': 'Alice'}

说明：

记录每个请求的上下文和异常。

日志文件自动轮换和保留。

6. 与 logging 模块对比

特性	loguru	logging
配置难度	简单，开箱即用	需手动配置
默认输出	彩色、格式美观	纯文本，需格式化
异步支持	原生支持	需额外实现
结构化日志	支持 JSON	需自定义
依赖	外部库	标准库
生态集成	较新，社区扩展少	广泛支持

迁移建议：

小型项目或快速开发：选择 loguru。

企业项目或需深度集成：考虑 logging 或结合两者。

7. 注意事项

日志级别：

默认记录 DEBUG 及以上级别，生产环境建议设为 INFO：

logger.add("prod.log", level="INFO")

性能：

异步日志（enqueue=True）适合高并发，但可能延迟写入。

避免在循环中频繁绑定上下文，影响性能。

文件管理：

定期检查日志文件大小，配置 rotation 和 retention。

确保写入路径有权限。

Windows 彩色输出：

安装 colorama：

pip install colorama

版本兼容性：

最新版本（截至 2025，0.7.2）稳定，推荐使用。

检查依赖（如 colorama）版本。

8. 综合示例

以下是一个综合示例，展示文件输出、异步日志、结构化日志和异常处理：

from loguru import logger
import sys
import asyncio

# 配置日志
logger.remove()  # 移除默认终端输出
logger.add(sys.stderr, level="DEBUG", format="{time} | {level} | {message}")
logger.add(
    "app.log",
    level="INFO",
    rotation="1 MB",
    retention="7 days",
    compression="zip",
    enqueue=True,
    serialize=True
)

async def process_task(task_id):
    logger_with_task = logger.bind(task_id=task_id)
    logger_with_task.info("Starting task")
    try:
        if task_id % 2 == 0:
            raise ValueError("Invalid task ID")
        await asyncio.sleep(1)
        logger_with_task.success("Task completed")
    except Exception as e:
        logger_with_task.exception("Task failed")
        raise

async def main():
    tasks = [process_task(i) for i in range(3)]
    await asyncio.gather(*tasks, return_exceptions=True)

if __name__ == "__main__":
    logger.info("Application started")
    asyncio.run(main())
    logger.info("Application finished")

输出示例（终端）：

2025-05-07T12:34:56.123456 | INFO     | Application started
2025-05-07T12:34:56.124456 | INFO     | Starting task {'task_id': 0}
2025-05-07T12:34:56.124456 | ERROR    | Task failed {'task_id': 0}
Traceback (most recent call last):
  File "...", line 15, in process_task
ValueError: Invalid task ID
2025-05-07T12:34:56.124456 | INFO     | Starting task {'task_id': 1}
2025-05-07T12:34:57.124456 | SUCCESS  | Task completed {'task_id': 1}
2025-05-07T12:34:57.124456 | INFO     | Application finished

输出示例（app.log，JSON 格式）：

{"text": "2025-05-07T12:34:56.123456 | INFO     | Application started","record": {...}}
{"text": "2025-05-07T12:34:56.124456 | INFO     | Starting task {'task_id': 0}","record": {...}}

说明：

配置终端和文件输出（JSON 格式）。

异步处理任务，记录上下文和异常。

日志文件支持轮换和压缩。