异步日志库loguru

Frankie.Lee2024年10月28日大约 6 分钟

异步日志库loguru

1. 引言

在编写调试Python代码过程中，我们经常需要记录日志，通常我们会采用python自带的内置标准库logging，但是使用该库，配置较为繁琐。为了提升编程效率，本文重点介绍最近发现的一个宝藏第三方日志库Loguru，该库名字来自于印度语，含义为日志大师。
我们先来做个直观的对比，来说明Loguru的优雅之处。使用python自带的logging，样例代码如下：

样例输出如下：

使用Loguru库，样例代码如下：

使用Loguru输出日志，终端执行后出现带颜色的日志，而且使用超级方便。

2. 安装loguru

直接使用pip进行安装即可，命令如下：

pip install loguru

输出到终端使用方式：

from loguru import logger
logger.debug("msg msg msg!")

输出到文件使用方式：

from loguru import logger
logger.add("file_name.log")
logger.debug("msg msg msg!")

3. 特性

参考官方github，里面给出了Loguru库丰富的特性，这里挑选几个重要的特性进行讲解

- logger.add参数说明
- sink
    - 可以传入类file对象，如sys.stderr或者open('test.log', 'w')。
    - 可以传入文件路径str或pathlib，如示例代码中的写入日志文件路径。路径可以使用一些附加参数对其进行参数化，如test_{time}.log，{time}即时间参数，创建文件时文件名称中会加入时间。
    - 可以传入像lambda这样的可调用函数的简单函数，如lambda msg:print(msg)。这允许完全由用户偏好和需求定义日志记录过程。
    - 可以是使用async def语句定义的异步协程函数。该函数返回的协程对象将使用loop.create_task()添加到事件循环中。在使用complete()	结束循环之前，应该等待这些任务。
    - 也支持传入logging模块的Handler，如FileHandler、StreamHandler等，Loguru记录会自动转换为日志模块预期的结构。
- level：发送到sink的日志消息的最低日志级别，即输出的最低日志级别。
- format：定义日志的输出格式。
- filter：过滤日志。
- colorize：终端日志输出的颜色。
- serializer：bool值，输出日志时是否先格式化成JSON数据格式。
- backtrace：bool值，是否进行异常跟踪（即backtrace信息记录）。
- diagnose：bool值，异常跟踪是否应显示变量值以简化调试。在生产中应将其设置为False，以避免泄漏敏感数据。
- enqueue：bool值，日志消息输出之前是否先通过多进程安全队列，多进程多线程运行写入日志时需用到，避免日志记录丢失或混乱。
- catch：bool值，是否自动捕获接收器处理日志消息时发生的错误。如果为True，则在sys上显示异常消息。

1. 开箱即用

Loguru库设计的初衷就在于追求有且仅有一个logger，为了使用方便，提前预置输出样式。如果需要打印日志仅需采取如下方式：

from loguru import logger
logger.debug("That's it, beautiful and simple logging!")

2. 无需初始化，导入函数即可使用

在Loguru中，我们如何自定义输出样式？如何过滤输出信息？如何设置日志级别？
- 答案是调用 add() 函数

import sys
from loguru import logger
logger.add(sys.stderr, format="{time} {level} {message}", filter="my_module", level="INFO")
logger.info("Hello, World!")

示例如下：

from loguru import logger
logger.add("info.log", format="{time} {level} {message}", filter="", level="INFO")
logger.debug("This is a debug msg")
logger.info("This is a info msg")

查看info.log，结果如下:

3. 更容易的文件日志记录与转存/保留/压缩方式

可以通过简单的配置，来让日志保存更加人性化。比如我们想要删除老的日志，或者我们希望自动压缩保存好的日志，可以参考一下命令：

logger.add("file_1.log", rotation="500 MB")    # 文件过大（超过500M）就会重新生成一个文件
logger.add("file_2.log", rotation="12:00")     # 每天12点创建新文件
logger.add("file_3.log", rotation="1 week")    # 文件时间过长就会创建新文件
logger.add("file_4.log", retention="10 days")  # 一段时间后会清空
logger.add("file_5.log", compression="zip")    # 保存zip格式

4. 更优雅的字符串格式化输出

Loguru库对字符串的处理功能更加强大，字符串格式化输出支持{} 来替换%，功能类似于str.format()

# 格式化
logger.info("If you're using Python {}, prefer {feature} of course!", 3.6, feature="f-strings")
# 控制台输出序列化日志信息便于后续配置引用
logger.add(sys.stderr, serialize=True)     
# 根据上面的序列化参数，进行配置日志输出结构
logger.add(sys.stderr, format="{time:YYYY-MM-DD HH:mm:ss}|{level}|{module}:{line}|processId:{process}|threadId:{thread}: {message}")

5. 可以在线程或主线程中捕获异常

我们经常会遇到代码出现crash时，我们在log里看不到任何错误的信息。在Loguru库中，可以通过 @logger.catch 装饰器来确保发生异常时，将错误信息保存下来。

示例如下

@logger.catch
def main(x, y, z):
    return x * y / z

res = main(1,2,0)
print(res)

6. 可以支持自定义颜色

Loguru 是支持自定义颜色的，如果你不喜欢它默认的颜色，可以这么改：

logger.add(sys.stdout, colorize=True, format="<green>{time}</green> <level>{message}</level>")

7. 支持异步，且线程和多进程安全

Loguru 默认情况下是线程安全的，但它不是多进程安全的。不过如果你需要多进程/异步记录日志，它也能支持，只需要添加一个 enqueue 参数：

logger.add("somefile.log", enqueue=True)

8. 支持异常完整性描述（支持Backtrace（回溯））

对于日志而言，没有错误堆栈的日志是没有灵魂的。Loguru 允许显示整个堆栈信息来帮助你发现问题（包括变量）。

logger.add("out.log", backtrace=True, diagnose=True)  # 默认可不填写此参数，需要注意内容泄露

def func(a, b):
    return a / b

def nested(c):
    try:
        func(5, c)
    except ZeroDivisionError:
        logger.exception("What?!")

nested(0)

运行结果如下

9. 更好的日期时间处理

我们可以自定义日期输出样式，如下所示：

logger.add("file.log", format="{time:YYYY-MM-DD at HH:mm:ss} | {level} | {message}")  # 定义日期样式

10. 支持邮件通知

Loguru 可以和强大的邮件通知模块 notifiers 库结合使用，以在程序意外失败时接收电子邮件，或发送许多其他类型的通知。

import notifiers

params = {
    "username": "you@gmail.com",
    "password": "abc123",
    "to": "dest@gmail.com"
}

# 初始化时发送一封邮件
notifier = notifiers.get_notifier("gmail")
notifier.notify(message="The application is running!", **params)

# 发生Error时，发邮件进行告警
from notifiers.logging import NotificationHandler

handler = NotificationHandler("gmail", defaults=params)
logger.add(handler, level="ERROR")

这样配置之后，每次产生 Error 日志，程序都会自动向你的邮箱发送告知邮件，真的是足够人性化了。

4. 总结

本文对Loguru库相关主要特性进行了简要概述，如果需要了解其更详细的特性说明，可参考官方github。

推荐大家在日常生活中多多使用Loguru库进行日志处理工作。

loguru官方网站: https://loguru.readthedocs.io/en/stable/index.html api文档: https://loguru.readthedocs.io/en/stable/api.html 项目地址：https://github.com/Delgan/loguru