【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__::3 - This is a debug message
2025-05-07 12:34:56.124 | INFO     | __main__::4 - This is an info message
2025-05-07 12:34:56.124 | WARNING  | __main__::5 - This is a warning
2025-05-07 12:34:56.125 | ERROR    | __main__::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__::5 - An error occurred
Traceback (most recent call last):
  File "", line 3, in 
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__::4 - User action {'user_id': 123}
2025-05-07 12:34:56.124 | INFO     | __main__::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 格式）。
• 异步处理任务，记录上下文和异常。
• 日志文件支持轮换和压缩。

---

9. 资源与文档

• 官方文档：https://loguru.readthedocs.io/
• GitHub 仓库：https://github.com/Delgan/loguru
• PyPI 页面：https://pypi.org/project/loguru/
• 教程：
  • Loguru 官方指南：https://loguru.readthedocs.io/en/stable/overview.html
  • Real Python 的日志教程：https://realpython.com/python-logging/