Python日志库Loguru教程（最人性化的Python日志模块）

标题

Python日志库Loguru教程（最人性化的Python日志模块）

1. What：我们需要一个什么样的日志库

1. 可以区分不同类型的日志：正常，警告，错误，严重。
2. 可以配置指定的日志文件名称。
3. 可以配置指定的日志格式。
4. 可以把不同的日志类型写到不同的文件中。
5. 可以配置按照时间，文件大小等条件对日志文件进行滚动分割。
6. 支持异步写日志。
7. 支持线程安全和进程安全写入日志。
8. 可以方便的记录，支持python的string format格式。

2. Why：为什么选用loguru

python自带的logging模块，需要完成复杂的配置才能很好的使用，基本生产环境都需要进行二次包装。

loguru专门梳理了这方面的问题，可以通过简单直接的配置完成你的需求。

举一个简单的例子，默认输出到标准输出：

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

# hello.py
from loguru import logger

logger.info("Hello from loguru!")

执行：

代码语言：shell

复制

$ python hello.py
2021-07-21 12:16:59.394 | INFO     | __main__:<module>:4 - Hello from loguru!

输出到日志文件：

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

from loguru import logger

logger.remove(0)
logger.add("out.log")
logger.success("Written message to log file")

可以看到，使用loguru可以非常简单的记录日志，也很方便的写到日志文件中。默认的日志格式已经版喊了基本的时间日期，日志类型，模块名称，代码行数。

官方说，Loguru是一个旨在为Python带来愉悦的日志记录的库。在使用中可以让我们更加简便的使用日志功能，从而把精力放到要解决的问题上。

3. How：如何使用loguru

3.1 安装

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

pip install loguru

最简单的使用：

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

from loguru import logger

# 在标准输出里面输出一行debug日志
logger.debug("That's it, beautiful and simple logging!")

3.2 日志类型（Level）介绍

loguru提供了七层日志层级，或者说七种日志类型。

生产环境中，常常在不同场景下使用不用的日志类型，用于处理各种问题。

每种类型的日志有一个整数值，表示日志层级，我们成为log level no。

• TRACE (5): 用于记录程序执行路径的细节信息，以进行诊断。
• DEBUG (10): 开发人员使用该工具记录调试信息。
• INFO (20): 用于记录描述程序正常操作的信息消息。
• SUCCESS (25): 类似于INFO，用于指示操作成功的情况。
• WARNING (30): 警告类型，用于指示可能需要进一步调查的不寻常事件。
• ERROR (40): 错误类型，用于记录影响特定操作的错误条件。
• CRITICAL (50): 严重类型，用于记录阻止核心功能正常工作的错误条件。

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

logger.trace("A trace message.")
logger.debug("A debug message.")
logger.info("An info message.")
logger.success("A success message.")
logger.warning("A warning message.")
logger.error("An error message.")
logger.critical("A critical message.")

输出如下：

代码语言：shell

复制

2022-08-10 11:58:33.224 | DEBUG | __main__:<module>:12 - A debug message.
2022-08-10 11:58:33.224 | INFO | __main__:<module>:13 - An info message.
2022-08-10 11:58:33.225 | SUCCESS | __main__:<module>:14 - A success message.
2022-08-10 11:58:33.226 | WARNING | __main__:<module>:15 - A warning message.
2022-08-10 11:58:33.226 | ERROR | __main__:<module>:16 - An error message.
2022-08-10 11:58:33.227 | CRITICAL | __main__:<module>:17 - A critical message.

如果你在linux的终端上，可以看到不同类型的日志，已经有不同的颜色加以区分，默认的配置已经很方便的让我们识别和使用了。

请注意，上述输出不包括TRACE级别的日志信息。这是因为Loguru默认使用DEBUG作为其最低日志级别，导致任何严重性低于DEBUG的日志信息都会被忽略。

如果您想更改默认级别，可以使用下面所示的add()方法的级别参数：

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

import sys
from loguru import logger

logger.remove(0)
logger.add(sys.stderr, level="INFO")

remove()方法被首先调用，以删除默认处理程序的配置（其ID为0）。然后，add()方法向记录器添加一个新处理程序。该处理程序将记录到标准错误，只记录INFO或更高级别的日志。

你也可以自定义一个新的类型的日志，并赋予新的日志level no，在这里就不介绍了，先保证使用默认的日志level，就足够了。

3.3 设置日志输出的格式

在日常使用中，如果默认的输出内容不够，我们还可以自定义日志的输出内容和格式。

可以通过add()方法中的格式选项对Loguru生成的日志记录进行重新格式化。

Loguru 中的每条日志记录都是一个 Python 字典，其中包含其时间戳、日志级别等数据。

可以使用loguru提供的格式化指令，包括或重新排列每条信息，如下所示：

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

import sys
from loguru import logger

logger.remove(0)
logger.add(sys.stderr, format="{time} | {level} | {message}")

logger.debug("Happy logging with Loguru!")

格式参数定义了自定义格式，在这个例子中有三个指令：

{time}：时间戳

{level}：日志级别

{message}：日志消息

输出如下：

代码语言：shell

复制

2022-08-10T15:01:32.154035-0400 | DEBUG | Happy logging with Loguru!

Loguru还通过其序列化选项支持JSON格式的结构化日志。

这可以让你以JSON格式输出你的日志，这样机器可以很容易地解析和分析它，因为每条记录中的信息将以键/值对的形式提供。

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

import sys
from loguru import logger

logger.remove(0)
logger.add(sys.stderr, format="{time:MMMM D, YYYY > HH:mm:ss!UTC} | {level} | {message}", serialize=True)
logger.debug("Happy logging with Loguru!")

json格式的输出：

代码语言：shell

复制

{"text": "August 10, 2022 > 19:38:06 | DEBUG | Happy logging with Loguru!\n", "record": {"elapsed": {"repr": "0:00:00.004000", "seconds": 0.004}, "exception": null, "extra": {}, "file": {"name": "app.py", "path": "C:\\Users\\Eric\\Documents\\Better Stack\\loguru-demo\\app.py"}, "function": "<module>", "level": {"icon": "🐞", "name": "DEBUG", "no": 10}, "line": 8, "message": "Happy logging with Loguru!", "module": "app", "name": "__main__", "process": {"id": 22652, "name": "MainProcess"}, "thread": {"id": 25892, "name": "MainThread"}, "time": {"repr": "2022-08-10 15:38:06.369578-04:00", "timestamp": 1660160286.369578}}}

3.4 把日志记录到文件中

最简单的配置如下：

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

logger.add("loguru.log")
logger.debug("A debug message.")

输出如下：

代码语言：shell

复制

cat loguru.log
2022-08-11 13:16:52.573 | DEBUG | __main__:<module>:13 - A debug message.

当add函数配置为一个文件时，add方法提供了更多选项来自定义日志文件的处理方式：

• rotate：指定关闭当前日志文件并创建新文件的条件。此条件可以是 int、datetime 或 str，建议使用 str，因为它更易于阅读。
  • 如果是整数值，它对应于当前文件在创建新文件之前允许保留的最大字节数。
  • 如果是datetime.timedelta 值时，它指示每次旋转的频率，而 datetime.time 指定每个旋转应在一天中发生的时间。
  • 如果是str值，这是上述类型的变体。
• retention：指定在从文件系统中删除每个日志文件之前如何保留日志。
• compression：如果设置此选项，日志文件将转换为指定的压缩格式。
• delay：如果设置为 True，则新日志文件的创建将延迟到推送第一条日志消息。
• mode， buffering， encoding： 这些参数将被传递给 Python 的 open（） 函数，该函数决定了 Python 将如何打开日志文件。

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

# 将自动删除超过一分钟的老文件
logger.add("loguru.log", rotation="5 seconds", retention="1 minute")
# 将仅保留三个最新文件
logger.add("loguru.log", rotation="5 seconds", retention=3)

一个完整的配置:

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

logger.add(
    sink="./logs/app.log",
    enqueue=True,
    rotation="4 weeks",
    retention="4 months",
    encoding="utf-8",
    backtrace=True,
    diagnose=True,
    compression="zip",
)

add函数参数的完整解释：

• sink：为记录器生成的每条记录指定目的地。默认情况下，它设置为 sys.stderr。
• level：指定记录器的最低日志级别。
• format：用于为日志定义自定义格式。
• filter：用于确定一条记录是否应该被记录。
• colorize: 采用布尔值并确定是否应启用终端着色。
• serialize：如果设置为 True，则日志记录以 JSON 格式呈现。
• backtrace：确定异常跟踪是否应该延伸到捕获错误的点之外，以便于调试。 诊断：确定变量值是否应显示在异常跟踪中。您应该在生产环境中将其设置为 False 以避免泄露敏感信息。
• diagnose: 确定变量值是否应在异常跟踪中显示。在生产环境中应将其设置为 False，以避免泄露敏感信息。
• enqueue：启用此选项会将日志记录放入队列中，以避免多个进程记录到同一目的地时发生冲突。
• catch：如果在记录到指定的接收器时发生意外错误，您可以通过将此选项设置为 True 来捕获该错误。错误将打印到标准错误。

4. One More Thing

4.1 不同类型的日志记录到不同的文件中

在上面的配置中，我们讲到，可以使用add函数来配置最小的日志级别，如果我们需要把不同的日志输出到不同的文件中，我们需要使用到filter参数：

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

import sys
from loguru import logger

def level_filter(level):
    def is_level(record):
        return record["level"].name == level
    return is_level

logger.remove(0)
logger.add("./logs/app.log", filter=level_filter(level="WARNING"))

输出如下：

代码语言：shell

复制

2022-09-30 12:17:00.548 | WARNING  | __main__:<module>:15 - A warning message.

还可以使用lambda函数直接配置filter参数，一个完整的例子：

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

from loguru import logger

# 设置不同级别的日志输出文件
logger.add("debug.log", level="DEBUG", rotation="10 MB", filter=lambda record: record["level"].name == "DEBUG")
logger.add("info.log", level="INFO", rotation="10 MB", filter=lambda record: record["level"].name == "INFO")
logger.add("warning.log", level="WARNING", rotation="10 MB", filter=lambda record: record["level"].name == "WARNING")
logger.add("error.log", level="ERROR", rotation="10 MB", filter=lambda record: record["level"].name == "ERROR")
logger.add("critical.log", level="CRITICAL", rotation="10 MB", filter=lambda record: record["level"].name == "CRITICAL")

# 输出不同级别的日志消息
logger.debug("This is a debug message")
logger.info("This is an info message")
logger.warning("This is a warning message")
logger.error("This is an error message")
logger.critical("This is a critical message")

4.2 异常记录

loguru提供了非常方便的异常定位功能，可以直接使用catch闭包，把抛出异常的位置记录到日志中。

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

from loguru import logger

logger.add(sink='log.log')

@logger.catch
def my_function(x, y, z):
    return 1 / (x + y + z)

res = my_function(0,0,0)

输出如下：

代码语言：shell

复制

> File "/var/folders/kb/0pw_yx2n75z8mlyzjk3mwlwc0000gn/T/ipykernel_85315/1609034425.py", line 9, in <module>
    res = my_function(0,0,0)
          └ <function my_function at 0x7fcce2170670>

  File "/var/folders/kb/0pw_yx2n75z8mlyzjk3mwlwc0000gn/T/ipykernel_85315/1609034425.py", line 7, in my_function
    return 1 / (x + y + z)
                │   │   └ 0
                │   └ 0
                └ 0

ZeroDivisionError: division by zero

4.3 实际使用示例

最后给一组我的代码里面使用的配置:

代码语言：python

代码运行次数：0

复制Cloud Studio代码运行

folder_ = "./log/"
prefix_ = "polaris-"
rotation_ = "10 MB"
retention_ = "30 days"
encoding_ = "utf-8"
backtrace_ = True
diagnose_ = True

# 格式里面添加了process和thread记录，方便查看多进程和线程程序
format_ = '<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> ' \
            '| <magenta>{process}</magenta>:<yellow>{thread}</yellow> ' \
            '| <cyan>{name}</cyan>:<cyan>{function}</cyan>:<yellow>{line}</yellow> - <level>{message}</level>'

# 这里面采用了层次式的日志记录方式，就是低级日志文件会记录比他高的所有级别日志，这样可以做到低等级日志最丰富，高级别日志更少更关键
# debug
logger.add(folder_ + prefix_ + "debug.log", level="DEBUG", backtrace=backtrace_, diagnose=diagnose_,
            format=format_, colorize=False,
            rotation=rotation_, retention=retention_, encoding=encoding_,
            filter=lambda record: record["level"].no >= logger.level("DEBUG").no)

# info
logger.add(folder_ + prefix_ + "info.log", level="INFO", backtrace=backtrace_, diagnose=diagnose_,
            format=format_, colorize=False,
            rotation=rotation_, retention=retention_, encoding=encoding_,
            filter=lambda record: record["level"].no >= logger.level("INFO").no)

# warning
logger.add(folder_ + prefix_ + "warning.log", level="WARNING", backtrace=backtrace_, diagnose=diagnose_,
            format=format_, colorize=False,
            rotation=rotation_, retention=retention_, encoding=encoding_,
            filter=lambda record: record["level"].no >= logger.level("WARNING").no)

# error
logger.add(folder_ + prefix_ + "error.log", level="ERROR", backtrace=backtrace_, diagnose=diagnose_,
            format=format_, colorize=False,
            rotation=rotation_, retention=retention_, encoding=encoding_,
            filter=lambda record: record["level"].no >= logger.level("ERROR").no)

# critical
logger.add(folder_ + prefix_ + "critical.log", level="CRITICAL", backtrace=backtrace_, diagnose=diagnose_,
            format=format_, colorize=False,
            rotation=rotation_, retention=retention_, encoding=encoding_,
            filter=lambda record: record["level"].no >= logger.level("CRITICAL").no)

logger.add(sys.stderr, level="CRITICAL", backtrace=backtrace_, diagnose=diagnose_,
            format=format_, colorize=True,
            filter=lambda record: record["level"].no >= logger.level("CRITICAL").no)