新聞中心

這里有您想知道的互聯(lián)網(wǎng)營銷解決方案

創(chuàng)新互聯(lián)Python教程：logging.handlers—-日志處理程序

logging.handlers —- 日志處理程序

源代碼: Lib/logging/handlers.py

Important

此頁面僅包含參考信息。有關(guān)教程，請參閱

基礎(chǔ)教程
進(jìn)階教程
日志記錄操作手冊

這個包提供了以下有用的處理程序。請注意有三個處理程序類 (StreamHandler, FileHandler 和 NullHandler) 實際上是在 logging 模塊本身定義的，但其文檔與其他處理程序一同記錄在此。

StreamHandler

StreamHandler 類位于核心 logging 包，它可將日志記錄輸出發(fā)送到數(shù)據(jù)流例如 sys.stdout, sys.stderr 或任何文件類對象（或者更精確地說，任何支持 write() 和 flush() 方法的對象）。

class logging.StreamHandler(stream=None)

返回一個新的 StreamHandler 類。如果指定了 stream，則實例將用它作為日志記錄輸出；在其他情況下將使用 sys.stderr。

emit(record)
如果指定了一個格式化器，它會被用來格式化記錄。隨后記錄會被寫入到 terminator 之后的流中。如果存在異常信息，則會使用 traceback.print_exception() 來格式化并添加到流中。
flush()
通過調(diào)用流的 flush() 方法來刷新它。請注意 close() 方法是繼承自 Handler 的所以沒有輸出，因此有時可能需要顯式地調(diào)用 flush()。
setStream(stream)
將實例的流設(shè)為指定值，如果兩者不一致的話。舊的流會在設(shè)置新的流之前被刷新。
- 參數(shù)
  stream — 處理程序應(yīng)當(dāng)使用的流。
  返回
  舊的流，如果流已被改變的話，如果未被改變則為 None。
3.7 新版功能.
terminator
當(dāng)將已格式化的記錄寫入到流時被用作終止符的字符串。默認(rèn)值為 '\n'。
如果你不希望以換行符終止，你可以將處理程序類實例的 terminator 屬性設(shè)為空字符串。
在較早的版本中，終止符被硬編碼為 '\n'。
3.2 新版功能.

FileHandler

FileHandler 類位于核心 logging 包，它可將日志記錄輸出到磁盤文件中。它從 StreamHandler 繼承了輸出功能。

class logging.FileHandler(filename, mode=’a’, encoding=None, delay=False, errors=None)

返回一個 FileHandler 類的新實例。將打開指定的文件并將其用作日志記錄流。如果未指定 mode，則會使用 'a'。如果 encoding 不為 None，則會將其用作打開文件的編碼格式。如果 delay 為真值，則文件打開會被推遲至第一次調(diào)用 emit() 時。默認(rèn)情況下，文件會無限增長。如果指定了 errors，它會被用于確定編碼格式錯誤的處理方式。

在 3.6 版更改: 除了字符串值，也接受 Path 對象作為 filename 參數(shù)。

在 3.9 版更改: 增加了 errors 形參。

close()
關(guān)閉文件。
emit(record)
將記錄輸出到文件。
請注意如果文件因日志記錄在退出后終止而被關(guān)閉并且文件打開模式為 ‘w’，則記錄將不會被發(fā)送 (參見 bpo-42378)。

NullHandler

3.1 新版功能.

NullHandler 類位于核心 logging 包，它不執(zhí)行任何格式化或輸出。它實際上是一個供庫開發(fā)者使用的‘無操作’處理程序。

class logging.NullHandler

返回一個 NullHandler 類的新實例。

emit(record)
此方法不執(zhí)行任何操作。
handle(record)
此方法不執(zhí)行任何操作。
createLock()
此方法會對鎖返回 None，因為沒有下層 I/O 的訪問需要被序列化。

請參閱配置庫的日志記錄了解有關(guān)如何使用 NullHandler 的更多信息。

WatchedFileHandler

WatchedFileHandler 類位于 logging.handlers 模塊，這個 FileHandler 用于監(jiān)視它所寫入日志記錄的文件。如果文件發(fā)生變化，它會被關(guān)閉并使用文件名重新打開。

發(fā)生文件更改可能是由于使用了執(zhí)行文件輪換的程序例如 newsyslog 和 logrotate。這個處理程序在 Unix/Linux 下使用，它會監(jiān)視文件來查看自上次發(fā)出數(shù)據(jù)后是否有更改。（如果文件的設(shè)備或 inode 發(fā)生變化就認(rèn)為已被更改。）如果文件被更改，則會關(guān)閉舊文件流，并再打開文件以獲得新文件流。

這個處理程序不適合在 Windows 下使用，因為在 Windows 下打開的日志文件無法被移動或改名 —— 日志記錄會使用排他的鎖來打開文件 —— 因此這樣的處理程序是沒有必要的。此外，ST_INO 在 Windows 下不受支持；stat() 將總是為該值返回零。

class logging.handlers.WatchedFileHandler(filename, mode=’a’, encoding=None, delay=False, errors=None)

返回一個 WatchedFileHandler 類的新實例。將打開指定的文件并將其用作日志記錄流。如果未指定 mode，則會使用 'a'。如果 encoding 不為 None，則會將其用作打開文件的編碼格式。如果 delay 為真值，則文件打開會被推遲至第一次調(diào)用 emit() 時。默認(rèn)情況下，文件會無限增長。如果提供了 errors，它會被用于確定編碼格式錯誤的處理方式。

在 3.6 版更改: 除了字符串值，也接受 Path 對象作為 filename 參數(shù)。

在 3.9 版更改: 增加了 errors 形參。

reopenIfNeeded()
檢查文件是否已更改。如果已更改，則會刷新并關(guān)閉現(xiàn)有流然后重新打開文件，這通常是將記錄輸出到文件的先導(dǎo)操作。
3.6 新版功能.
emit(record)
將記錄輸出到文件，但如果文件已更改則會先調(diào)用 reopenIfNeeded() 來重新打開它。

BaseRotatingHandler

BaseRotatingHandler 類位于 logging.handlers 模塊中，它是輪換文件處理程序類 RotatingFileHandler 和 TimedRotatingFileHandler 的基類。你不需要實例化此類，但它具有你可能需要重載的屬性和方法。

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)

類的形參與 FileHandler 的相同。其屬性有:

namer
如果此屬性被設(shè)為一個可調(diào)用對象，則 rotation_filename() 方法會委托給該可調(diào)用對象。傳給該可調(diào)用對象的形參與傳給 rotation_filename() 的相同。
備注
namer 函數(shù)會在輪換期間被多次調(diào)用，因此它應(yīng)當(dāng)盡可能的簡單快速。它還應(yīng)當(dāng)對給定的輸入每次都返回相同的輸出，否則輪換行為可能無法按預(yù)期工作。
還有一點值得注意的是當(dāng)使用命名器來保存文件名中要在輪換中使用的特定屬性時必須小心處理。例如，RotatingFileHandler 會要求有一組名稱中包含連續(xù)整數(shù)的日志文件，以便輪換的效果能滿足預(yù)期，而 TimedRotatingFileHandler 會通過確定要刪除的最舊文件（根據(jù)傳遞縱使中處理句柄的初始化器的 backupCount 形參）來刪除舊的日志文件。為了達(dá)成這樣的效果，文件名應(yīng)當(dāng)是可以使用文件名的日期/時間部分來排序的，而且命名器需要遵循此排序。（如果想使用不遵循此規(guī)則的命名器，則需要在一個重載了 getFilesToDelete() 方法的 TimedRotatingFileHandler 的子類中使用它以便與自定義的命名規(guī)則進(jìn)行配合。）
3.3 新版功能.
rotator
如果此屬性被設(shè)為一個可調(diào)用對象，則 rotate() 方法會委托給該可調(diào)用對象。傳給該可調(diào)用對象的形參與傳給 rotate() 的相同。
3.3 新版功能.
rotation_filename(default_name)
當(dāng)輪換時修改日志文件的文件名。
提供該屬性以便可以提供自定義文件名。
默認(rèn)實現(xiàn)會調(diào)用處理程序的 ‘namer’ 屬性，如果它是可調(diào)用對象的話，并傳給它默認(rèn)的名稱。如果該屬性不是可調(diào)用對象 (默認(rèn)值為 None)，則將名稱原樣返回。
- 參數(shù)
  default_name — 日志文件的默認(rèn)名稱。
3.3 新版功能.
rotate(source, dest)
當(dāng)執(zhí)行輪換時，輪換當(dāng)前日志。
默認(rèn)實現(xiàn)會調(diào)用處理程序的 ‘rotator’ 屬性，如果它是可調(diào)用對象的話，并傳給它 source 和 dest 參數(shù)。如果該屬性不是可調(diào)用對象 (默認(rèn)值為 None)，則將源簡單地重命名為目標(biāo)。
- 參數(shù)
  - source — 源文件名。這通常為基本文件名，例如 ‘test.log’。
  - dest — 目標(biāo)文件名。這通常是源被輪換后的名稱，例如 ‘test.log.1’。

 
 
 
 
  
  
  
  3.3 新版功能.

該屬性存在的理由是讓你不必進(jìn)行子類化 —— 你可以使用與 RotatingFileHandler 和 TimedRotatingFileHandler 的實例相同的可調(diào)用對象。如果 namer 或 rotator 可調(diào)用對象引發(fā)了異常，將會按照與 emit() 調(diào)用期間的任何其他異常相同的方式來處理，例如通過處理程序的 handleError() 方法。

如果你需要對輪換進(jìn)程執(zhí)行更多的修改，你可以重載這些方法。

請參閱利用 rotator 和 namer 自定義日志輪換操作獲取具體示例。

RotatingFileHandler

RotatingFileHandler 類位于 logging.handlers 模塊，它支持磁盤日志文件的輪換。

class logging.handlers.RotatingFileHandler(filename, mode=’a’, maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

返回一個 RotatingFileHandler 類的新實例。將打開指定的文件并將其用作日志記錄流。如果未指定 mode，則會使用 'a'。如果 encoding 不為 None，則會將其用作打開文件的編碼格式。如果 delay 為真值，則文件打開會被推遲至第一次調(diào)用 emit()。默認(rèn)情況下，文件會無限增長。如果提供了 errors，它會被用于確定編碼格式錯誤的處理方式。

你可以使用 maxBytes 和 backupCount 值來允許文件以預(yù)定的大小執(zhí)行 rollover。當(dāng)即將超出預(yù)定大小時，將關(guān)閉舊文件并打開一個新文件用于輸出。只要當(dāng)前日志文件長度接近 maxBytes 就會發(fā)生輪換；但是如果 maxBytes 或 backupCount 兩者之一的值為零，就不會發(fā)生輪換，因此你通常要設(shè)置 backupCount 至少為 1，而 maxBytes 不能為零。當(dāng) backupCount 為非零值時，系統(tǒng)將通過為原文件名添加擴(kuò)展名 ‘.1’, ‘.2’ 等來保存舊日志文件。例如，當(dāng) backupCount 為 5 而基本文件名為 app.log 時，你將得到 app.log, app.log.1, app.log.2 直至 app.log.5。當(dāng)前被寫入的文件總是 app.log。當(dāng)此文件寫滿時，它會被關(guān)閉并重戶名為 app.log.1，而如果文件 app.log.1, app.log.2 等存在，則它們會被分別重命名為 app.log.2, app.log.3 等等。

在 3.6 版更改: 除了字符串值，也接受 Path 對象作為 filename 參數(shù)。

在 3.9 版更改: 增加了 errors 形參。

doRollover()
執(zhí)行上文所描述的輪換。
emit(record)
將記錄輸出到文件，以適應(yīng)上文所描述的輪換。

TimedRotatingFileHandler

TimedRotatingFileHandler 類位于 logging.handlers 模塊，它支持基于特定時間間隔的磁盤日志文件輪換。

class logging.handlers.TimedRotatingFileHandler(filename, when=’h’, interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

返回一個新的 TimedRotatingFileHandler 類實例。指定的文件會被打開并用作日志記錄的流。對于輪換操作它還會設(shè)置文件名前綴。輪換的發(fā)生是基于 when 和 interval 的積。

你可以使用 when 來指定 interval 的類型。可能的值列表如下。請注意它們不是大小寫敏感的。

值	間隔類型	如果/如何使用 atTime
`‘S’`	秒	忽略
`‘M’`	分鐘	忽略
`‘H’`	小時	忽略
`‘D’`	天	忽略
`‘W0’-‘W6’`	工作日(0=星期一)	用于計算初始輪換時間
`‘midnight’`	如果未指定 atTime 則在午夜執(zhí)行輪換，否則將使用 atTime。	用于計算初始輪換時間

當(dāng)使用基于星期的輪換時，星期一為 ‘W0’，星期二為 ‘W1’，以此類推直至星期日為 ‘W6’。在這種情況下，傳入的 interval 值不會被使用。

系統(tǒng)將通過為文件名添加擴(kuò)展名來保存舊日志文件。擴(kuò)展名是基于日期和時間的，根據(jù)輪換間隔的長短使用 strftime 格式 %Y-%m-%d_%H-%M-%S 或是其中有變動的部分。

當(dāng)首次計算下次輪換的時間時（即當(dāng)處理程序被創(chuàng)建時），現(xiàn)有日志文件的上次被修改時間或者當(dāng)前時間會被用來計算下次輪換的發(fā)生時間。

如果 utc 參數(shù)為真值，將使用 UTC 時間；否則會使用本地時間。

如果 backupCount 不為零，則最多將保留 backupCount 個文件，而如果當(dāng)輪換發(fā)生時創(chuàng)建了更多的文件，則最舊的文件會被刪除。刪除邏輯使用間隔時間來確定要刪除的文件，因此改變間隔時間可能導(dǎo)致舊文件被繼續(xù)保留。

如果 delay 為真值，則會將文件打開延遲到首次調(diào)用 emit() 的時候。

如果 atTime 不為 None，則它必須是一個 datetime.time 的實例，該實例指定輪換在一天內(nèi)的發(fā)生時間，用于輪換被設(shè)為“在午夜”或“在每星期的某一天”之類的情況。請注意在這些情況下，atTime 值實際上會被用于計算初始輪換，而后續(xù)輪換將會通過正常的間隔時間計算來得出。

如果指定了 errors，它會被用來確定編碼錯誤的處理方式。

備注

初始輪換時間的計算是在處理程序被初始化時執(zhí)行的。后續(xù)輪換時間的計算則僅在輪換發(fā)生時執(zhí)行，而只有當(dāng)提交輸出時輪換才會發(fā)生。如果不記住這一點，你就可能會感到困惑。例如，如果設(shè)置時間間隔為“每分鐘”，那并不意味著你總會看到（文件名中）帶有間隔一分鐘時間的日志文件；如果在應(yīng)用程序執(zhí)行期間，日志記錄輸出的生成頻率高于每分鐘一次，那么你可以預(yù)期看到間隔一分鐘時間的日志文件。另一方面，如果（假設(shè)）日志記錄消息每五分鐘才輸出一次，那么文件時間將會存在對應(yīng)于沒有輸出（因而沒有輪換）的缺失。

在 3.4 版更改: 添加了 atTime 形參。

在 3.6 版更改: 除了字符串值，也接受 Path 對象作為 filename 參數(shù)。

在 3.9 版更改: 增加了 errors 形參。

doRollover()
執(zhí)行上文所描述的輪換。
emit(record)
將記錄輸出到文件，以適應(yīng)上文所描述的輪換。
getFilesToDelete()
返回由應(yīng)當(dāng)作為輪轉(zhuǎn)的一部分被刪除的文件名組成的列表。它們是由處理程序?qū)懭氲淖钆f的備份日志文件的絕對路徑。

SocketHandler

SocketHandler 類位于 logging.handlers 模塊，它會將日志記錄輸出發(fā)送到網(wǎng)絡(luò)套接字。基類所使用的是 TCP 套接字。

class logging.handlers.SocketHandler(host, port)

返回一個 SocketHandler 類的新實例，該實例旨在與使用 host 與 port 給定地址的遠(yuǎn)程主機(jī)進(jìn)行通信。

在 3.4 版更改: 如果 port 指定為 None，會使用 host 中的值來創(chuàng)建一個 Unix 域套接字 —— 在其他情況下，則會創(chuàng)建一個 TCP 套接字。

close()
關(guān)閉套接字。
emit()
對記錄的屬性字典執(zhí)行封存并以二進(jìn)制格式將其寫入套接字。如果套接字存在錯誤，則靜默地丟棄數(shù)據(jù)包。如果連接在此之前丟失，則重新建立連接。要在接收端將記錄解封并輸出到 LogRecord，請使用 makeLogRecord() 函數(shù)。
handleError()
處理在 emit() 期間發(fā)生的錯誤。最可能的原因是連接丟失。關(guān)閉套接字以便我們能在下次事件時重新嘗試。
makeSocket()
這是一個工廠方法，它允許子類定義它們想要的套接字的準(zhǔn)確類型。默認(rèn)實現(xiàn)會創(chuàng)建一個 TCP 套接字 (socket.SOCK_STREAM)。
makePickle(record)
將記錄的屬性字典封存為帶有長度前綴的二進(jìn)制格式，并將其返回以準(zhǔn)備通過套接字進(jìn)行傳輸。此操作在細(xì)節(jié)上相當(dāng)于:
```
   
   
   
   
    
    
    
    data = pickle.dumps(record_attr_dict, 1)    
    
    
    datalen = struct.pack('>L', len(data))    
    
    
    return datalen + data   
   
   
   
```
請注意封存操作不是絕對安全的。如果你關(guān)心安全問題，你可能會想要重載此方法以實現(xiàn)更安全的機(jī)制。例如，你可以使用 HMAC 對封存對象進(jìn)行簽名然后在接收端驗證它們，或者你也可以在接收端禁用全局對象的解封操作。
send(packet)
將封存后的字節(jié)串 packet 發(fā)送到套接字。所發(fā)送字節(jié)串的格式與 makePickle() 文檔中的描述一致。
此函數(shù)允許部分發(fā)送，這可能會在網(wǎng)絡(luò)繁忙時發(fā)生。
createSocket()
嘗試創(chuàng)建一個套接字；失敗時將使用指數(shù)化回退算法處理。在失敗初次發(fā)生時，處理程序?qū)G棄它正嘗試發(fā)送的消息。當(dāng)后續(xù)消息交由同一實例處理時，它將不會嘗試連接直到經(jīng)過一段時間以后。默認(rèn)形參設(shè)置為初始延遲一秒，如果在延遲之后連接仍然無法建立，處理程序?qū)⒚看伟蜒舆t翻倍直至達(dá)到 30 秒的最大值。
此行為由下列處理程序?qū)傩钥刂?
- retryStart (初始延遲，默認(rèn)為 1.0 秒)。
- retryFactor (倍數(shù)，默認(rèn)為 2.0)。
- retryMax (最大延遲，默認(rèn)為 30.0 秒)。
這意味著如果遠(yuǎn)程監(jiān)聽器在處理程序被使用之后啟動，你可能會丟失消息（因為處理程序在延遲結(jié)束之前甚至不會嘗試連接，而在延遲期間靜默地丟棄消息）。

DatagramHandler

DatagramHandler 類位于 logging.handlers 模塊，它繼承自 SocketHandler，支持通過 UDP 套接字發(fā)送日志記錄消息。

class logging.handlers.DatagramHandler(host, port)

返回一個 DatagramHandler 類的新實例，該實例旨在與使用 host 與 port 給定地址的遠(yuǎn)程主機(jī)進(jìn)行通信。

備注

As UDP is not a streaming protocol, there is no persistent connection between an instance of this handler and host. For this reason, when using a network socket, a DNS lookup might have to be made each time an event is logged, which can introduce some latency into the system. If this affects you, you can do a lookup yourself and initialize this handler using the looked-up IP address rather than the hostname.

在 3.4 版更改: 如果 port 指定為 None，會使用 host 中的值來創(chuàng)建一個 Unix 域套接字 —— 在其他情況下，則會創(chuàng)建一個 UDP 套接字。

emit()
對記錄的屬性字典執(zhí)行封存并以二進(jìn)制格式將其寫入套接字。如果套接字存在錯誤，則靜默地丟棄數(shù)據(jù)包。要在接收端將記錄解封并輸出到 LogRecord，請使用 makeLogRecord() 函數(shù)。
makeSocket()
SocketHandler 的工廠方法會在此被重載以創(chuàng)建一個 UDP 套接字 (socket.SOCK_DGRAM)。
send(s)
將封存后的字節(jié)串發(fā)送到套接字。所發(fā)送字節(jié)串的格式與 SocketHandler.makePickle() 文檔中的描述一致。

SysLogHandler

SysLogHandler 類位于 logging.handlers 模塊，它支持將日志記錄消息發(fā)送到遠(yuǎn)程或本地 Unix syslog。

class logging.handlers.SysLogHandler(address=(‘localhost’, SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)

返回一個 SysLogHandler 類的新實例用來與通過 address 以 (host, port) 元組形式給出地址的遠(yuǎn)程 Unix 機(jī)器進(jìn)行通訊。如果未指定 address，則使用 ('localhost', 514)。該地址會被用于打開套接字。提供 (host, port) 元組的一種替代方式是提供字符串形式的地址，例如 ‘/dev/log’。在這種情況下，會使用 Unix 域套接字將消息發(fā)送到 syslog。如果未指定 facility，則使用 LOG_USER。打開的套接字類型取決于 socktype 參數(shù)，該參數(shù)的默認(rèn)值為 socket.SOCK_DGRAM 即打開一個 UDP 套接字。要打開一個 TCP 套接字（用來配合較新的 syslog 守護(hù)程序例如 rsyslog 使用），請指定值為 socket.SOCK_STREAM。

請注意如果你的服務(wù)器不是在 UDP 端口 514 上進(jìn)行偵聽，則 SysLogHandler 可能無法正常工作。在這種情況下，請檢查你應(yīng)當(dāng)為域套接字所使用的地址 —— 它依賴于具體的系統(tǒng)。例如，在 Linux 上通常為 ‘/dev/log’ 而在 OS/X 上則為 ‘/var/run/syslog’。你需要檢查你的系統(tǒng)平臺并使用適當(dāng)?shù)牡刂罚ㄈ绻愕膽?yīng)用程序需要在多個平臺上運行則可能需要在運行時進(jìn)行這樣的檢查）。在 Windows 上，你大概必須要使用 UDP 選項。

備注

On macOS 12.x (Monterey), Apple has changed the behaviour of their syslog daemon - it no longer listens on a domain socket. Therefore, you cannot expect SysLogHandler to work on this system.

See gh-91070 for more information.

在 3.2 版更改: 添加了 socktype。

close()
關(guān)閉連接遠(yuǎn)程主機(jī)的套接字。
createSocket()
Tries to create a socket and, if it’s not a datagram socket, connect it to the other end. This method is called during handler initialization, but it’s not regarded as an error if the other end isn’t listening at this point - the method will be called again when emitting an event, if but it’s not regarded as an error if the other end isn’t listening yet —- the method will be called again when emitting an event, if there is no socket at that point.
3.11 新版功能.
emit(record)
記錄會被格式化，然后發(fā)送到 syslog 服務(wù)器。如果存在異常信息，則它不會被發(fā)送到服務(wù)器。
在 3.2.1 版更改: (參見: bpo-12168。) 在較早的版本中，發(fā)送至 syslog 守護(hù)程序的消息總是以一個 NUL 字節(jié)結(jié)束，因為守護(hù)程序的早期版本期望接收一個以 NUL 結(jié)束的消息 —— 即使它不包含于對應(yīng)的規(guī)范說明 (RFC 5424)。這些守護(hù)程序的較新版本不再期望接收 NUL 字節(jié)，如果其存在則會將其去除，而最新的守護(hù)程序（更緊密地遵循 RFC 5424）會將 NUL 字節(jié)作為消息的一部分傳遞出去。
為了在面對所有這些不同守護(hù)程序行為時能夠更方便地處理 syslog 消息，通過使用類層級屬性 append_nul，添加 NUL 字節(jié)的操作已被作為可配置項。該屬性默認(rèn)為 True (保留現(xiàn)有行為) 但可在 SysLogHandler 實例上設(shè)為 False 以便讓實例不會添加 NUL 結(jié)束符。
在 3.3 版更改: (參見: bpo-12419。) 在較早的版本中，沒有 “ident” 或 “tag” 前綴工具可以用來標(biāo)識消息的來源。現(xiàn)在則可以使用一個類層級屬性來設(shè)置它，該屬性默認(rèn)為 "" 表示保留現(xiàn)有行為，但可在 SysLogHandler 實例上重載以便讓實例不會為所處理的每條消息添加標(biāo)識。請注意所提供的標(biāo)識必須為文本而非字節(jié)串，并且它會被原封不動地添加到消息中。

encodePriority(facility, priority)

將功能和優(yōu)先級編碼為一個整數(shù)。你可以傳入字符串或者整數(shù) —— 如果傳入的是字符串，則會使用內(nèi)部的映射字典將其轉(zhuǎn)換為整數(shù)。

符號 LOG_ 的值在 SysLogHandler 中定義并且是 sys/syslog.h 頭文件中所定義值的鏡像。

優(yōu)先級

名稱（字符串）	符號值
`alert`	LOG_ALERT
`crit` 或 `critical`	LOG_CRIT
`debug`	LOG_DEBUG
`emerg` 或 `panic`	LOG_EMERG
`err` 或 `error`	LOG_ERR
`info`	LOG_INFO
`notice`	LOG_NOTICE
`warn` 或 `warning`	LOG_WARNING

設(shè)備

名稱（字符串）	符號值
`auth`	LOG_AUTH
`authpriv`	LOG_AUTHPRIV
`cron`	LOG_CRON
`daemon`	LOG_DAEMON
`ftp`	LOG_FTP
`kern`	LOG_KERN
`lpr`	LOG_LPR
`mail`	LOG_MAIL
`news`	LOG_NEWS
`syslog`	LOG_SYSLOG
`user`	LOG_USER
`uucp`	LOG_UUCP
`local0`	LOG_LOCAL0
`local1`	LOG_LOCAL1
`local2`	LOG_LOCAL2
`local3`	LOG_LOCAL3
`local4`	LOG_LOCAL4
`local5`	LOG_LOCAL5
`local6`	LOG_LOCAL6
`local7`	LOG_LOCAL7

mapPriority(levelname)
將日志記錄級別名稱映射到 syslog 優(yōu)先級名稱。如果你使用自定義級別，或者如果默認(rèn)算法不適合你的需要，你可能需要重載此方法。默認(rèn)算法將 DEBUG, INFO, WARNING, ERROR 和 CRITICAL 映射到等價的 syslog 名稱，并將所有其他級別名稱映射到 ‘warning’。

NTEventLogHandler

NTEventLogHandler 類位于 logging.handlers 模塊，它支持將日志記錄消息發(fā)送到本地 Windows NT, Windows 2000 或 Windows XP 事件日志。在你使用它之前，你需要安裝 Mark Hammond 的 python Win32 擴(kuò)展。

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype=’Application’)

返回一個 NTEventLogHandler 類的新實例。 appname 用來定義出現(xiàn)在事件日志中的應(yīng)用名稱。將使用此名稱創(chuàng)建適當(dāng)?shù)淖员項l目。 dllname 應(yīng)當(dāng)給出要包含在日志中的消息定義的 .dll 或 .exe 的完整限定路徑名稱（如未指定則會使用 'win32service.pyd' —— 此文件隨 Win32 擴(kuò)展安裝且包含一些基本的消息定義占位符。請注意使用這些占位符將使你的事件日志變得很大，因為整個消息源都會被放入日志。如果你希望有較小的日志，你必須自行傳入包含你想要在事件日志中使用的消息定義的 .dll 或 .exe 名稱）。 logtype 為 'Application', 'System' 或 'Security' 之一，且默認(rèn)值為 'Application'。

close()
這時，你就可以從注冊表中移除作為事件日志條目來源的應(yīng)用名稱。但是，如果你這樣做，你將無法如你所預(yù)期的那樣在事件日志查看器中看到這些事件 —— 它必須能訪問注冊表來獲取 .dll 名稱。當(dāng)前版本并不會這樣做。
emit(record)
確定消息 ID，事件類別和事件類型，然后將消息記錄到 NT 事件日志中。
getEventCategory(record)
返回記錄的事件類別。如果你希望指定你自己的類別就要重載此方法。此版本將返回 0。
getEventType(record)
返回記錄的事件類型。如果你希望指定你自己的類型就要重載此方法。此版本將使用處理程序的 typemap 屬性來執(zhí)行映射，該屬性在 __init__() 被設(shè)置為一個字典，其中包含 DEBUG, INFO, WARNING, ERROR 和 CRITICAL 的映射。如果你使用你自己的級別，你將需要重載此方法或者在處理程序的 typemap 屬性中放置一個合適的字典。
getMessageID(record)
返回記錄的消息 ID。如果你使用你自己的消息，你可以通過將 msg 傳給日志記錄器作為 ID 而非格式字符串實現(xiàn)此功能。然后，你可以在這里使用字典查找來獲取消息 ID。此版本將返回 1，是 win32service.pyd 中的基本消息 ID。

SMTPHandler

SMTPHandler 類位于 logging.handlers 模塊，它支持將日志記錄消息通過 SMTP 發(fā)送到一個電子郵件地址。

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

返回一個 SMTPHandler 類的新實例。該實例使用電子郵件的發(fā)件人、收件人地址和主題行進(jìn)行初始化。 toaddrs 應(yīng)當(dāng)為字符串列表。要指定一個非標(biāo)準(zhǔn) SMTP 端口，請使用 (host, port) 元組格式作為 mailhost 參數(shù)。如果你使用一個字符串，則會使用標(biāo)準(zhǔn) SMTP 端口。如果你的 SMTP 服務(wù)器要求驗證，你可以指定一個 (username, password) 元組作為 credentials 參數(shù)。

要指定使用安全協(xié)議 (TLS)，請傳入一個元組作為 secure 參數(shù)。這將僅在提供了驗證憑據(jù)時才能被使用。元組應(yīng)當(dāng)或是一個空元組，或是一個包含密鑰文件名的單值元組，或是一個包含密鑰文件和證書文件的 2 值元組。（此元組會被傳給 smtplib.SMTP.starttls() 方法。）

可以使用 timeout 參數(shù)為與 SMTP 服務(wù)器的通信指定超時限制。

3.3 新版功能: 增加了 timeout 參數(shù)。

emit(record)
對記錄執(zhí)行格式化并將其發(fā)送到指定的地址。
getSubject(record)
如果你想要指定一個基于記錄的主題行，請重載此方法。

MemoryHandler

MemoryHandler 類位于 logging.handlers 模塊，它支持在內(nèi)存中緩沖日志記錄，并定期將其刷新到 target 處理程序中。刷新會在緩沖區(qū)滿的時候，或是在遇到特定或更高嚴(yán)重程度事件的時候發(fā)生。

MemoryHandler 是更通用的 BufferingHandler 的子類，后者屬于抽象類。它會在內(nèi)存中緩沖日志記錄。當(dāng)每條記錄被添加到緩沖區(qū)時，會通過調(diào)用 shouldFlush() 來檢查緩沖區(qū)是否應(yīng)當(dāng)刷新。如果應(yīng)當(dāng)刷新，則要使用 flush() 來執(zhí)行刷新。

class logging.handlers.BufferingHandler(capacity)

使用指定容量的緩沖區(qū)初始化處理程序。這里，capacity 是指緩沖的日志記錄數(shù)量。

emit(record)
將記錄添加到緩沖區(qū)。如果 shouldFlush() 返回真值，則會調(diào)用 flush() 來處理緩沖區(qū)。
flush()
你可以重載此方法來實現(xiàn)自定義的刷新行為。此版本只是將緩沖區(qū)清空。
shouldFlush(record)
如果緩沖區(qū)容量已滿則返回 True。可以重載此方法以實現(xiàn)自定義的刷新策略。

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)

返回一個 MemoryHandler 類的新實例。該實例使用 capacity 指定的緩沖區(qū)大?。ㄒ彌_的記錄數(shù)量）來初始化。如果 flushLevel 未指定，則使用 ERROR。如果未指定 target，則需要在此處理程序執(zhí)行任何實際操作之前使用 setTarget() 來設(shè)置目標(biāo)。如果 flushOnClose 指定為 False，則當(dāng)處理程序被關(guān)閉時不會刷新緩沖區(qū)。如果未指定或指定為 True，則當(dāng)處理程序被關(guān)閉時將會發(fā)生之前的緩沖區(qū)刷新行為。

在 3.6 版更改: 增加了 flushOnClose 形參。

close()
調(diào)用 flush()，設(shè)置目標(biāo)為 None 并清空緩沖區(qū)。
flush()
對于 MemoryHandler，刷新是指將緩沖的記錄發(fā)送到目標(biāo)，如果存在目標(biāo)的話。當(dāng)此行為發(fā)生時緩沖區(qū)也將被清空。如果你想要不同的行為請重載此方法。
setTarget(target)
設(shè)置此處理程序的目標(biāo)處理程序。
shouldFlush(record)
檢測緩沖區(qū)是否已滿或是有記錄為 flushLevel 或更高級別。

HTTPHandler

HTTPHandler 類位于 logging.handlers 模塊，它支持使用 GET 或 POST 語義將日志記錄消息發(fā)送到 Web 服務(wù)器。

class logging.handlers.HTTPHandler(host, url, method=’GET’, secure=False, credentials=None, context=None)

返回一個 HTTPHandler 類的新實例。 host 可以為 host:port 的形式，如果你需要使用指定端口號的話。如果沒有指定 method，則會使用 GET。如果 secure 為真值，則將使用 HTTPS 連接。 context 形參可以設(shè)為一個 ssl.SSLContext 實例以配置用于 HTTPS 連接的 SSL 設(shè)置。如果指定了 credentials，它應(yīng)當(dāng)為包含 userid 和 password 的二元組，該元組將被放入使用 Basic 驗證的 HTTP ‘Authorization’ 標(biāo)頭中。如果你指定了 credentials，你還應(yīng)當(dāng)指定 secure=True 這樣你的 userid 和 password 就不會以明文在線路上傳輸。

在 3.5 版更改: 增加了 context 形參。

mapLogRecord(record)
基于 record 提供一個字典，它將被執(zhí)行 URL 編碼并發(fā)送至 Web 服務(wù)器。默認(rèn)實現(xiàn)僅返回 record.__dict__。在只需將 LogRecord 的某個子集發(fā)送至 Web 服務(wù)器，或者需要對發(fā)送至服務(wù)器的內(nèi)容進(jìn)行更多定制時可以重載此方法。
emit(record)
將記錄以 URL 編碼字典的形式發(fā)送至 Web 服務(wù)器。 mapLogRecord() 方法會被用來將要發(fā)送的記錄轉(zhuǎn)換為字典。

備注

由于記錄發(fā)送至 Web 服務(wù)器所需的預(yù)處理與通用的格式化操作不同，使用 setFormatter() 來指定一個 Formatter 用于 HTTPHandler 是沒有效果的。此處理程序不會調(diào)用 format()，而是調(diào)用 mapLogRecord() 然后再調(diào)用 urllib.parse.urlencode() 來以適合發(fā)送至 Web 服務(wù)器的形式對字典進(jìn)行編碼。

QueueHandler

3.2 新版功能.

QueueHandler 類位于 logging.handlers 模塊，它支持將日志記錄消息發(fā)送到一個隊列，例如在 queue 或 multiprocessing 模塊中實現(xiàn)的隊列。

配合 QueueListener 類使用，QueueHandler 可被用來使處理程序在與執(zhí)行日志記錄的線程不同的線程上完成工作。這對 Web 應(yīng)用程序以及其他服務(wù)于客戶端的線程需要盡可能快地響應(yīng)的服務(wù)應(yīng)用程序來說很重要，任何潛在的慢速操作（例如通過 SMTPHandler 發(fā)送郵件）都要在單獨的線程上完成。

class logging.handlers.QueueHandler(queue)

返回一個 QueueHandler 類的新實例。該實例使用隊列來初始化以向其發(fā)送消息。 queue 可以為任何隊列類對象；它由 enqueue() 方法來使用，該方法需要知道如何向其發(fā)送消息。隊列 不要求 具有任務(wù)跟蹤 API，這意味著你可以為 queue 使用 SimpleQueue 實例。

備注

If you are using multiprocessing, you should avoid using SimpleQueue and instead use multiprocessing.Queue.

emit(record)
將準(zhǔn)備 LogRecord 的結(jié)果排入隊列。如果發(fā)生了異常（例如由于有界隊列已滿），則會調(diào)用 handleError() 方法來處理錯誤。這可能導(dǎo)致記錄被靜默地丟棄 (如果 logging.raiseExceptions 為 False) 或者消息被打印到 sys.stderr (如果 logging.raiseExceptions 為 True)。
prepare(record)
準(zhǔn)備用于隊列的記錄。此方法返回的對象會被排入隊列。
The base implementation formats the record to merge the message, arguments, exception and stack information, if present. It also removes unpickleable items from the record in-place. Specifically, it overwrites the record’s msg and message attributes with the merged message (obtained by calling the handler’s format() method), and sets the args, exc_info and exc_text attributes to None.
如果你想要將記錄轉(zhuǎn)換為 dict 或 JSON 字符串，或者發(fā)送記錄被修改后的副本而讓初始記錄保持原樣，則你可能會想要重載此方法。
備注
The base implementation formats the message with arguments, sets the message and msg attributes to the formatted message and sets the args and exc_text attributes to None to allow pickling and to prevent further attempts at formatting. This means that a handler on the QueueListener side won’t have the information to do custom formatting, e.g. of exceptions. You may wish to subclass QueueHandler and override this method to e.g. avoid setting exc_text to None. Note that the message / msg / args changes are related to ensuring the record is pickleable, and you might or might not be able to avoid doing that depending on whether your args are pickleable. (Note that you may have to consider not only your own code but also code in any libraries that you use.)
enqueue(record)
使用 put_nowait() 將記錄排入隊列；如果你想要使用阻塞行為，或超時設(shè)置，或自定義的隊列實現(xiàn)，則你可能會想要重載此方法。

QueueListener

3.2 新版功能.

QueueListener 類位于 logging.handlers 模塊，它支持從一個隊列接收日志記錄消息，例如在 queue 或 multiprocessing 模塊中實現(xiàn)的隊列。消息是在內(nèi)部線程中從隊列接收并在同一線程上傳遞到一個或多個處理程序進(jìn)行處理的。盡管 QueueListener 本身并不是一個處理程序，但由于它要與 QueueHandler 配合工作，因此也在此處介紹。

配合 QueueHandler 類使用，QueueListener 可被用來使處理程序在與執(zhí)行日志記錄的線程不同的線程上完成工作。這對 Web 應(yīng)用程序以及其他服務(wù)于客戶端的線程需要盡可能快地響應(yīng)的服務(wù)應(yīng)用程序來說很重要，任何潛在的慢速動作（例如通過 SMTPHandler 發(fā)送郵件）都要在單獨的線程上完成。

class logging.handlers.QueueListener(queue, \handlers, respect_handler_level=False*)

返回一個 QueueListener 類的新實例。該實例初始化時要傳入一個隊列以向其發(fā)送消息，還要傳入一個處理程序列表用來處理放置在隊列中的條目。隊列可以是任何隊列類對象；它會被原樣傳給 dequeue() 方法，該方法需要知道如何從其獲取消息。隊列 不要求 具有任務(wù)跟蹤 API（但如提供則會使用它），這意味著你可以為 queue 使用 SimpleQueue 實例。

備注

If you are using multiprocessing, you should avoid using SimpleQueue and instead use multiprocessing.Queue.

如果 respect_handler_level 為 True，則在決定是否將消息傳遞給處理程序之前會遵循處理程序的級別（與消息的級別進(jìn)行比較）；在其他情況下，其行為與之前的 Python 版本一致 —— 總是將每條消息傳遞給每個處理程序。

在 3.5 版更改: 增加了 respect_handler_level 參數(shù)。

dequeue(block)
從隊列移出一條記錄并將其返回，可以選擇阻塞。
基本實現(xiàn)使用 get()。如果你想要使用超時設(shè)置或自定義的隊列實現(xiàn)，則你可能會想要重載此方法。
prepare(record)
準(zhǔn)備一條要處理的記錄。
該實現(xiàn)只是返回傳入的記錄。如果你想要對記錄執(zhí)行任何自定義的 marshal 操作或在將其傳給處理程序之前進(jìn)行調(diào)整，則你可能會想要重載此方法。
handle(record)
處理一條記錄。
此方法簡單地循環(huán)遍歷處理程序，向它們提供要處理的記錄。實際傳給處理程序的對象就是從 prepare() 返回的對象。
start()
啟動監(jiān)聽器。
此方法啟動一個后臺線程來監(jiān)視 LogRecords 隊列以進(jìn)行處理。
stop()
停止監(jiān)聽器。
此方法要求線程終止，然后等待它完成終止操作。請注意在你的應(yīng)用程序退出之前如果你沒有調(diào)用此方法，則可能會有一些記錄在留在隊列中，它們將不會被處理。
enqueue_sentinel()
將一個標(biāo)記寫入隊列以通知監(jiān)聽器退出。此實現(xiàn)會使用 put_nowait()。如果你想要使得超時設(shè)置或自定義的隊列實現(xiàn)，則你可能會想要重載此方法。
3.3 新版功能.

參見

模塊 logging

日志記錄模塊的 API 參考。

logging.config 模塊

日志記錄模塊的配置 API 。

標(biāo)題名稱：創(chuàng)新互聯(lián)Python教程：logging.handlers—-日志處理程序
分享URL：http://www.fisionsoft.com.cn/article/cogjcij.html

新聞中心

logging.handlers —- 日志處理程序

StreamHandler

FileHandler

NullHandler

WatchedFileHandler

BaseRotatingHandler

RotatingFileHandler

TimedRotatingFileHandler

SocketHandler

DatagramHandler

SysLogHandler

NTEventLogHandler

SMTPHandler

MemoryHandler

HTTPHandler

QueueHandler

QueueListener

其他資訊