logging.handlers — 日誌處理程式

原始碼: Lib/logging/handlers.py

重要

此頁面僅包含參考資訊。有關教程，請參閱

• 基礎教程

• 高階教程

• 日誌操作手冊

---

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

StreamHandler

StreamHandler 類位於核心 logging 包中，將日誌輸出傳送到諸如 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

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

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

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

版本 3.6 中的更改: 除了字串值之外，filename 引數也接受 Path 物件。

版本 3.9 中的更改: 添加了 errors 引數。

close()

關閉檔案。

emit(record)

將記錄輸出到檔案。

請注意，如果檔案因退出時的日誌關閉而關閉，並且檔案模式為 'w'，則不會發出記錄（參見 bpo-42378）。

NullHandler

在 3.1 版本加入。

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

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 為真，則檔案開啟會推遲到第一次呼叫 emit()。預設情況下，檔案無限增長。如果提供了 errors，它將確定如何處理編碼錯誤。

版本 3.6 中的更改: 除了字串值之外，filename 引數也接受 Path 物件。

版本 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 的例項。如果命名器或輪轉器可呼叫物件引發異常，則將以與 emit() 呼叫期間的任何其他異常相同的方式處理此異常，即透過處理程式的 handleError() 方法。

如果您需要對輪轉處理進行更顯著的更改，則可以覆蓋這些方法。

有關示例，請參閱 使用輪轉器和命名器自定義日誌輪轉處理。

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 為真，則檔案開啟會推遲到第一次呼叫 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 中的更改: 除了字串值之外，filename 引數也接受 Path 物件。

版本 3.9 中的更改: 添加了 errors 引數。

doRollover()

執行如上所述的輪轉。

emit(record)

將記錄輸出到檔案，並按前面所述處理輪轉。

shouldRollover(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 引數為真，則使用 UTC 時間；否則使用本地時間。

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

如果 delay 為真，則檔案開啟會推遲到第一次呼叫 emit()。

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

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

備註

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

版本 3.4 中的更改: 添加了 atTime 引數。

版本 3.6 中的更改: 除了字串值之外，filename 引數也接受 Path 物件。

版本 3.9 中的更改: 添加了 errors 引數。

doRollover()

執行如上所述的輪轉。

emit(record)

將記錄輸出到檔案，並按上述方式處理輪轉。

getFilesToDelete()

返回一個檔名列表，這些檔案應作為輪轉的一部分刪除。這些

shouldRollover(record)

檢視是否已過去足夠的時間進行輪轉，如果已過去，則計算下一個輪轉時間。

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()

嘗試建立套接字；失敗時，使用指數退避演算法。初始失敗時，處理程式將丟棄它嘗試傳送的訊息。當後續訊息由同一例項處理時，它不會嘗試連線，直到經過一段時間。預設引數是：初始延遲為一秒，如果延遲後仍無法建立連線，處理程式將每次將延遲加倍，最多 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 syslog。

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

返回 SysLogHandler 類的新例項，旨在與遠端 Unix 機器通訊，其地址以 (host, port) 元組的形式由 address 給出。如果未指定 address，則使用 ('localhost', 514)。地址用於開啟套接字。提供 (host, port) 元組的替代方法是提供一個字串作為地址，例如 '/dev/log'。在這種情況下，Unix 域套接字用於將訊息傳送到 syslog。如果未指定 facility，則使用 LOG_USER。開啟的套接字型別取決於 socktype 引數，該引數預設為 socket.SOCK_DGRAM，從而開啟一個 UDP 套接字。要開啟 TCP 套接字（用於較新的 syslog 守護程序，例如 rsyslog），請指定 socket.SOCK_STREAM 的值。如果指定了 timeout，它將為套接字操作設定超時（以秒為單位）。這有助於防止在 syslog 伺服器無法訪問時程式無限期掛起。預設情況下，timeout 為 None，表示不應用超時。

請注意，如果您的伺服器未偵聽 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。

版本 3.14 中的更改: 添加了 timeout。

close()

關閉與遠端主機的套接字。

createSocket()

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

在 3.11 版本中新增。

emit(record)

記錄被格式化，然後傳送到 syslog 伺服器。如果存在異常資訊，則 不 傳送到伺服器。

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

為了更容易地處理所有這些不同的守護程序行為，NUL 位元組的附加已透過使用類級屬性 append_nul 變為可配置。此屬性預設為 True（保留現有行為），但可以在 SysLogHandler 例項上設定為 False，以便該例項 不 附加 NUL 終止符。

版本 3.3 中的更改: （參見：bpo-12419。）在早期版本中，沒有“ident”或“tag”字首來標識訊息源的功能。現在可以使用類級屬性指定，該屬性預設為 "" 以保留現有行為，但可以在 SysLogHandler 例項上覆蓋，以便該例項將 ident 前置到處理的每條訊息。請注意，提供的 ident 必須是文字，而不是位元組，並且完全按原樣前置到訊息中。

encodePriority(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
使用者	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

NTEventLogHandler 類位於 logging.handlers 模組中，支援將日誌訊息傳送到本地 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

SMTPHandler 類位於 logging.handlers 模組中，支援透過 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，它應該是一個包含使用者 ID 和密碼的 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() 方法按原樣使用，該方法需要知道如何向其傳送訊息。佇列不需要具有任務跟蹤 API，這意味著您可以使用 SimpleQueue 例項作為 queue。

備註

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

警告

multiprocessing 模組使用透過 get_logger() 建立和訪問的內部記錄器。multiprocessing.Queue 將在專案入隊時記錄 DEBUG 級別訊息。如果這些日誌訊息由使用相同 multiprocessing.Queue 例項的 QueueHandler 處理，將導致死鎖或無限遞迴。

emit(record)

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

prepare(record)

準備記錄以進行排隊。此方法返回的物件將入隊。

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

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

備註

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

enqueue(record)

使用 put_nowait() 將記錄入隊；如果您想使用阻塞行為、超時或自定義佇列實現，則可能需要覆蓋此方法。

listener

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

3.12 新版功能.

QueueListener

在 3.2 版本加入。

位於 logging.handlers 模組中的 QueueListener 類支援從佇列接收日誌訊息，例如在 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 引數。

3.14 版本變更: QueueListener 現在可以透過 with 用作上下文管理器。進入上下文時，監聽器啟動。退出上下文時，監聽器停止。__enter__() 返回 QueueListener 物件。

dequeue(block)

出隊一條記錄並返回它，可選地阻塞。

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

prepare(record)

準備記錄以進行處理。

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

handle(record)

處理記錄。

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

start()

啟動監聽器。

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

3.14 版本變更: 如果呼叫時監聽器已在執行，則會引發 RuntimeError。

stop()

停止監聽器。

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

enqueue_sentinel()

向佇列寫入一個哨兵，以告知監聽器退出。此實現使用 put_nowait()。如果您想使用超時或使用自定義佇列實現，則可能需要覆蓋此方法。

在 3.3 版本加入。

參見

模組 logging

logging 模組的 API 參考。

模組 logging.config

日誌模組的配置 API。