`logging.handlers` — 日誌處理器¶

該軟體包中提供了以下有用的處理器。請注意，其中三個處理器（StreamHandler， FileHandler 和 NullHandler）實際上是在 logging 模組本身中定義的，但已在此處與其他處理器一起記錄。

StreamHandler¶

位於核心 logging 包中的 StreamHandler 類，將日誌輸出傳送到諸如 sys.stdout、sys.stderr 之類的流或任何類檔案物件（或者，更精確地說，任何支援 write() 和 flush() 方法的物件）。

class logging.StreamHandler(stream=None)¶

返回 StreamHandler 類的新例項。如果指定了 stream，則該例項將使用它進行日誌輸出；否則，將使用 sys.stderr。

emit(record)¶: 如果指定了格式化程式，則使用它來格式化記錄。然後將記錄寫入流，後跟 terminator。如果存在異常資訊，則使用 traceback.print_exception() 進行格式化，並將其附加到流中。

flush()¶: 透過呼叫其 flush() 方法來重新整理流。請注意，close() 方法是從 Handler 繼承的，因此不會輸出任何內容，因此有時可能需要顯式呼叫 flush()。

setStream(stream)¶

如果例項的流與指定的值不同，則將其設定為指定的值。在設定新流之前，將重新整理舊流。

引數:: stream – 處理程式應使用的流。
返回:: 如果流已更改，則返回舊流；如果未更改，則返回 None。

3.7 版本加入。

terminator¶

將格式化的記錄寫入流時用作終止符的字串。預設值為 '\n'。

如果您不希望換行符終止，則可以將處理程式例項的 terminator 屬性設定為空字串。

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

3.2 版本加入。

FileHandler¶

位於核心 logging 包中的 FileHandler 類，將日誌輸出傳送到磁碟檔案。它從 StreamHandler 繼承輸出功能。

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

返回 FileHandler 類的新例項。指定的檔案將開啟並用作日誌記錄的流。如果未指定 mode，則使用 'a'。如果 encoding 不是 None，則會使用該編碼開啟檔案。如果 delay 為 true，則檔案開啟將延遲到首次呼叫 emit()。預設情況下，檔案會無限增長。如果指定了 errors，則它用於確定如何處理編碼錯誤。

在 3.6 版本中更改：除了字串值之外，Path 物件也被接受作為 filename 引數。

在 3.9 版本中更改：添加了 errors 引數。

close()¶: 關閉檔案。

emit(record)¶

將記錄輸出到檔案。

請注意，如果由於退出時的日誌記錄關閉而關閉了檔案，並且檔案模式為“w”，則不會發出該記錄（請參閱 bpo-42378）。

NullHandler¶

3.1 版本加入。

位於核心 logging 包中的 NullHandler 類，不執行任何格式化或輸出。它本質上是庫開發人員使用的“無操作”處理程式。

class logging.NullHandler¶

返回 NullHandler 類的新例項。

emit(record)¶: 此方法不執行任何操作。

handle(record)¶: 此方法不執行任何操作。

createLock()¶: 此方法返回 None 作為鎖，因為沒有底層 I/O 需要序列化訪問。

有關如何使用 NullHandler 的更多資訊，請參閱為庫配置日誌記錄。

WatchedFileHandler¶

WatchedFileHandler 類位於 logging.handlers 模組中，它是一個 FileHandler，會監視它正在寫入的日誌檔案。如果檔案發生更改，它將被關閉，並使用檔名重新開啟。

檔案更改可能是由於使用了諸如 newsyslog 和 logrotate 之類的程式執行日誌檔案輪換而發生的。此處理器旨在在 Unix/Linux 下使用，它會監視檔案以檢視自上次發出以來是否已更改。（如果檔案的裝置或 inode 已更改，則認為檔案已更改。）如果檔案已更改，則舊的檔案流將被關閉，並重新開啟該檔案以獲取新的流。

此處理器不適合在 Windows 下使用，因為在 Windows 下，開啟的日誌檔案無法移動或重新命名 - 日誌使用獨佔鎖開啟檔案 - 因此不需要這樣的處理器。此外，Windows 下不支援 ST_INO；stat() 對此值始終返回零。

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

返回 WatchedFileHandler 類的新例項。指定的檔案被開啟並用作日誌記錄的流。如果未指定 *mode*，則使用 'a'。如果 *encoding* 不是 None，則使用該編碼開啟檔案。如果 *delay* 為 true，則檔案開啟將延遲到第一次呼叫 emit()。預設情況下，檔案無限增長。如果提供了 *errors*，它將確定如何處理編碼錯誤。

在 3.6 版本中更改：除了字串值之外，Path 物件也被接受作為 filename 引數。

在 3.9 版本中更改：添加了 errors 引數。

reopenIfNeeded()¶: 檢查檔案是否已更改。如果已更改，則重新整理並關閉現有流，然後再次開啟檔案，通常作為將記錄輸出到檔案的前奏。

3.6 版本新增。

emit(record)¶: 將記錄輸出到檔案，但首先呼叫 reopenIfNeeded() 以在檔案已更改時重新開啟它。

BaseRotatingHandler¶

BaseRotatingHandler 類位於 logging.handlers 模組中，它是輪換檔案處理器 RotatingFileHandler 和 TimedRotatingFileHandler 的基類。你不需要例項化此類，但它具有你可能需要覆蓋的屬性和方法。

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

引數與 FileHandler 的引數相同。屬性如下：

namer¶: 如果此屬性設定為可呼叫物件，則 rotation_filename() 方法將委託給此可呼叫物件。傳遞給可呼叫物件的引數是傳遞給 rotation_filename() 的引數。

註解

命名器函式在滾動期間會被多次呼叫，因此它應該儘可能簡單和快速。對於給定的輸入，它也應該每次都返回相同的輸出，否則滾動行為可能無法按預期工作。

還值得注意的是，在使用命名器時應注意保留檔名中在輪換期間使用的某些屬性。例如，RotatingFileHandler 希望擁有一組名稱包含連續整數的日誌檔案，以便輪換按預期工作，而 TimedRotatingFileHandler 透過確定要刪除的最舊的檔案來刪除舊的日誌檔案（基於傳遞給處理器初始值設定項的 backupCount 引數）。為了實現這一點，檔名應該可以使用檔名的日期/時間部分進行排序，並且命名器需要遵守此規則。（如果需要不遵守此方案的命名器，則需要在 TimedRotatingFileHandler 的子類中使用，該子類會覆蓋 getFilesToDelete() 方法以適應自定義命名方案。）

3.3 版本新增。

rotator¶: 如果此屬性設定為可呼叫物件，則 rotate() 方法將委託給此可呼叫物件。傳遞給可呼叫物件的引數是傳遞給 rotate() 的引數。

3.3 版本新增。

rotation_filename(default_name)¶

輪換時修改日誌檔案的檔名。

提供此功能是為了可以提供自定義檔名。

預設實現會呼叫處理程式的“namer”屬性（如果它是可呼叫的），並將預設名稱傳遞給它。如果該屬性不可呼叫（預設值為 None），則返回的名稱不變。

引數:: default_name – 日誌檔案的預設名稱。

3.3 版本新增。

rotate(source, dest)¶

輪換時，輪換當前日誌。

預設實現會呼叫處理程式的“rotator”屬性（如果它是可呼叫的），並將源和目標引數傳遞給它。如果該屬性不可呼叫（預設值為 None），則只是將源重新命名為目標。

引數:

source – 原始檔名。這通常是基本檔名，例如“test.log”。
dest – 目標檔名。這通常是原始檔輪換的目標，例如“test.log.1”。

3.3 版本新增。

之所以存在這些屬性，是為了避免你必須進行子類化操作 - 你可以將相同的可呼叫物件用於 RotatingFileHandler 和 TimedRotatingFileHandler 的例項。如果 namer 或 rotator 可呼叫物件引發異常，其處理方式將與 emit() 呼叫期間的任何其他異常相同，即透過處理程式的 handleError() 方法。

如果你需要對輪轉處理進行更重大的更改，可以重寫這些方法。

有關示例，請參閱使用 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 為 true，則檔案開啟將延遲到首次呼叫 emit()。預設情況下，檔案會無限增長。如果提供了 errors，則它確定如何處理編碼錯誤。

你可以使用 maxBytes 和 backupCount 值來允許檔案在預定大小處滾動。當大小即將超出時，檔案將被關閉，並會靜默開啟一個新檔案以進行輸出。噹噹前日誌檔案的長度接近 maxBytes 時，會發生滾動；但是，如果 maxBytes 或 backupCount 為零，則永遠不會發生滾動，因此你通常希望將 backupCount 設定為至少 1，並具有非零的 maxBytes。當 backupCount 為非零值時，系統將透過向檔名附加副檔名“.1”、“.2”等來儲存舊的日誌檔案。例如，如果 backupCount 為 5，並且基本檔名為 app.log，你將獲得 app.log、app.log.1、app.log.2，直到 app.log.5。正在寫入的檔案始終是 app.log。當此檔案填滿時，它將被關閉並重命名為 app.log.1，並且如果檔案 app.log.1、app.log.2 等存在，則它們將分別重新命名為 app.log.2、app.log.3 等。

在 3.6 版本中更改：除了字串值之外，Path 物件也被接受作為 filename 引數。

在 3.9 版本中更改：添加了 errors 引數。

doRollover()¶: 如上所述執行滾動。

emit(record)¶: 將記錄輸出到檔案，並按先前描述的方式進行滾動。

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 類的新例項。指定的檔案將被開啟並用作日誌的流。在輪轉時，它還會設定檔名字尾。輪轉基於 when 和 interval 的乘積進行。

你可以使用 when 來指定 interval 的型別。下面是可能值的列表。請注意，它們不區分大小寫。

值	間隔型別	如何/是否使用 atTime
`'S'`	秒	忽略
`'M'`	分鐘	忽略
`'H'`	小時	忽略
`'D'`	天	忽略
`'W0'-'W6'`	工作日（0=星期一）	用於計算初始輪轉時間
`'midnight'`	在午夜輪轉，如果未指定 atTime，則在時間 atTime 輪轉	用於計算初始輪轉時間

當使用基於工作日的輪轉時，星期一指定為“W0”，星期二指定為“W1”，依此類推，直到星期日指定為“W6”。在這種情況下，不會使用為 interval 傳遞的值。

系統將透過向檔名附加副檔名來儲存舊的日誌檔案。副檔名是基於日期和時間的，使用 strftime 格式 %Y-%m-%d_%H-%M-%S 或其前導部分，具體取決於輪轉間隔。

在首次計算下一個輪轉時間時（當建立處理程式時），將使用現有日誌檔案的最後修改時間，或者當前時間來計算下一個輪轉時間。

如果 utc 引數為 true，則將使用 UTC 時間；否則，將使用本地時間。

如果 backupCount 為非零值，則最多會保留 backupCount 個檔案，如果在發生輪轉時將建立更多檔案，則會刪除最舊的檔案。刪除邏輯使用間隔來確定要刪除哪些檔案，因此更改間隔可能會導致舊檔案滯留。

如果 delay 為 true，則檔案開啟將延遲到首次呼叫 emit()。

如果 atTime 不是 None，則它必須是 datetime.time 例項，該例項指定一天中發生輪轉的時間，以處理設定為“在午夜”或“在特定工作日”發生輪轉的情況。請注意，在這些情況下，atTime 值實際上用於計算初始輪轉，隨後的輪轉將透過正常的間隔計算來計算。

如果指定了 errors，則它將用於確定如何處理編碼錯誤。

註解

初始輪轉時間的計算在初始化處理程式時完成。後續輪轉時間的計算僅在發生輪轉時完成，並且僅在輸出輸出時才發生輪轉。如果未牢記這一點，可能會導致一些困惑。例如，如果設定了“每分鐘”的間隔，則並不意味著你總是會看到檔名中的時間間隔為一分鐘的日誌檔案；如果在應用程式執行期間，日誌輸出的生成頻率高於每分鐘一次，那麼你可以期望看到時間間隔為一分鐘的日誌檔案。另一方面，如果日誌訊息僅每五分鐘輸出一次（例如），則檔案時間將存在間隙，對應於未發生輸出（因此未發生輪轉）的分鐘數。

在版本 3.4 中更改：添加了 atTime 引數。

在 3.6 版本中更改：除了字串值之外，Path 物件也被接受作為 filename 引數。

在 3.9 版本中更改：添加了 errors 引數。

doRollover()¶: 如上所述執行滾動。

emit(record)¶: 將記錄輸出到檔案，並按上述方式進行滾動。

getFilesToDelete()¶: 返回一個檔名列表，這些檔名應作為滾動的一部分被刪除。這些是處理程式寫入的最舊備份日誌檔案的絕對路徑。

SocketHandler¶

SocketHandler 類，位於 logging.handlers 模組中，將日誌輸出傳送到網路套接字。基類使用 TCP 套接字。

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

返回 SocketHandler 類的新例項，該例項旨在與地址由 host 和 port 給定的遠端計算機通訊。

在 3.4 版本中更改: 如果 port 被指定為 None，則會使用 host 中的值建立一個 Unix 域套接字；否則，將建立一個 TCP 套接字。

close()¶: 關閉套接字。

emit()¶: 將記錄的屬性字典進行序列化，並以二進位制格式寫入套接字。如果套接字出現錯誤，則靜默丟棄資料包。如果連線先前丟失，則重新建立連線。要在接收端將記錄反序列化為 LogRecord，請使用 makeLogRecord() 函式。

handleError()¶: 處理在 emit() 期間發生的錯誤。最可能的原因是連線丟失。關閉套接字，以便我們可以在下一個事件時重試。

makeSocket()¶: 這是一個工廠方法，允許子類定義他們想要的精確套接字型別。預設實現建立 TCP 套接字 (socket.SOCK_STREAM)。

makePickle(record)¶

將記錄的屬性字典以二進位制格式序列化，並帶有長度字首，然後返回準備好透過套接字傳輸的資料。此操作的詳細資訊等效於

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

請注意，pickle 並非完全安全。如果您擔心安全性，則可能需要覆蓋此方法以實現更安全的機制。例如，您可以使用 HMAC 對 pickle 進行簽名，然後在接收端驗證它們，或者您可以在接收端停用全域性物件的反序列化。

send(packet)¶

將序列化的位元組字串 packet 傳送到套接字。傳送的位元組字串的格式如 makePickle() 的文件中所述。

此函式允許部分發送，這可能在網路繁忙時發生。

createSocket()¶

嘗試建立套接字；如果失敗，則使用指數退避演算法。在初始失敗時，處理程式將丟棄它試圖傳送的訊息。當同一個例項處理後續訊息時，它將不會嘗試連線，直到經過一段時間。預設引數是初始延遲為 1 秒，如果在此延遲之後仍無法建立連線，則處理程式每次都會將延遲加倍，直到最大延遲為 30 秒。

此行為由以下處理程式屬性控制

retryStart (初始延遲，預設為 1.0 秒)。
retryFactor (乘數，預設為 2.0)。
retryMax (最大延遲，預設為 30.0 秒)。

這意味著如果遠端偵聽器在處理程式使用之後啟動，您可能會丟失訊息（因為處理程式甚至不會嘗試連線，直到延遲已過，但只會在延遲期間靜默丟棄訊息）。

DatagramHandler¶

DatagramHandler 類，位於 logging.handlers 模組中，繼承自 SocketHandler 以支援透過 UDP 套接字傳送日誌訊息。

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

返回 DatagramHandler 類的新例項，該例項旨在與地址由 host 和 port 給定的遠端計算機通訊。

註解

由於 UDP 不是流協議，因此此處理程式的例項與 host 之間沒有持久連線。因此，當使用網路套接字時，每次記錄事件時都可能必須進行 DNS 查詢，這可能會在系統中引入一些延遲。如果這影響到您，您可以自己進行查詢，並使用查找出的 IP 地址而不是主機名來初始化此處理程式。

在 3.4 版本中更改: 如果 port 被指定為 None，則會使用 host 中的值建立一個 Unix 域套接字；否則，將建立一個 UDP 套接字。

emit()¶: 將記錄的屬性字典進行序列化，並以二進位制格式寫入套接字。如果套接字出現錯誤，則靜默丟棄資料包。要在接收端將記錄反序列化為 LogRecord，請使用 makeLogRecord() 函式。

makeSocket()¶: 這裡重寫了 SocketHandler 的工廠方法，以建立 UDP 套接字 (socket.SOCK_DGRAM)。

send(s)¶: 將序列化的位元組字串傳送到套接字。傳送的位元組字串的格式如 SocketHandler.makePickle() 的文件中所述。

SysLogHandler¶

SysLogHandler 類，位於 logging.handlers 模組中，支援將日誌訊息傳送到遠端或本地 Unix 系統日誌。

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

返回一個 SysLogHandler 類的新例項，該例項旨在與遠端 Unix 機器通訊，其地址由 address 指定，形式為 (主機, 埠) 元組。如果未指定 address，則使用 ('localhost', 514)。該地址用於開啟套接字。除了提供 (主機, 埠) 元組外，還可以提供字串形式的地址，例如 ‘/dev/log’。在這種情況下，將使用 Unix 域套接字將訊息傳送到 syslog。如果未指定 facility，則使用 LOG_USER。開啟的套接字型別取決於 socktype 引數，該引數預設為 socket.SOCK_DGRAM，因此會開啟一個 UDP 套接字。要開啟 TCP 套接字（用於較新的 syslog 守護程式，如 rsyslog），請指定 socket.SOCK_STREAM 的值。

請注意，如果您的伺服器沒有監聽 UDP 埠 514，SysLogHandler 可能看起來無法工作。在這種情況下，請檢查您應該使用哪個域套接字地址 - 這取決於系統。例如，在 Linux 上通常是 ‘/dev/log’，但在 OS/X 上是 ‘/var/run/syslog’。您需要檢查您的平臺並使用適當的地址（如果您的應用程式需要在多個平臺上執行，您可能需要在執行時執行此檢查）。在 Windows 上，您幾乎必須使用 UDP 選項。

註解

在 macOS 12.x (Monterey) 上，Apple 更改了其 syslog 守護程式的行為 - 它不再監聽域套接字。因此，您不能期望 SysLogHandler 在此係統上工作。

有關詳細資訊，請參閱 gh-91070。

在 3.2 版本中更改: 添加了 socktype。

close()¶: 關閉到遠端主機的套接字。

createSocket()¶: 嘗試建立一個套接字，如果它不是資料報套接字，則將其連線到另一端。此方法在處理程式初始化期間呼叫，但如果另一端此時沒有監聽，則不認為是錯誤 - 如果此時沒有套接字，則在發出事件時將再次呼叫該方法。

在 3.11 版本中新增。

emit(record)¶: 格式化記錄，然後將其傳送到 syslog 伺服器。如果存在異常資訊，則不會將其傳送到伺服器。

在 3.2.1 版本中更改: (請參閱：bpo-12168。) 在早期版本中，傳送到 syslog 守護程式的訊息始終以 NUL 位元組結尾，因為這些守護程式的早期版本需要以 NUL 結尾的訊息 - 即使它不在相關規範中 (RFC 5424)。這些守護程式的更新版本不需要 NUL 位元組，但如果存在則會將其剝離，而更新的版本（更嚴格地遵守 RFC 5424）會將 NUL 位元組作為訊息的一部分傳遞。

為了更輕鬆地處理所有這些不同的守護程式行為中的 syslog 訊息，透過使用類級屬性 append_nul，可以配置是否附加 NUL 位元組。此屬性預設為 True（保留現有行為），但可以在 SysLogHandler 例項上將其設定為 False，以使該例項不附加 NUL 終止符。

在 3.3 版本中更改: (請參閱：bpo-12419。) 在早期版本中，沒有用於標識訊息來源的“ident”或“tag”字首的機制。現在可以使用類級屬性指定此項，預設值為 "" 以保留現有行為，但可以在 SysLogHandler 例項上覆蓋此項，以便該例項將 ident 字首新增到每個處理的訊息。請注意，提供的 ident 必須是文字，而不是位元組，並且會按原樣新增到訊息前面。

encodePriority(facility, priority)¶

將 facility 和 priority 編碼為整數。您可以傳入字串或整數 - 如果傳入字串，則會使用內部對映字典將其轉換為整數。

符號 LOG_ 值在 SysLogHandler 中定義，並映象在 sys/syslog.h 標頭檔案中定義的值。

優先順序

名稱（字串）	符號值
`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

設施

名稱（字串）	符號值
`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 優先順序名稱。如果使用自定義級別，或者預設演算法不適合您的需求，您可能需要重寫此方法。預設演算法將 DEBUG、INFO、WARNING、ERROR 和 CRITICAL 對映到等效的 syslog 名稱，並將所有其他級別名稱對映到 “warning”。

NTEventLogHandler¶

位於 logging.handlers 模組中的 NTEventLogHandler 類支援將日誌訊息傳送到本地 Windows NT、Windows 2000 或 Windows XP 事件日誌。在使用它之前，您需要安裝 Mark Hammond 的 Python Win32 擴充套件。

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

返回一個 NTEventLogHandler 類的新例項。appname 用於定義在事件日誌中顯示的應用程式名稱。使用此名稱建立相應的登錄檔項。dllname 應給出 .dll 或 .exe 的完整路徑名，其中包含要保留在日誌中的訊息定義（如果未指定，則使用 'win32service.pyd' - 它與 Win32 擴充套件一起安裝，幷包含一些基本的佔位符訊息定義。請注意，使用這些佔位符會使您的事件日誌很大，因為整個訊息源都儲存在日誌中。如果您想要更小的日誌，則必須傳入自己的 .dll 或 .exe 的名稱，其中包含要在事件日誌中使用的訊息定義）。logtype 是 'Application'、'System' 或 'Security' 之一，預設為 'Application'。

close()¶: 此時，您可以從登錄檔中刪除應用程式名稱作為事件日誌條目的來源。但是，如果執行此操作，您將無法在事件日誌檢視器中看到您想要的事件 - 它需要能夠訪問登錄檔以獲取 .dll 名稱。當前版本不執行此操作。

emit(record)¶: 確定訊息 ID、事件類別和事件型別，然後在 NT 事件日誌中記錄訊息。

getEventCategory(record)¶: 返回記錄的事件類別。如果您想指定自己的類別，請覆蓋此方法。此版本返回 0。

getEventType(record)¶: 返回記錄的事件型別。如果您想指定自己的型別，請覆蓋此方法。此版本使用處理程式的 typemap 屬性進行對映，該屬性在 __init__() 中設定為包含 DEBUG、 INFO、 WARNING、 ERROR 和 CRITICAL 對映的字典。如果您使用自己的級別，則需要覆蓋此方法或將合適的字典放置在處理程式的 typemap 屬性中。

getMessageID(record)¶: 返回記錄的訊息 ID。如果您使用自己的訊息，可以透過讓傳遞給記錄器的 msg 成為 ID 而不是格式字串來實現。然後，在這裡，您可以使用字典查詢來獲取訊息 ID。此版本返回 1，它是 win32service.pyd 中的基本訊息 ID。

SMTPHandler¶

位於 logging.handlers 模組中的 SMTPHandler 類，支援透過 SMTP 將日誌訊息傳送到電子郵件地址。

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

返回 SMTPHandler 類的新例項。該例項使用電子郵件的發件人和收件人地址以及主題行進行初始化。toaddrs 應該是字串列表。要指定非標準的 SMTP 埠，請為 mailhost 引數使用 (主機, 埠) 元組格式。如果您使用字串，則使用標準的 SMTP 埠。如果您的 SMTP 伺服器需要身份驗證，您可以為 credentials 引數指定 (使用者名稱, 密碼) 元組。

要指定使用安全協議 (TLS)，請將元組傳遞給 secure 引數。只有在提供身份驗證憑據時才會使用此引數。該元組應該是一個空元組，或一個帶有金鑰檔名值的單值元組，或一個帶有金鑰檔名和證書檔名的 2 值元組。（此元組傳遞給 smtplib.SMTP.starttls() 方法。）

可以使用 timeout 引數指定與 SMTP 伺服器通訊的超時時間。

在 3.3 版本中更改: 添加了 timeout 引數。

emit(record)¶: 格式化記錄並將其傳送給指定的收件人。

getSubject(record)¶: 如果要指定依賴於記錄的主題行，請覆蓋此方法。

MemoryHandler¶

位於 logging.handlers 模組中的 MemoryHandler 類，支援在記憶體中緩衝日誌記錄，定期將其重新整理到目標處理程式。當緩衝區已滿，或看到某個嚴重程度或更高的事件時，就會發生重新整理。

MemoryHandler 是更通用的 BufferingHandler 的子類，後者是一個抽象類。它在記憶體中緩衝日誌記錄。每當向緩衝區新增記錄時，都會透過呼叫 shouldFlush() 進行檢查，以確定是否應重新整理緩衝區。如果應該重新整理，則預期 flush() 執行重新整理。

class logging.handlers.BufferingHandler(capacity)¶

使用指定容量的緩衝區初始化處理程式。此處，capacity 表示緩衝的日誌記錄數。

emit(record)¶: 將記錄附加到緩衝區。如果 shouldFlush() 返回 true，則呼叫 flush() 來處理緩衝區。

flush()¶: 對於 BufferingHandler 例項，重新整理意味著將緩衝區設定為空列表。可以覆蓋此方法以實現更有用的重新整理行為。

shouldFlush(record)¶: 如果緩衝區已達到容量，則返回 True。可以覆蓋此方法以實現自定義重新整理策略。

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

返回 MemoryHandler 類的新例項。該例項使用 capacity 的緩衝區大小（緩衝的記錄數）初始化。如果未指定 flushLevel，則使用 ERROR。如果未指定 target，則需要在該處理程式執行任何有用的操作之前使用 setTarget() 設定目標。如果將 flushOnClose 指定為 False，則關閉處理程式時不會重新整理緩衝區。如果未指定或指定為 True，則關閉處理程式時將發生重新整理緩衝區的先前行為。

在 3.6 版本中更改: 添加了 flushOnClose 引數。

close()¶: 呼叫 flush()，將目標設定為 None 並清除緩衝區。

flush()¶: 對於 MemoryHandler 例項，重新整理意味著僅將緩衝的記錄傳送到目標（如果有目標）。當緩衝的記錄傳送到目標時，緩衝區也會被清除。如果您需要不同的行為，請覆蓋。

setTarget(target)¶: 為此處理程式設定目標處理程式。

shouldFlush(record)¶: 檢查緩衝區是否已滿，或者是否有日誌記錄的級別等於或高於 flushLevel。

HTTPHandler¶

位於 logging.handlers 模組中的 HTTPHandler 類支援使用 GET 或 POST 語義向 Web 伺服器傳送日誌訊息。

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

返回 HTTPHandler 類的新例項。host 可以是 host:port 的形式，如果你需要使用特定的埠號。如果沒有指定 method，則使用 GET。如果 secure 為 true，將使用 HTTPS 連線。可以將 context 引數設定為 ssl.SSLContext 例項，以配置 HTTPS 連線使用的 SSL 設定。如果指定了 credentials，它應該是一個包含 userid 和 password 的 2 元組，它將使用基本身份驗證放置在 HTTP ‘Authorization’ 標頭中。如果您指定了憑據，還應該指定 secure=True，以便您的使用者 ID 和密碼不會以明文形式在網路上傳輸。

在 3.5 版本中更改: 添加了 context 引數。

mapLogRecord(record)¶: 提供一個基於 record 的字典，該字典將被 URL 編碼併發送到 Web 伺服器。預設實現只返回 record.__dict__。如果例如只需要將 LogRecord 的子集傳送到 Web 伺服器，或者需要對傳送到伺服器的內容進行更具體的自定義，則可以覆蓋此方法。

emit(record)¶: 將記錄作為 URL 編碼的字典傳送到 Web 伺服器。使用 mapLogRecord() 方法將記錄轉換為要傳送的字典。

註解

由於準備要傳送到 Web 伺服器的記錄與通用格式化操作不同，因此使用 setFormatter() 為 HTTPHandler 指定 Formatter 無效。此處理器不是呼叫 format()，而是呼叫 mapLogRecord()，然後呼叫 urllib.parse.urlencode() 以適合傳送到 Web 伺服器的形式對字典進行編碼。

QueueHandler¶

3.2 版本加入。

位於 logging.handlers 模組中的 QueueHandler 類支援將日誌訊息傳送到佇列，例如在 queue 或 multiprocessing 模組中實現的佇列。

與 QueueListener 類一起，QueueHandler 可用於讓處理器在與執行日誌記錄的執行緒分離的執行緒上工作。這在 Web 應用程式和其他服務應用程式中非常重要，在這些應用程式中，為客戶端提供服務的執行緒需要儘可能快地響應，而任何可能較慢的操作（例如透過 SMTPHandler 傳送電子郵件）都在單獨的執行緒上完成。

class logging.handlers.QueueHandler(queue)¶

返回 QueueHandler 類的新例項。該例項使用要向其傳送訊息的佇列進行初始化。queue 可以是任何類似佇列的物件；enqueue() 方法按原樣使用它，該方法需要知道如何向其傳送訊息。queue 不需要具有任務跟蹤 API，這意味著您可以為 queue 使用 SimpleQueue 例項。

註解

如果您正在使用 multiprocessing，則應避免使用 SimpleQueue，而應使用 multiprocessing.Queue。

emit(record)¶: 將準備好的 LogRecord 的結果加入佇列。如果發生異常（例如，因為有界佇列已滿），則會呼叫 handleError() 方法來處理該錯誤。這可能會導致記錄被靜默丟棄（如果 logging.raiseExceptions 為 False）或者將訊息列印到 sys.stderr （如果 logging.raiseExceptions 為 True）。

prepare(record)¶

準備記錄以加入佇列。此方法返回的物件將加入佇列。

基本實現格式化記錄以合併訊息、引數、異常和堆疊資訊（如果存在）。它還會就地刪除記錄中不可醃製的項。具體來說，它使用合併的訊息覆蓋記錄的 msg 和 message 屬性（透過呼叫處理程式的 format() 方法獲得），並將 args、 exc_info 和 exc_text 屬性設定為 None。

如果您想將記錄轉換為字典或 JSON 字串，或者在保留原始記錄完整性的同時傳送記錄的修改副本，您可能需要覆蓋此方法。

註解

基本實現使用引數格式化訊息，將 message 和 msg 屬性設定為格式化後的訊息，並將 args 和 exc_text 屬性設定為 None，以允許醃製並防止進一步嘗試格式化。這意味著 QueueListener 端的處理程式將沒有資訊來執行自定義格式化，例如異常。您可能希望子類化 QueueHandler 並覆蓋此方法，例如避免將 exc_text 設定為 None。請注意，message / msg / args 的更改與確保記錄可醃製有關，並且您是否能夠避免這樣做可能取決於您的 args 是否可醃製。（請注意，您可能不僅需要考慮您自己的程式碼，還需要考慮您使用的任何庫中的程式碼。）

enqueue(record)¶: 使用 put_nowait() 將記錄放入佇列；如果你想使用阻塞行為、超時或自定義佇列實現，你可能需要重寫此方法。

listener¶: 當透過使用 dictConfig() 進行配置建立時，此屬性將包含一個 QueueListener 例項，用於此處理程式。否則，它將為 None。

在 3.12 版本中新增。

QueueListener¶

3.2 版本加入。

QueueListener 類位於 logging.handlers 模組中，支援從佇列接收日誌訊息，例如在 queue 或 multiprocessing 模組中實現的佇列。訊息在內部執行緒中從佇列接收，並在同一執行緒上，傳遞給一個或多個處理程式進行處理。雖然 QueueListener 本身不是處理程式，但在此處記錄是因為它與 QueueHandler 協同工作。

與 QueueHandler 類一起，QueueListener 可用於讓處理程式在與執行日誌記錄的執行緒分離的單獨執行緒上完成其工作。這在 Web 應用程式和其他服務應用程式中非常重要，在這些應用程式中，為客戶端提供服務的執行緒需要儘快響應，而任何可能緩慢的操作（例如透過 SMTPHandler 傳送電子郵件）則在單獨的執行緒上完成。

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

返回 QueueListener 類的新例項。該例項使用要向其傳送訊息的佇列和將處理放入佇列的條目的處理程式列表進行初始化。該佇列可以是任何類似佇列的物件；它按原樣傳遞給 dequeue() 方法，該方法需要知道如何從中獲取訊息。該佇列不是必須具有任務跟蹤 API（儘管如果可用則會使用），這意味著你可以使用 SimpleQueue 例項作為queue。

註解

如果您正在使用 multiprocessing，則應避免使用 SimpleQueue，而應使用 multiprocessing.Queue。

如果 respect_handler_level 為 True，則在決定是否將訊息傳遞給該處理程式時，會考慮處理程式的級別（與訊息的級別進行比較）；否則，行為與以前的 Python 版本相同 - 始終將每個訊息傳遞給每個處理程式。

在 3.5 版本中更改：添加了 respect_handler_level 引數。

dequeue(block)¶

將記錄出隊並返回，可以選擇阻塞。

基本實現使用 get()。如果你想使用超時或使用自定義佇列實現，你可能需要重寫此方法。

prepare(record)¶

準備記錄以進行處理。

此實現只是返回傳入的記錄。如果需要在將記錄傳遞給處理程式之前對記錄進行任何自定義編組或操作，你可能需要重寫此方法。

handle(record)¶

處理記錄。

這只是迴圈遍歷處理程式，向它們提供要處理的記錄。傳遞給處理程式的實際物件是從 prepare() 返回的物件。

start()¶

啟動監聽器。

這將啟動一個後臺執行緒來監視佇列以處理 LogRecords。

stop()¶

停止監聽器。

這將請求執行緒終止，然後等待它執行此操作。請注意，如果你在應用程式退出之前不呼叫此方法，則佇列中可能仍會留下一些記錄，這些記錄將不會被處理。

enqueue_sentinel()¶: 向佇列寫入一個標記，告訴監聽器退出。此實現使用 put_nowait()。如果你想使用超時或使用自定義佇列實現，你可能需要重寫此方法。

3.3 版本新增。

另請參閱

模組 logging: 日誌模組的 API 參考。
模組 logging.config: 日誌模組的配置 API。

`logging.handlers` — 日誌處理器¶

StreamHandler¶

FileHandler¶

NullHandler¶

WatchedFileHandler¶

BaseRotatingHandler¶

RotatingFileHandler¶

TimedRotatingFileHandler¶

SocketHandler¶

DatagramHandler¶

SysLogHandler¶

NTEventLogHandler¶

SMTPHandler¶

MemoryHandler¶

HTTPHandler¶

QueueHandler¶

QueueListener¶

目錄

上一主題

下一主題

本頁

logging.handlers — 日誌處理器¶

StreamHandler¶

FileHandler¶

NullHandler¶

WatchedFileHandler¶

BaseRotatingHandler¶

RotatingFileHandler¶

TimedRotatingFileHandler¶

SocketHandler¶

DatagramHandler¶

SysLogHandler¶

NTEventLogHandler¶

SMTPHandler¶

MemoryHandler¶

HTTPHandler¶

QueueHandler¶

QueueListener¶

`logging.handlers` — 日誌處理器¶