logging.handlers --- 日志處理程序?

StreamHandler?

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

class logging.StreamHandler(stream=None)?

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

emit(record)?

如果指定了一個(gè)格式化器，它會(huì)被用來(lái)格式化記錄。 隨后記錄會(huì)被寫入到 terminator 之后的流中。 如果存在異常信息，則會(huì)使用 traceback.print_exception() 來(lái)格式化并添加到流中。

flush()?

通過(guò)調(diào)用流的 flush() 方法來(lái)刷新它。 請(qǐng)注意 close() 方法是繼承自 Handler 的所以沒有輸出，因此有時(shí)可能需要顯式地調(diào)用 flush()。

setStream(stream)?

將實(shí)例的流設(shè)為指定值，如果兩者不一致的話。 舊的流會(huì)在設(shè)置新的流之前被刷新。

參數(shù)

stream -- 處理程序應(yīng)當(dāng)使用的流。

返回

舊的流，如果流已被改變的話，如果未被改變則為 None。

3.7 新版功能.

terminator?

當(dāng)將已格式化的記錄寫入到流時(shí)被用作終止符的字符串。 默認(rèn)值為 '\n'。

如果你不希望以換行符終止，你可以將處理程序類實(shí)例的 terminator 屬性設(shè)為空字符串。

在較早的版本中，終止符被硬編碼為 '\n'。

3.2 新版功能.

FileHandler?

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

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

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

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

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

close()?

關(guān)閉文件。

emit(record)?

將記錄輸出到文件。

Note that if the file was closed due to logging shutdown at exit and the file mode is 'w', the record will not be emitted (see bpo-42378).

NullHandler?

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

class logging.NullHandler?

返回一個(gè) NullHandler 類的新實(shí)例。

emit(record)?

此方法不執(zhí)行任何操作。

handle(record)?

此方法不執(zhí)行任何操作。

createLock()?

此方法會(huì)對(duì)鎖返回 None，因?yàn)闆]有下層 I/O 的訪問需要被序列化。

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

WatchedFileHandler?

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

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

這個(gè)處理程序不適合在 Windows 下使用，因?yàn)樵?Windows 下打開的日志文件無(wú)法被移動(dòng)或改名 —— 日志記錄會(huì)使用排他的鎖來(lái)打開文件 —— 因此這樣的處理程序是沒有必要的。 此外，ST_INO 在 Windows 下不受支持；stat() 將總是為該值返回零。

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

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

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

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

reopenIfNeeded()?

檢查文件是否已更改。 如果已更改，則會(huì)刷新并關(guān)閉現(xiàn)有流然后重新打開文件，這通常是將記錄輸出到文件的先導(dǎo)操作。

3.6 新版功能.

emit(record)?

將記錄輸出到文件，但如果文件已更改則會(huì)先調(diào)用 reopenIfNeeded() 來(lái)重新打開它。

BaseRotatingHandler?

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

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

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

namer?

如果此屬性被設(shè)為一個(gè)可調(diào)用對(duì)象，則 rotation_filename() 方法會(huì)委托給該可調(diào)用對(duì)象。 傳給該可調(diào)用對(duì)象的形參與傳給 rotation_filename() 的相同。

備注

namer 函數(shù)會(huì)在輪換期間被多次調(diào)用，因此它應(yīng)當(dāng)盡可能的簡(jiǎn)單快速。 它還應(yīng)當(dāng)對(duì)給定的輸入每次都返回相同的輸出，否則輪換行為可能無(wú)法按預(yù)期工作。

It's also worth noting that care should be taken when using a namer to preserve certain attributes in the filename which are used during rotation. For example, RotatingFileHandler expects to have a set of log files whose names contain successive integers, so that rotation works as expected, and TimedRotatingFileHandler deletes old log files (based on the backupCount parameter passed to the handler's initializer) by determining the oldest files to delete. For this to happen, the filenames should be sortable using the date/time portion of the filename, and a namer needs to respect this. (If a namer is wanted that doesn't respect this scheme, it will need to be used in a subclass of TimedRotatingFileHandler which overrides the getFilesToDelete() method to fit in with the custom naming scheme.)

3.3 新版功能.

rotator?

如果此屬性被設(shè)為一個(gè)可調(diào)用對(duì)象，則 rotate() 方法會(huì)委托給該可調(diào)用對(duì)象。 傳給該可調(diào)用對(duì)象的形參與傳給 rotate() 的相同。

3.3 新版功能.

rotation_filename(default_name)?

當(dāng)輪換時(shí)修改日志文件的文件名。

提供該屬性以便可以提供自定義文件名。

默認(rèn)實(shí)現(xiàn)會(huì)調(diào)用處理程序的 'namer' 屬性，如果它是可調(diào)用對(duì)象的話，并傳給它默認(rèn)的名稱。 如果該屬性不是可調(diào)用對(duì)象 (默認(rèn)值為 None)，則將名稱原樣返回。

參數(shù)

default_name -- 日志文件的默認(rèn)名稱。

3.3 新版功能.

rotate(source, dest)?

當(dāng)執(zhí)行輪換時(shí)，輪換當(dāng)前日志。

默認(rèn)實(shí)現(xiàn)會(huì)調(diào)用處理程序的 'rotator' 屬性，如果它是可調(diào)用對(duì)象的話，并傳給它 source 和 dest 參數(shù)。 如果該屬性不是可調(diào)用對(duì)象 (默認(rèn)值為 None)，則將源簡(jiǎn)單地重命名為目標(biāo)。

參數(shù)

• source -- 源文件名。 這通常為基本文件名，例如 'test.log'。

• dest -- 目標(biāo)文件名。 這通常是源被輪換后的名稱，例如 'test.log.1'。

3.3 新版功能.

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

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

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

RotatingFileHandler?

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

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

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

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

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

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

doRollover()?

執(zhí)行上文所描述的輪換。

emit(record)?

將記錄輸出到文件，以適應(yīng)上文所描述的輪換。

TimedRotatingFileHandler?

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

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

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

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

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

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

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

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

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

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

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

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

如果指定了 errors，它會(huì)被用來(lái)確定編碼錯(cuò)誤的處理方式。

備注

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

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

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

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

doRollover()?

執(zhí)行上文所描述的輪換。

emit(record)?

將記錄輸出到文件，以適應(yīng)上文所描述的輪換。

getFilesToDelete()?

Returns a list of filenames which should be deleted as part of rollover. These are the absolute paths of the oldest backup log files written by the handler.

SocketHandler?

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

class logging.handlers.SocketHandler(host, port)?

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

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

close()?

關(guān)閉套接字。

emit()?

對(duì)記錄的屬性字典執(zhí)行封存并以二進(jìn)制格式將其寫入套接字。 如果套接字存在錯(cuò)誤，則靜默地丟棄數(shù)據(jù)包。 如果連接在此之前丟失，則重新建立連接。 要在接收端將記錄解封并輸出到 LogRecord，請(qǐng)使用 makeLogRecord() 函數(shù)。

handleError()?

處理在 emit() 期間發(fā)生的錯(cuò)誤。 最可能的原因是連接丟失。 關(guān)閉套接字以便我們能在下次事件時(shí)重新嘗試。

makeSocket()?

這是一個(gè)工廠方法，它允許子類定義它們想要的套接字的準(zhǔn)確類型。 默認(rèn)實(shí)現(xiàn)會(huì)創(chuàng)建一個(gè) TCP 套接字 (socket.SOCK_STREAM)。

makePickle(record)?

將記錄的屬性字典封存為帶有長(zhǎng)度前綴的二進(jìn)制格式，并將其返回以準(zhǔn)備通過(guò)套接字進(jìn)行傳輸。 此操作在細(xì)節(jié)上相當(dāng)于:

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

請(qǐng)注意封存操作不是絕對(duì)安全的。 如果你關(guān)心安全問題，你可能會(huì)想要重載此方法以實(shí)現(xiàn)更安全的機(jī)制。 例如，你可以使用 HMAC 對(duì)封存對(duì)象進(jìn)行簽名然后在接收端驗(yàn)證它們，或者你也可以在接收端禁用全局對(duì)象的解封操作。

send(packet)?

將封存后的字節(jié)串 packet 發(fā)送到套接字。 所發(fā)送字節(jié)串的格式與 makePickle() 文檔中的描述一致。

此函數(shù)允許部分發(fā)送，這可能會(huì)在網(wǎng)絡(luò)繁忙時(shí)發(fā)生。

createSocket()?

嘗試創(chuàng)建一個(gè)套接字；失敗時(shí)將使用指數(shù)化回退算法處理。 在失敗初次發(fā)生時(shí)，處理程序?qū)G棄它正嘗試發(fā)送的消息。 當(dāng)后續(xù)消息交由同一實(shí)例處理時(shí)，它將不會(huì)嘗試連接直到經(jīng)過(guò)一段時(shí)間以后。 默認(rèn)形參設(shè)置為初始延遲一秒，如果在延遲之后連接仍然無(wú)法建立，處理程序?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)聽器在處理程序被使用 之后 啟動(dòng)，你可能會(huì)丟失消息（因?yàn)樘幚沓绦蛟谘舆t結(jié)束之前甚至不會(huì)嘗試連接，而在延遲期間靜默地丟棄消息）。

DatagramHandler?

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

class logging.handlers.DatagramHandler(host, port)?

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

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

emit()?

對(duì)記錄的屬性字典執(zhí)行封存并以二進(jìn)制格式將其寫入套接字。 如果套接字存在錯(cuò)誤，則靜默地丟棄數(shù)據(jù)包。 要在接收端將記錄解封并輸出到 LogRecord，請(qǐng)使用 makeLogRecord() 函數(shù)。

makeSocket()?

SocketHandler 的工廠方法會(huì)在此被重載以創(chuàng)建一個(gè) 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)?

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

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

在 3.2 版更改: 添加了 socktype。

close()?

關(guān)閉連接遠(yuǎn)程主機(jī)的套接字。

emit(record)?

記錄會(huì)被格式化，然后發(fā)送到 syslog 服務(wù)器。 如果存在異常信息，則它 不會(huì) 被發(fā)送到服務(wù)器。

在 3.2.1 版更改: (參見: bpo-12168。) 在較早的版本中，發(fā)送至 syslog 守護(hù)程序的消息總是以一個(gè) NUL 字節(jié)結(jié)束，因?yàn)槭刈o(hù)程序的早期版本期望接收一個(gè)以 NUL 結(jié)束的消息 —— 即使它不包含于對(duì)應(yīng)的規(guī)范說(shuō)明 (RFC 5424)。 這些守護(hù)程序的較新版本不再期望接收 NUL 字節(jié)，如果其存在則會(huì)將其去除，而最新的守護(hù)程序（更緊密地遵循 RFC 5424）會(huì)將 NUL 字節(jié)作為消息的一部分傳遞出去。

為了在面對(duì)所有這些不同守護(hù)程序行為時(shí)能夠更方便地處理 syslog 消息，通過(guò)使用類層級(jí)屬性 append_nul，添加 NUL 字節(jié)的操作已被作為可配置項(xiàng)。 該屬性默認(rèn)為 True (保留現(xiàn)有行為) 但可在 SysLogHandler 實(shí)例上設(shè)為 False 以便讓實(shí)例 不會(huì) 添加 NUL 結(jié)束符。

在 3.3 版更改: (參見: bpo-12419。) 在較早的版本中，沒有 "ident" 或 "tag" 前綴工具可以用來(lái)標(biāo)識(shí)消息的來(lái)源。 現(xiàn)在則可以使用一個(gè)類層級(jí)屬性來(lái)設(shè)置它，該屬性默認(rèn)為 "" 表示保留現(xiàn)有行為，但可在 SysLogHandler 實(shí)例上重載以便讓實(shí)例不會(huì)為所處理的每條消息添加標(biāo)識(shí)。 請(qǐng)注意所提供的標(biāo)識(shí)必須為文本而非字節(jié)串，并且它會(huì)被原封不動(dòng)地添加到消息中。

encodePriority(facility, priority)?

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

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

優(yōu)先級(jí)

名稱（字符串）	符號(hào)值
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è)備

名稱（字符串）	符號(hào)值
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)?

將日志記錄級(jí)別名稱映射到 syslog 優(yōu)先級(jí)名稱。 如果你使用自定義級(jí)別，或者如果默認(rèn)算法不適合你的需要，你可能需要重載此方法。 默認(rèn)算法將 DEBUG, INFO, WARNING, ERROR 和 CRITICAL 映射到等價(jià)的 syslog 名稱，并將所有其他級(jí)別名稱映射到 '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')?

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

close()?

這時(shí)，你就可以從注冊(cè)表中移除作為事件日志條目來(lái)源的應(yīng)用名稱。 但是，如果你這樣做，你將無(wú)法如你所預(yù)期的那樣在事件日志查看器中看到這些事件 —— 它必須能訪問注冊(cè)表來(lái)獲取 .dll 名稱。 當(dāng)前版本并不會(huì)這樣做。

emit(record)?

確定消息 ID，事件類別和事件類型，然后將消息記錄到 NT 事件日志中。

getEventCategory(record)?

返回記錄的事件類別。 如果你希望指定你自己的類別就要重載此方法。 此版本將返回 0。

getEventType(record)?

返回記錄的事件類型。 如果你希望指定你自己的類型就要重載此方法。 此版本將使用處理程序的 typemap 屬性來(lái)執(zhí)行映射，該屬性在 __init__() 被設(shè)置為一個(gè)字典，其中包含 DEBUG, INFO, WARNING, ERROR 和 CRITICAL 的映射。 如果你使用你自己的級(jí)別，你將需要重載此方法或者在處理程序的 typemap 屬性中放置一個(gè)合適的字典。

getMessageID(record)?

返回記錄的消息 ID。 如果你使用你自己的消息，你可以通過(guò)將 msg 傳給日志記錄器作為 ID 而非格式字符串實(shí)現(xiàn)此功能。 然后，你可以在這里使用字典查找來(lái)獲取消息 ID。 此版本將返回 1，是 win32service.pyd 中的基本消息 ID。

SMTPHandler?

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

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

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

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

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

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

emit(record)?

對(duì)記錄執(zhí)行格式化并將其發(fā)送到指定的地址。

getSubject(record)?

如果你想要指定一個(gè)基于記錄的主題行，請(qǐng)重載此方法。

MemoryHandler?

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

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

class logging.handlers.BufferingHandler(capacity)?

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

emit(record)?

將記錄添加到緩沖區(qū)。 如果 shouldFlush() 返回真值，則會(huì)調(diào)用 flush() 來(lái)處理緩沖區(qū)。

flush()?

你可以重載此方法來(lái)實(shí)現(xiàn)自定義的刷新行為。 此版本只是將緩沖區(qū)清空。

shouldFlush(record)?

如果緩沖區(qū)容量已滿則返回 True。 可以重載此方法以實(shí)現(xiàn)自定義的刷新策略。

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

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

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

close()?

調(diào)用 flush()，設(shè)置目標(biāo)為 None 并清空緩沖區(qū)。

flush()?

對(duì)于 MemoryHandler，刷新是指將緩沖的記錄發(fā)送到目標(biāo)，如果存在目標(biāo)的話。 當(dāng)此行為發(fā)生時(shí)緩沖區(qū)也將被清空。 如果你想要不同的行為請(qǐng)重載此方法。

setTarget(target)?

設(shè)置此處理程序的目標(biāo)處理程序。

shouldFlush(record)?

檢測(cè)緩沖區(qū)是否已滿或是有記錄為 flushLevel 或更高級(jí)別。

HTTPHandler?

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

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

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

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

mapLogRecord(record)?

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

emit(record)?

將記錄以 URL 編碼字典的形式發(fā)送至 Web 服務(wù)器。 mapLogRecord() 方法會(huì)被用來(lái)將要發(fā)送的記錄轉(zhuǎn)換為字典。

備注

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

QueueHandler?

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

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

class logging.handlers.QueueHandler(queue)?

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

emit(record)?

將準(zhǔn)備 LogRecord 的結(jié)果排入隊(duì)列。 如果發(fā)生了異常（例如由于有界隊(duì)列已滿），則會(huì)調(diào)用 handleError() 方法來(lái)處理錯(cuò)誤。 這可能導(dǎo)致記錄被靜默地丟棄 (如果 logging.raiseExceptions 為 False) 或者消息被打印到 sys.stderr (如果 logging.raiseExceptions 為 True)。

prepare(record)?

準(zhǔn)備用于隊(duì)列的記錄。 此方法返回的對(duì)象會(huì)被排入隊(duì)列。

The base implementation formats the record to merge the message, arguments, and exception 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ā)送記錄被修改后的副本而讓初始記錄保持原樣，則你可能會(huì)想要重載此方法。

enqueue(record)?

使用 put_nowait() 將記錄排入隊(duì)列；如果你想要使用阻塞行為，或超時(shí)設(shè)置，或自定義的隊(duì)列實(shí)現(xiàn)，則你可能會(huì)想要重載此方法。

QueueListener?

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

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

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

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

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

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

dequeue(block)?

從隊(duì)列移出一條記錄并將其返回，可以選擇阻塞。

基本實(shí)現(xiàn)使用 get()。 如果你想要使用超時(shí)設(shè)置或自定義的隊(duì)列實(shí)現(xiàn)，則你可能會(huì)想要重載此方法。

prepare(record)?

準(zhǔn)備一條要處理的記錄。

該實(shí)現(xiàn)只是返回傳入的記錄。 如果你想要對(duì)記錄執(zhí)行任何自定義的 marshal 操作或在將其傳給處理程序之前進(jìn)行調(diào)整，則你可能會(huì)想要重載此方法。

handle(record)?

處理一條記錄。

此方法簡(jiǎn)單地循環(huán)遍歷處理程序，向它們提供要處理的記錄。 實(shí)際傳給處理程序的對(duì)象就是從 prepare() 返回的對(duì)象。

start()?

啟動(dòng)監(jiān)聽器。

此方法啟動(dòng)一個(gè)后臺(tái)線程來(lái)監(jiān)視 LogRecords 隊(duì)列以進(jìn)行處理。

stop()?

停止監(jiān)聽器。

此方法要求線程終止，然后等待它完成終止操作。 請(qǐng)注意在你的應(yīng)用程序退出之前如果你沒有調(diào)用此方法，則可能會(huì)有一些記錄在留在隊(duì)列中，它們將不會(huì)被處理。

enqueue_sentinel()?

將一個(gè)標(biāo)記寫入隊(duì)列以通知監(jiān)聽器退出。 此實(shí)現(xiàn)會(huì)使用 put_nowait()。 如果你想要使得超時(shí)設(shè)置或自定義的隊(duì)列實(shí)現(xiàn)，則你可能會(huì)想要重載此方法。

3.3 新版功能.