Loguru：Python 日志終極解決方案

關注微信公眾號：K哥爬蟲，持續分享爬蟲進階、JS/安卓逆向等技術干貨！

日志的重要性

日志的作用非常重要，日志可以記錄用戶的操作、程序的異常，還可以為數據分析提供依據，日志的存在意義就是為了能夠在程序在運行過程中記錄錯誤，方便維護和調試，能夠快速定位出錯的地方，減少維護成本。每個程序員都應該知道，不是為了記錄日志而記錄日志，日志也不是隨意記的。要實現能夠只通過日志文件還原整個程序執行的過程，達到能透明地看到程序里執行情況，每個線程、每個過程到底執行到哪的目的。日志就像飛機的黑匣子一樣，應當能夠復原異常的整個現場乃至細節！

常見日志記錄方式

print()

最常見的是把輸出函數 print() 當作日志記錄的方式，直接打印各種提示信息，常見於個人練習項目里，通常是懶得單獨配置日志，而且項目太小不需要日志信息，不需要上線，不需要持續運行，完整的項目不推薦直接打印日志信息，現實中也幾乎沒有人這么做。

自寫模板

我們可以在不少小項目里面看到作者自己寫了一個日志模板，通常利用 print() 或者 sys.stdout 稍微封裝一下即可實現簡單的日志輸出，這里的 sys.stdout 是 Python 中的標准輸出流，print() 函數是對 sys.stdout 的高級封裝，當我們在 Python 中打印對象調用 print(obj) 時候，事實上是調用了 sys.stdout.write(obj+'\n')，print() 將內容打印到了控制台，然后追加了一個換行符 \n。

自寫日志模板適合比較小的項目，可以按照自己的喜好編寫模板，不需要太多復雜配置，方便快捷，但是這種記錄日志的方式並不是很規范，有可能你自己覺得閱讀體驗不錯，但是別人在接觸你的項目的時候往往需要花費一定的時間去學習日志的邏輯、格式、輸出方式等，比較大的項目同樣不推薦這種方法。

一個簡單的自寫日志模板舉例：

日志模板 log.py：

import sys
import traceback
import datetime


def getnowtime():
    return datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")


def _log(content, level, *args):
    sys.stdout.write("%s - %s - %s\n" % (getnowtime(), level, content))
    for arg in args:
        sys.stdout.write("%s\n" % arg)


def debug(content, *args):
    _log(content, 'DEBUG', *args)


def info(content, *args):
    _log(content, 'INFO', *args)


def warn(content, *args):
    _log(content, 'WARN', *args)


def error(content, *args):
    _log(content, 'ERROR', *args)


def exception(content):
    sys.stdout.write("%s - %s\n" % (getnowtime(), content))
    traceback.print_exc(file=sys.stdout)

調用日志模塊：

import log


log.info("This is log info!")
log.warn("This is log warn!")
log.error("This is log error!")
log.debug("This is log debug!")

people_info = {"name": "Bob", "age": 20}

try:
    gender = people_info["gender"]
except Exception as error:
    log.exception(error)

日志輸出：

2021-10-19 09:50:58 - INFO - This is log info!
2021-10-19 09:50:58 - WARN - This is log warn!
2021-10-19 09:50:58 - ERROR - This is log error!
2021-10-19 09:50:58 - DEBUG - This is log debug!
2021-10-19 09:50:58 - 'gender'
Traceback (most recent call last):
  File "D:/python3Project/test.py", line 18, in <module>
    gender = people_info["gender"]
KeyError: 'gender'

Logging

在一個完整的項目中，大多數人都會引入專門的日志記錄庫，而 Python 自帶的標准庫 logging 就是專門為日志記錄而生的，logging 模塊定義的函數和類為應用程序和庫的開發實現了一個靈活的事件日志系統。由標准庫模塊提供日志記錄 API 的關鍵好處是所有 Python 模塊都可以使用這個日志記錄功能。所以，你的應用日志可以將你自己的日志信息與來自第三方模塊的信息整合起來。

logging 模塊雖然強大，但是其配置也是比較繁瑣的，在大型項目中通常需要單獨初始化日志、配置日志格式等等，K哥在日常使用中通常都會對 logging 做如下的封裝寫法，使日志可以按天保存，保留15天的日志，可以配置是否輸出到控制台和文件，如下所示：

# 實現按天分割保留日志


import os
import sys
import logging
from logging import handlers


PARENT_DIR = os.path.split(os.path.realpath(__file__))[0]  # 父目錄
LOGGING_DIR = os.path.join(PARENT_DIR, "log")              # 日志目錄
LOGGING_NAME = "test"                                      # 日志文件名

LOGGING_TO_FILE = True                                     # 日志輸出文件
LOGGING_TO_CONSOLE = True                                  # 日志輸出到控制台

LOGGING_WHEN = 'D'                                         # 日志文件切分維度
LOGGING_INTERVAL = 1                                       # 間隔少個 when 后，自動重建文件
LOGGING_BACKUP_COUNT = 15                                  # 日志保留個數，0 保留所有日志
LOGGING_LEVEL = logging.DEBUG                              # 日志等級
LOGGING_suffix = "%Y.%m.%d.log"                            # 舊日志文件名

# 日志輸出格式
LOGGING_FORMATTER = "%(levelname)s - %(asctime)s - process:%(process)d - %(filename)s - %(name)s - line:%(lineno)d - %(module)s - %(message)s"


def logging_init():
    if not os.path.exists(LOGGING_DIR):
        os.makedirs(LOGGING_DIR)
    logger = logging.getLogger()
    logger.setLevel(LOGGING_LEVEL)
    formatter = logging.Formatter(LOGGING_FORMATTER)

    if LOGGING_TO_FILE:
        file_handler = handlers.TimedRotatingFileHandler(filename=os.path.join(LOGGING_DIR, LOGGING_NAME), when=LOGGING_WHEN, interval=LOGGING_INTERVAL, backupCount=LOGGING_BACKUP_COUNT)
        file_handler.suffix = LOGGING_suffix
        file_handler.setFormatter(formatter)
        logger.addHandler(file_handler)

    if LOGGING_TO_CONSOLE:
        stream_handler = logging.StreamHandler(sys.stderr)
        stream_handler.setFormatter(formatter)
        logger.addHandler(stream_handler)


def logging_test():
    logging.info("This is log info!")
    logging.warning("This is log warn!")
    logging.error("This is log error!")
    logging.debug("This is log debug!")
    people_info = {"name": "Bob", "age": 20}

    try:
        gender = people_info["gender"]
    except Exception as error:
        logging.exception(error)


if __name__ == "__main__":
    logging_init()
    logging_test()

輸出日志：

INFO - 2021-10-19 11:28:10,103 - process:15144 - test.py - root - line:52 - test - This is log info!
WARNING - 2021-10-19 11:28:10,105 - process:15144 - test.py - root - line:53 - test - This is log warn!
ERROR - 2021-10-19 11:28:10,105 - process:15144 - test.py - root - line:54 - test - This is log error!
DEBUG - 2021-10-19 11:28:10,105 - process:15144 - test.py - root - line:55 - test - This is log debug!
ERROR - 2021-10-19 11:28:10,105 - process:15144 - test.py - root - line:61 - test - 'gender'
Traceback (most recent call last):
  File "D:/python3Project/test.py", line 59, in logging_test
    gender = people_info["gender"]
KeyError: 'gender'

它在控制台中是這樣的：

當然，如果你不需要很復雜的功能，希望簡潔一點，僅僅需要在控制台輸出一下日志的話，也可以只進行簡單的配置：

import logging
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
logging.getLogger()

更優雅的解決方案：Loguru

對於 logging 模塊，即便是簡單的使用，也需要自己定義格式，這里介紹一個更加優雅、高效、簡潔的第三方模塊：loguru，官方的介紹是：Loguru is a library which aims to bring enjoyable logging in Python. Loguru 旨在為 Python 帶來愉快的日志記錄。這里引用官方的一個 GIF 來快速演示其功能：

安裝

Loguru 僅支持 Python 3.5 及以上的版本，使用 pip 安裝即可：

pip install loguru

開箱即用

Loguru 的主要概念是只有一個：logger

from loguru import logger

logger.info("This is log info!")
logger.warning("This is log warn!")
logger.error("This is log error!")
logger.debug("This is log debug!")

控制台輸出：

可以看到不需要手動設置，Loguru 會提前配置一些基礎信息，自動輸出時間、日志級別、模塊名、行號等信息，而且根據等級的不同，還自動設置了不同的顏色，方便觀察，真正做到了開箱即用！

add() / remove()

如果想自定義日志級別，自定義日志格式，保存日志到文件該怎么辦？與 logging 模塊不同，不需要 Handler，不需要 Formatter，只需要一個 add() 函數就可以了，例如我們想把日志儲存到文件：

from loguru import logger

logger.add('test.log')
logger.debug('this is a debug')

我們不需要像 logging 模塊一樣再聲明一個 FileHandler 了，就一行 add() 語句搞定，運行之后會發現目錄下 test.log 里面同樣出現了剛剛控制台輸出的 debug 信息。

與 add() 語句相反，remove() 語句可以刪除我們添加的配置：

from loguru import logger

log_file = logger.add('test.log')
logger.debug('This is log debug!')
logger.remove(log_file)
logger.debug('This is another log debug!')

此時控制台會輸出兩條 debug 信息：

2021-10-19 13:53:36.610 | DEBUG    | __main__:<module>:86 - This is log debug!
2021-10-19 13:53:36.611 | DEBUG    | __main__:<module>:88 - This is another log debug!

而 test.log 日志文件里面只有一條 debug 信息，原因就在於我們在第二條 debug 語句之前使用了 remove() 語句。

完整參數

Loguru 對輸出到文件的配置有非常強大的支持，比如支持輸出到多個文件，分級別分別輸出，過大創建新文件，過久自動刪除等等。 下面我們來詳細看一下 add() 語句的詳細參數：

基本語法：

add(sink, *, level='DEBUG', format='<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>', filter=None, colorize=None, serialize=False, backtrace=True, diagnose=True, enqueue=False, catch=True, **kwargs)

基本參數釋義：

• sink：可以是一個 file 對象，例如 sys.stderr 或 open('file.log', 'w')，也可以是 str 字符串或者 pathlib.Path 對象，即文件路徑，也可以是一個方法，可以自行定義輸出實現，也可以是一個 logging 模塊的 Handler，比如 FileHandler、StreamHandler 等，還可以是 coroutine function，即一個返回協程對象的函數等。
• level：日志輸出和保存級別。
• format：日志格式模板。
• filter：一個可選的指令，用於決定每個記錄的消息是否應該發送到 sink。
• colorize：格式化消息中包含的顏色標記是否應轉換為用於終端着色的 ansi 代碼，或以其他方式剝離。 如果沒有，則根據 sink 是否為 tty（電傳打字機縮寫） 自動做出選擇。
• serialize：在發送到 sink 之前，是否應首先將記錄的消息轉換為 JSON 字符串。
• backtrace：格式化的異常跟蹤是否應該向上擴展，超出捕獲點，以顯示生成錯誤的完整堆棧跟蹤。
• diagnose：異常跟蹤是否應顯示變量值以簡化調試。建議在生產環境中設置 False，避免泄露敏感數據。
• enqueue：要記錄的消息是否應在到達 sink 之前首先通過多進程安全隊列，這在通過多個進程記錄到文件時很有用，這樣做的好處還在於使日志記錄調用是非阻塞的。
• catch：是否應自動捕獲 sink 處理日志消息時發生的錯誤，如果為 True，則會在 sys.stderr 上顯示異常消息，但該異常不會傳播到 sink，從而防止應用程序崩潰。
• **kwargs：僅對配置協程或文件接收器有效的附加參數（見下文）。

當且僅當 sink 是協程函數時，以下參數適用：

• loop：將在其中調度和執行異步日志記錄任務的事件循環。如果為 None，將使用 asyncio.get_event_loop() 返回的循環。

當且僅當 sink 是文件路徑時，以下參數適用：

• rotation：一種條件，指示何時應關閉當前記錄的文件並開始新的文件。
• **retention **：過濾舊文件的指令，在循環或程序結束期間會刪除舊文件。
• compression：日志文件在關閉時應轉換為的壓縮或存檔格式。
• delay：是在配置 sink 后立即創建文件，還是延遲到第一條記錄的消息時再創建。默認為 False。
• mode：內置 open() 函數的打開模式，默認為 a（以追加模式打開文件）。
• buffering：內置 open() 函數的緩沖策略，默認為1（行緩沖文件）。
• encoding：內置 open() 函數的文件編碼，如果 None，則默認為 locale.getpreferredencoding()。
• **kwargs：其他傳遞給內置 open() 函數的參數。

這么多參數可以見識到 add() 函數的強大之處，僅僅一個函數就能實現 logging 模塊的諸多功能，接下來介紹幾個比較常用的方法。

rotation 日志文件分隔

add() 函數的 rotation 參數，可以實現按照固定時間創建新的日志文件，比如設置每天 0 點新創建一個 log 文件：

logger.add('runtime_{time}.log', rotation='00:00')

設置超過 500 MB 新創建一個 log 文件：

logger.add('runtime_{time}.log', rotation="500 MB")

設置每隔一個周新創建一個 log 文件：

logger.add('runtime_{time}.log', rotation='1 week')

retention 日志保留時間

add() 函數的 retention 參數，可以設置日志的最長保留時間，比如設置日志文件最長保留 15 天：

logger.add('runtime_{time}.log', retention='15 days')

設置日志文件最多保留 10 個：

logger.add('runtime_{time}.log', retention=10)

也可以是一個 datetime.timedelta 對象，比如設置日志文件最多保留 5 個小時：

import datetime
from loguru import logger

logger.add('runtime_{time}.log', retention=datetime.timedelta(hours=5))

compression 日志壓縮格式

add() 函數的 compression 參數，可以配置日志文件的壓縮格式，這樣可以更加節省存儲空間，比如設置使用 zip 文件格式保存：

logger.add('runtime_{time}.log', compression='zip')

其格式支持：gz、bz2、xz、lzma、tar、tar.gz、tar.bz2、tar.xz

字符串格式化

Loguru 在輸出 log 的時候還提供了非常友好的字符串格式化功能，相當於 str.format()：

logger.info('If you are using Python {}, prefer {feature} of course!', 3.6, feature='f-strings')

輸出：

2021-10-19 14:59:06.412 | INFO     | __main__:<module>:3 - If you are using Python 3.6, prefer f-strings of course!

異常追溯

在 Loguru 里可以直接使用它提供的裝飾器就可以直接進行異常捕獲，而且得到的日志是無比詳細的：

from loguru import logger


@logger.catch
def my_function(x, y, z):
    # An error? It's caught anyway!
    return 1 / (x + y + z)


my_function(0, 0, 0)

日志輸出：

2021-10-19 15:04:51.675 | ERROR    | __main__:<module>:10 - An error has been caught in function '<module>', process 'MainProcess' (30456), thread 'MainThread' (26268):
Traceback (most recent call last):

> File "D:/python3Project\test.py", line 10, in <module>
    my_function(0, 0, 0)
    └ <function my_function at 0x014CDFA8>

  File "D:/python3Project\test.py", line 7, in my_function
    return 1 / (x + y + z)
                │   │   └ 0
                │   └ 0
                └ 0

ZeroDivisionError: division by zero

在控制台的輸出是這樣的：

相比 Logging，Loguru 無論是在配置方面、日志輸出樣式還是異常追蹤，都遠優於 Logging，使用 Loguru 無疑能提升開發人員效率。本文僅介紹了一些常用的方法，想要詳細了解可參考 Loguru 官方文檔或關注 Loguru GitHub。