1 萬字詳解 python logging 日誌模塊

前言
這篇文章熬了一週，終於寫完了。一個知識點自己理解可能只需要花半個小時，而要想把它寫出來讓別人理解，要花十倍甚至更多的時間。所以說寫技術文是真的不容易。而它的價值在於它的生命力更長久。即使三五年後給別人看依然會有收穫。對寫作者自己而言，寫的過程也是對知識的一次更通透的理解。

以下爲正文

說到日誌，無論是寫框架代碼還是業務代碼，都離不開日誌的記錄，他能給我們定位問題帶來極大的幫助。

記錄日誌最簡單的方法就是在你想要記錄的地方加上一句 print ，我相信無論是新手還是老鳥都經常這麼幹。在簡單的代碼中或者小型項目中這麼幹一點問題都沒有。但是在一些稍大一點的項目，有時候定位一個問題，需要查看歷史日誌定位問題，用 print 就不合時宜了。

print 打印出來的日誌沒有時間，不知道日誌記錄的位置，也沒有可讀的日誌格式，還不能把日誌輸出到指定文件。。。。除非這些你都全部自己重複造一遍輪子。

最佳的做法是使用內置的 logging 模塊，因爲 logging 模塊給開發者提供了非常豐富的功能。

比如上圖就是用標準庫 logging 模塊記錄生成的日誌，有日誌的具體時間、日誌發生的模塊、有日誌級別和日誌的具體內容等等

怎麼用呢，來看個例子

導入 logging 模塊，然後直接使用 logging 提供的日誌消息記錄方法就可以。

日誌級別

日誌級別分爲以下 5 個級別

qqQXPR

日誌級別重要程度逐次提高，python 提供了 5 個對應級別的方法。默認情況下日誌的級別是 WARGING, 低於 WARING 的日誌信息都不會輸出。

從上面代碼中可以看到 loging.warging 以後的日誌內容都打印在標準輸出流，也就是命令行窗口，但是 logging.debug 和 info 記錄的日誌不會打印出來。

修改日誌級別

如何讓 debug 級別的信息也輸出？

當然是修改默認的日誌級別，在開始記錄日誌前可以使用logging.basicConfig方法來設定日誌級別

import logging
logging.basicConfig( level=logging.DEBUG)
logging.debug("this is debug")
logging.info("this is info")
logging.error("this is error")

設置爲 debug 級別後，所有的日誌信息都會輸出

DEBUG:root:this is debug
INFO:root:this is info
ERROR:root:this is error

日誌記錄到文件

前面的日誌默認會把日誌輸出到標準輸出流，就是隻在命令行窗口輸出，程序重啓後歷史日誌沒地方找，所以把日誌內容永久記錄是一個很常見的需求。同樣通過配置函數 logging.basicConfig 可以指定日誌輸出到什麼地方

import logging
logging.basicConfig(file, level=logging.INFO)
logging.debug("this is debug")
logging.info("this is info")
logging.error("this is error")

這裏我指定日誌輸出到文件 test.log 中，日誌級別指定爲了 INFO，最後文件中記錄的內容如下：

INFO:root:this is info
ERROR:root:this is error

每次重新運行時，日誌會以追加的方式在後面，如果每次運行前要覆蓋之前的日誌，則需指定 filemode='w'，這個和 open 函數寫數據到文件用的參數是一樣的。

指定日誌格式

默認輸出的格式包含 3 部分，日誌級別，日誌記錄器的名字，以及日誌內容，中間用 “:” 連接。如果我們想改變日誌格式，例如想加入日期時間、顯示日誌器名字，我們是可以指定 format 參數來設置日誌的格式

import logging
logging.basicConfig(format='%(asctime)s %(levelname)s %(name)s %(message)s')
logging.error("this is error")

輸出

2021-12-15 07:44:16,547 ERROR root this is error

日誌格式化輸出提供了非常多的參數，除了時間、日誌級別、日誌消息內容、日誌記錄器的名字外，還可以指定線程名，進程名等等

到這裏爲止，日誌模塊的基本用法就這些了，也能滿足大部分應用場景，更高級的方法接着往下看，可以幫助你更好的處理日誌

記錄器（logger）

前面介紹的日誌記錄，其實都是通過一個叫做日誌記錄器（Logger）的實例對象創建的，每個記錄器都有一個名稱，直接使用 logging 來記錄日誌時，系統會默認創建名爲 root 的記錄器，這個記錄器是根記錄器。記錄器支持層級結構，子記錄器通常不需要單獨設置日誌級別以及 Handler（後面會介紹），如果子記錄器沒有單獨設置，則它的行爲會委託給父級。

記錄器名稱可以是任意名稱，不過最佳實踐是直接用模塊的名稱當作記錄器的名字。命名如下

logger = logging.getLogger(__name__)

默認情況下，記錄器採用層級結構，上句點作爲分隔符排列在命名空間的層次結構中。層次結構列表中位於下方的記錄器是列表中較高位置的記錄器的子級。例如，有個名叫 foo 的記錄器，而名字是 foo.bar，foo.bar.baz，和 foo.bam 的記錄器都是 foo 的子級。

├─foo
│  │  main.py
│  │  __init__.py
│  │  
│  ├─bam
│  │  │  __init__.py
│  │  │  
│  │          
│  ├─bar
│  │  │  __init__.py
│  │  │  
│  │  ├─baz
│  │  │  │  __init__.py
│  │  │  │

main.py

import foo
from foo import bar
from foo import bam
from foo.bar import baz

if __name__ == '__main__':
    pass

foo.py

import logging

logging.basicConfig()
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

logger.info("this is foo")

這裏我只設置 foo 這個記錄器的級別爲 INFO

bar.py

import logging

logger = logging.getLogger(__name__)
logger.info("this is bar")

其它子模塊都是像 bar.py 一樣類似的代碼，都沒有設置日誌級別，最後的輸出結果是

INFO:foo:this is foo
INFO:foo.bar:this is bar
INFO:foo.bam:this is bam
INFO:foo.bar.baz:this is baz

這是因爲 foo.bar 這個記錄器沒有設置日誌級別，就會向上找到已經設置了日日誌級別的祖先，這裏剛好找到父記錄器 foo 的級別爲 INFO，如果 foo 也沒設置的話，就會找到根記錄器 root，root 默認的級別爲 WARGING。

處理器（Handler）

記錄器負責日誌的記錄，但是日誌最終記錄在哪裏記錄器並不關心，而是交給了另一個傢伙 -- 處理器（Handler）去處理。

例如一個 Flask 項目，你可能會將 INFO 級別的日誌記錄到文件，將 ERROR 級別的日誌記錄到標準輸出，將某些關鍵日誌（例如有訂單或者嚴重錯誤）發送到某個郵件地址通知老闆。這時候你的記錄器添加多個不同的處理器來處理不同的消息日誌，以此根據消息的重要性發送的特定的位置。

Python 內置了很多實用的處理器，常用的有：

1、StreamHandler 標準流處理器，將消息發送到標準輸出流、錯誤流
2、FileHandler 文件處理器，將消息發送到文件
3、RotatingFileHandler 文件處理器，文件達到指定大小後，啓用新文件存儲日誌
4、TimedRotatingFileHandler 文件處理器，日誌以特定的時間間隔輪換日誌文件

處理器操作

Handler 提供了 4 個方法給開發者使用，細心的你可以發現了，logger 可以設置 level，Handler 也可以設置 Level。通過 setLevel 可以將記錄器記錄的不同級別的消息發送到不同的地方去。

import logging
from logging import StreamHandler
from logging import FileHandler

logger = logging.getLogger(__name__)

# 設置爲DEBUG級別
logger.setLevel(logging.DEBUG)

# 標準流處理器，設置的級別爲WARAING
stream_handler = StreamHandler()
stream_handler.setLevel(logging.WARNING)
logger.addHandler(stream_handler)

# 文件處理器，設置的級別爲INFO
file_handler = FileHandler(file)
file_handler.setLevel(logging.INFO)
logger.addHandler(file_handler)

logger.debug("this is debug")
logger.info("this is info")
logger.error("this is error")
logger.warning("this is warning")

運行後，在命令行窗口輸出的日誌內容是：

this is error
this is warning

輸出在文件的日誌內容是：

this is info
this is error
this is warning

儘管我們將 logger 的級別設置爲了 DEBUG，但是 debug 記錄的消息並沒有輸出，因爲我給兩個 Handler 設置的級別都比 DEBUG 要高，所以這條消息被過濾掉了。

格式器（formatter）

格式器在文章的前面部分其實已經有所介紹，不過那是通過 logging.basicConfig 來指定的，其實格式器還可以以對象的形式來設置在 Handler 上。格式器可以指定日誌的輸出格式，要不要展示時間，時間格式什麼，要不要展示日誌的級別，要不要展示記錄器的名字等等，都可以通過一個格式器對消息進行格式化輸出。

import logging
from logging import StreamHandler

logger = logging.getLogger(__name__)

# 標準流處理器
stream_handler = StreamHandler()
stream_handler.setLevel(logging.WARNING)

# 創建一個格式器
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
# 作用在handler上
stream_handler.setFormatter(formatter)
# 添加處理器
logger.addHandler(stream_handler)

logger.info("this is info")
logger.error("this is error")
logger.warning("this is warning")

注意，格式器只能作用在處理器上，通過處理器的setFromatter方法設置格式器。而且一個 Handler 只能設置一個格式器。是一對一的關係。而 logger 與 handler 是一對多的關係，一個 logger 可以添加多個 handler。handler 和 logger 都可以設置日誌的等級。

logging.basicConfig

回到最開始的地方，logging.basicConfig() 方法爲我們幹了啥？現在你大概能猜出來了。來看 python 源碼中是怎麼說的

Do basic configuration for the logging system.

This function does nothing if the root logger already has handlers configured. It is a convenience method intended for use by simple scripts to do one-shot configuration of the logging package.

The default behaviour is to create a StreamHandler which writes to sys.stderr, set a formatter using the BASIC_FORMAT format string, and add the handler to the root logger.

A number of optional keyword arguments may be specified, which can alter the default behaviour.

1、創建一個 root 記錄器
2、設置 root 的日誌級別爲 warning
3、爲 root 記錄器添加 StreamHandler 處理器
4、爲處理器設置一個簡單格式器

logging.basicConfig()
logging.warning("hello")

這兩行代碼其實就等價於：

import sys
import logging
from logging import StreamHandler
from logging import Formatter


logger = logging.getLogger("root")
logger.setLevel(logging.WARNING)
handler = StreamHandler(sys.stderr)
logger.addHandler(handler)
formatter = Formatter(" %(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)
logger.warning("hello")

logging.basicConfig 方法做的事情是相當於給日誌系統做一個最基本的配置，方便開發者快速接入使用。它必須在開始記錄日誌前調用。不過如果 root 記錄器已經指定有其它處理器，這時候你再調用 basciConfig，則該方式將失效，它什麼都不做。

日誌配置

日誌的配置除了前面介紹的將配置直接寫在代碼中，還可以將配置信息單獨放在配置文件中，實現配置與代碼分離。

日誌配置文件 logging.conf

[loggers]
keys=root

[handlers]
keys=consoleHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler


[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s

加載配置文件

import logging
import logging.config

# 加載配置
logging.config.fileConfig('logging.conf')

# 創建 logger
logger = logging.getLogger()

# 應用代碼
logger.debug("debug message")
logger.info("info message")
logger.warning("warning message")
logger.error("error message")

輸出

2021-12-23 00:02:07,019 - root - DEBUG - debug message
2021-12-23 00:02:07,019 - root - INFO - info message
2021-12-23 00:02:07,019 - root - WARNING - warning message
2021-12-23 00:02:07,019 - root - ERROR - error message

到這裏算是對 logging 的一次比較完整的介紹，當然，還有很多細節並沒有涉及到，因此我給了幾個鏈接供參考。

參考鏈接：

https://docs.python.org/3/library/logging.html#

https://docs.python.org/3/howto/logging.html#logging-advanced-tutorial

https://awaywithideas.com/python-logging-a-practical-guide/

https://rmcomplexity.com/article/2020/12/01/introduction-to-python-logging.html

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/K3k-Mk75tSe-Z8cTooyJTg