python深入之日誌配置
作為開發者,我們可以通過以下3種方式來配置logging:
- 1)使用Python程式碼顯式的建立loggers, handlers和formatters並分別呼叫它們的配置函式;
- 2)建立一個日誌配置檔案,然後使用
fileConfig()
函式來讀取該檔案的內容; - 3)建立一個包含配置資訊的dict,然後把它傳遞個
dictConfig()
函式;
需要說明的是,logging.basicConfig()
也屬於第一種方式,它只是對loggers, handlers和formatters的配置函式進行了封裝。另外,第二種配置方式相對於第一種配置方式的優點在於,它將配置資訊和程式碼進行了分離,這一方面降低了日誌的維護成本,同時還使得非開發人員也能夠去很容易地修改日誌配置。
一、使用Python程式碼實現日誌配置
程式碼如下:
# 建立一個日誌器logger並設定其日誌級別為DEBUG logger = logging.getLogger('simple_logger') logger.setLevel(logging.DEBUG) # 建立一個流處理器handler並設定其日誌級別為DEBUG handler = logging.StreamHandler(sys.stdout) handler.setLevel(logging.DEBUG) # 建立一個格式器formatter並將其新增到處理器handler formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s") handler.setFormatter(formatter) # 為日誌器logger新增上面建立的處理器handler logger.addHandler(handler) # 日誌輸出 logger.debug('debug message') logger.info('info message') logger.warn('warn message') logger.error('error message') logger.critical('critical message')
執行輸出:
2017-05-15 11:30:50,955 - simple_logger - DEBUG - debug message 2017-05-15 11:30:50,955 - simple_logger - INFO - info message 2017-05-15 11:30:50,955 - simple_logger - WARNING - warn message 2017-05-15 11:30:50,955 - simple_logger - ERROR - error message 2017-05-15 11:30:50,955 - simple_logger - CRITICAL - critical message
二、使用配置檔案和fileConfig()函式實現日誌配置
現在我們通過配置檔案的方式來實現與上面同樣的功能:
# 讀取日誌配置檔案內容
logging.config.fileConfig('logging.conf')
# 建立一個日誌器logger
logger = logging.getLogger('simpleExample')
# 日誌輸出
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
配置檔案logging.conf
內容如下:
[loggers]
keys=root,simpleExample
[handlers]
keys=fileHandler,consoleHandler
[formatters]
keys=simpleFormatter
[logger_root]
level=DEBUG
handlers=fileHandler
[logger_simpleExample]
level=DEBUG
handlers=consoleHandler
qualname=simpleExample
propagate=0
[handler_consoleHandler]
class=StreamHandler
args=(sys.stdout,)
level=DEBUG
formatter=simpleFormatter
[handler_fileHandler]
class=FileHandler
args=('logging.log', 'a')
level=ERROR
formatter=simpleFormatter
[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=
執行輸出:
2017-05-15 11:32:16,539 - simpleExample - DEBUG - debug message
2017-05-15 11:32:16,555 - simpleExample - INFO - info message
2017-05-15 11:32:16,555 - simpleExample - WARNING - warn message
2017-05-15 11:32:16,555 - simpleExample - ERROR - error message
2017-05-15 11:32:16,555 - simpleExample - CRITICAL - critical message
1. 關於fileConfig()
函式的說明:
該函式實際上是對configparser
模組的封裝,關於configparser
模組的介紹請參考<。
函式定義:
該函式定義在loging.config模組下:
logging.config.fileConfig(fname, defaults=None, disable_existing_loggers=True)
引數:
- fname:表示配置檔案的檔名或檔案物件
- defaults:指定傳給ConfigParser的預設值
- disable_existing_loggers:這是一個布林型值,預設值為True(為了向後相容)表示禁用已經存在的logger,除非它們或者它們的祖先明確的出現在日誌配置中;如果值為False則對已存在的loggers保持啟動狀態。
2. 配置檔案格式說明:
上面提到過,fileConfig()
函式是對ConfigParser/configparser
模組的封裝,也就是說fileConfig()
函式是基於ConfigParser/configparser
模組來理解日誌配置檔案的。換句話說,fileConfig()
函式所能理解的配置檔案基礎格式是與ConfigParser/configparser
模組一致的,只是在此基礎上對檔案中包含的section
和option
做了一下規定和限制,比如:
-
1)配置檔案中一定要包含
loggers
、handlers
、formatters
這些section,它們通過keys
這個option來指定該配置檔案中已經定義好的loggers、handlers和formatters,多個值之間用逗號分隔;另外loggers
這個section中的keys一定要包含root這個值; -
2)
loggers
、handlers
、formatters
中所指定的日誌器、處理器和格式器都需要在下面以單獨的section進行定義。seciton的命名規則為[logger_loggerName]
、[formatter_formatterName]
、[handler_handlerName]
-
3)定義logger的section必須指定
level
和handlers
這兩個option,level
的可取值為DEBUG
、INFO
、WARNING
、ERROR
、CRITICAL
、NOTSET
,其中NOTSET
表示所有級別的日誌訊息都要記錄,包括使用者定義級別;handlers
的值是以逗號分隔的handler名字列表,這裡出現的handler必須出現在[handlers]這個section中,並且相應的handler必須在配置檔案中有對應的section定義; -
4)對於非root logger來說,除了
level
和handlers
這兩個option之外,還需要一些額外的option,其中qualname
是必須提供的option,它表示在logger層級中的名字,在應用程式碼中通過這個名字得到logger;propagate
是可選項,其預設是為1,表示訊息將會傳遞給高層次logger的handler,通常我們需要指定其值為0,這個可以看下下面的例子;另外,對於非root logger的level如果設定為NOTSET,系統將會查詢高層次的logger來決定此logger的有效level。 -
5)定義handler的section中必須指定
class
和args
這兩個option,level
和formatter
為可選option;class
表示用於建立handler的類名,args
表示傳遞給class
所指定的handler類初始化方法引數
,它必須是一個元組(tuple)的形式,即便只有一個引數值也需要是一個元組的形式;level
與logger中的level一樣,而formatter
指定的是該處理器所使用的格式器,這裡指定的格式器名稱必須出現在formatters
這個section中,且在配置檔案中必須要有這個formatter的section定義;如果不指定formatter則該handler將會以訊息本身作為日誌訊息進行記錄,而不新增額外的時間、日誌器名稱等資訊; -
6)定義formatter的sectioin中的option都是可選的,其中包括
format
用於指定格式字串,預設為訊息字串本身;datefmt
用於指定asctime的時間格式,預設為'%Y-%m-%d %H:%M:%S'
;class
用於指定格式器類名,預設為logging.Formatter;
說明:
配置檔案中的
class
指定類名時,該類名可以是相對於logging模組的相對值,如:FileHandler
、handlers.TimeRotatingFileHandler
;也可以是一個絕對路徑值,通過普通的import機制來解析,如自定義的handler類mypackage.mymodule.MyHandler
,但是mypackage需要在Python可用的匯入路徑中--sys.path。
3. 對於propagate屬性的說明
例項1:
我們把logging.conf
中simpleExample這個handler定義中的propagate屬性值改為1,或者刪除這個option(預設值就是1):
[logger_simpleExample]
level=DEBUG
handlers=consoleHandler
qualname=simpleExample
propagate=1
現在來執行同樣的程式碼:
# 讀取日誌配置檔案內容
logging.config.fileConfig('logging.conf')
# 建立一個日誌器logger
logger = logging.getLogger('simpleExample')
# 日誌輸出
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
我們會發現,除了在控制檯有輸出資訊時候,在logging.log檔案中也有內容輸出:
2017-05-15 16:06:25,366 - simpleExample - ERROR - error message
2017-05-15 16:06:25,367 - simpleExample - CRITICAL - critical message
這說明simpleExample這個logger在處理完日誌記錄後,把日誌記錄傳遞給了上級的root logger再次做處理,所有才會有兩個地方都有日誌記錄的輸出。通常,我們都需要顯示的指定propagate的值為0,防止日誌記錄向上層logger傳遞。
例項2:
現在,我們試著用一個沒有在配置檔案中定義的logger名稱來獲取logger:
# 讀取日誌配置檔案內容
logging.config.fileConfig('logging.conf')
# 用一個沒有在配置檔案中定義的logger名稱來建立一個日誌器logger
logger = logging.getLogger('simpleExample1')
# 日誌輸出
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
執行程式後,我們會發現控制檯沒有任何輸出,而logging.log檔案中又多了兩行輸出:
2017-05-15 16:13:16,810 - simpleExample1 - ERROR - error message
2017-05-15 16:13:16,810 - simpleExample1 - CRITICAL - critical message
這是因為,當一個日誌器沒有被設定任何處理器是,系統會去查詢該日誌器的上層日誌器上所設定的日誌處理器來處理日誌記錄。simpleExample1在配置檔案中沒有被定義,因此logging.getLogger(simpleExample1)
這行程式碼這是獲取了一個logger例項,並沒有給它設定任何處理器,但是它的上級日誌器--root logger在配置檔案中有定義且設定了一個FileHandler處理器,simpleExample1處理器最終通過這個FileHandler處理器將日誌記錄輸出到logging.log檔案中了。
三、使用字典配置資訊和dictConfig()函式實現日誌配置
Python 3.2中引入的一種新的配置日誌記錄的方法--用字典來儲存logging配置資訊。這相對於上面所講的基於配置檔案來儲存logging配置資訊的方式來說,功能更加強大,也更加靈活,因為我們可把很多的資料轉換成字典。比如,我們可以使用JSON格式的配置檔案、YAML格式的配置檔案,然後將它們填充到一個配置字典中;或者,我們也可以用Python程式碼構建這個配置字典,或者通過socket接收pickled序列化後的配置資訊。總之,你可以使用你的應用程式可以操作的任何方法來構建這個配置字典。
這個例子中,我們將使用YAML格式來完成與上面同樣的日誌配置。
首先需要安裝PyYAML模組:
pip install PyYAML
Python程式碼:
import logging
import logging.config
import yaml
with open('logging.yml', 'r') as f_conf:
dict_conf = yaml.load(f_conf)
logging.config.dictConfig(dict_conf)
logger = logging.getLogger('simpleExample')
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
logging.yml配置檔案的內容:
version: 1
formatters:
simple:
format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
handlers:
console:
class: logging.StreamHandler
level: DEBUG
formatter: simple
stream: ext://sys.stdout
console_err:
class: logging.StreamHandler
level: ERROR
formatter: simple
stream: ext://sys.stderr
loggers:
simpleExample:
level: DEBUG
handlers: [console]
propagate: yes
root:
level: DEBUG
handlers: [console_err]
輸出結果:
2017-05-21 14:19:31,089 - simpleExample - DEBUG - debug message
2017-05-21 14:19:31,089 - simpleExample - INFO - info message
2017-05-21 14:19:31,089 - simpleExample - WARNING - warn message
2017-05-21 14:19:31,089 - simpleExample - ERROR - error message
2017-05-21 14:19:31,090 - simpleExample - CRITICAL - critical message
1. 關於dictConfig()
函式的說明:
該函式實際上是對configparser
模組的封裝,關於configparser
模組的介紹請參考<。
函式定義:
該函式定義在loging.config模組下:
logging.config.dictConfig(config)
該函式可以從一個字典物件中獲取日誌配置資訊,config引數就是這個字典物件。關於這個字典物件的內容規則會在下面進行描述。
2. 配置字典說明
無論是上面提到的配置檔案,還是這裡的配置字典,它們都要描述出日誌配置所需要建立的各種物件以及這些物件之間的關聯關係。比如,可以先建立一個名額為“simple”的格式器formatter;然後建立一個名為“console”的處理器handler,並指定該handler輸出日誌所使用的格式器為"simple";然後再建立一個日誌器logger,並指定它所使用的處理器為"console"。
傳遞給dictConfig()函式的字典物件只能包含下面這些keys,其中version
是必須指定的key,其它key都是可選項:
key名稱 | 描述 |
---|---|
version | 必選項,其值是一個整數值,表示配置格式的版本,當前唯一可用的值就是1 |
formatters | 可選項,其值是一個字典物件,該字典物件每個元素的key為要定義的格式器名稱,value為格式器的配置資訊組成的dict,如format和datefmt |
filters | 可選項,其值是一個字典物件,該字典物件每個元素的key為要定義的過濾器名稱,value為過濾器的配置資訊組成的dict,如name |
handlers | 可選項,其值是一個字典物件,該字典物件每個元素的key為要定義的處理器名稱,value為處理器的配置資訊組成的dcit,如class、level、formatter和filters,其中class為必選項,其它為可選項;其他配置資訊將會傳遞給class所指定的處理器類的建構函式,如下面的handlers定義示例中的stream、filename、maxBytes和backupCount等 |
loggers | 可選項,其值是一個字典物件,該字典物件每個元素的key為要定義的日誌器名稱,value為日誌器的配置資訊組成的dcit,如level、handlers、filters 和 propagate(yes |
root | 可選項,這是root logger的配置資訊,其值也是一個字典物件。除非在定義其它logger時明確指定propagate值為no,否則root logger定義的handlers都會被作用到其它logger上 |
incremental | 可選項,預設值為False。該選項的意義在於,如果這裡定義的物件已經存在,那麼這裡對這些物件的定義是否應用到已存在的物件上。值為False表示,已存在的物件將會被重新定義。 |
disable_existing_loggers | 可選項,預設值為True。該選項用於指定是否禁用已存在的日誌器loggers,如果incremental的值為True則該選項將會被忽略 |
handlers定義示例:
handlers:
console:
class : logging.StreamHandler
formatter: brief
level : INFO
filters: [allow_foo]
stream : ext://sys.stdout
file:
class : logging.handlers.RotatingFileHandler
formatter: precise
filename: logconfig.log
maxBytes: 1024
backupCount: 3
3. 關於外部物件的訪問
需要說明的是,上面所使用的物件並不限於loggging模組所提供的物件,我們可以實現自己的formatter或handler類。另外,這些類的引數也許需要包含sys.stderr這樣的外部物件。如果配置字典物件是使用Python程式碼構造的,可以直接使用sys.stdout、sys.stderr;但是當通過文字檔案(如JSON、YAML格式的配置檔案)提供配置時就會出現問題,因為在文字檔案中,沒有標準的方法來區分sys.stderr
和字串'sys.stderr'
。為了區分它們,配置系統會在字串值中查詢特定的字首,例如'ext://sys.stderr'中'ext://'會被移除,然後import sys.stderr
。