logging.handlers — 日志处理程序

源代码： :source:`Lib/logging/handlers.py`

重要的

此页面仅包含参考信息。有关教程，请参阅

包中提供了以下有用的处理程序。请注意，其中三个处理程序（StreamHandler、FileHandler 和 NullHandler）实际上是在 logging 模块本身中定义的，但已被记录在案这里与其他处理程序一起。

流处理器

StreamHandler 类位于核心 logging 包中，将日志输出发送到 sys.stdout、sys.stderr 或任何类似文件的对象（或更准确地说，支持 write() 和 flush() 方法的任何对象）。

class logging.StreamHandler(stream=None)

返回 StreamHandler 类的新实例。如果指定了 stream，则实例将使用它来记录输出；否则，将使用 sys.stderr。

emit(record): 如果指定了格式化程序，则它用于格式化记录。然后将记录写入流中，后跟终止符。如果存在异常信息，则使用 traceback.print_exception() 对其进行格式化并附加到流中。

flush(): 通过调用其 flush() 方法刷新流。请注意，close() 方法是从 Handler 继承的，因此没有输出，因此有时可能需要显式的 flush() 调用。

setStream(stream)

将实例的流设置为指定值（如果不同）。在设置新流之前刷新旧流。

参数: stream – 处理程序应使用的流。
退货: 旧流，如果流被改变，或者 None 如果不是。

3.7 版中的新功能。

terminator

将格式化记录写入流时用作终止符的字符串。默认值为 '\n'。

如果您不想换行终止，则可以将处理程序实例的 terminator 属性设置为空字符串。

在早期版本中，终结符被硬编码为 '\n'。

3.2 版中的新功能。

文件处理器

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 版更改：除了字符串值， 文件名 参数也接受 Path 对象。

3.9 版更改：添加了 errors 参数。

close(): 关闭文件。

emit(record): 将记录输出到文件。

空处理器

3.1 版中的新功能。

NullHandler 类位于核心 logging 包中，不进行任何格式化或输出。它本质上是一个供库开发人员使用的“无操作”处理程序。

class logging.NullHandler

返回 NullHandler 类的新实例。

emit(record): 这个方法什么都不做。

handle(record): 这个方法什么都不做。

createLock(): 此方法为锁返回 None，因为没有需要序列化访问的底层 I/O。

有关如何使用 NullHandler 的更多信息，请参阅为库配置日志记录。

监视文件处理程序

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 版更改：除了字符串值， 文件名 参数也接受 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() 的参数。

笔记

在翻转过程中，namer 函数会被多次调用，因此它应该尽可能简单和快速。对于给定的输入，它也应该每次都返回相同的输出，否则翻转行为可能无法按预期工作。

3.3 版中的新功能。

rotator: 如果此属性设置为可调用，则 rotate() 方法委托给此可调用。传递给可调用对象的参数是传递给 rotate() 的参数。

3.3 版中的新功能。

rotation_filename(default_name)

旋转时修改日志文件的文件名。

提供此信息是为了可以提供自定义文件名。

默认实现调用处理程序的“namer”属性，如果它是可调用的，则将默认名称传递给它。如果属性不可调用（默认值为 None），则返回名称不变。

参数: default_name – 日志文件的默认名称。

3.3 版中的新功能。

rotate(source, dest)

旋转时，旋转当前日志。

默认实现调用处理程序的 'rotator' 属性，如果它是可调用的，则将 source 和 dest 参数传递给它。如果该属性不可调用（默认值为 None），则只需将源重命名为目标。

参数

source – 源文件名。这通常是基本文件名，例如 '测试日志'。
dest – 目标文件名。这通常是源旋转到的，例如 'test.log.1'。

3.3 版中的新功能。

属性存在的原因是为了避免您必须子类化 - 您可以对 RotatingFileHandler 和 TimedRotatingFileHandler 的实例使用相同的可调用对象。如果 namer 或 rotator callable 引发异常，这将以与 emit() 调用期间的任何其他异常相同的方式处理，即通过处理程序的 handleError() 方法。

如果您需要对旋转处理进行更重要的更改，您可以覆盖这些方法。

示例参见使用旋转器和命名器自定义日志轮换处理。

旋转文件处理器

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 值来允许文件以预定大小 rollover。当即将超过大小时，将关闭文件并静默打开一个新文件进行输出。每当当前日志文件的长度接近 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 对象。

3.9 版更改：添加了 errors 参数。

doRollover(): 进行翻转，如上所述。

emit(record): 将记录输出到文件，满足前面所述的翻转。

定时旋转文件处理器

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和间隔的乘积。

您可以使用when来指定间隔的类型。可能的值列表如下。请注意，它们不区分大小写。

价值	间隔类型	如果/如何使用 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 版更改：除了字符串值， 文件名 参数也接受 Path 对象。

3.9 版更改：添加了 errors 参数。

doRollover(): 进行翻转，如上所述。

emit(record): 将记录输出到文件，满足上述翻转。

套接字处理程序

SocketHandler 类位于 logging.handlers 模块中，将日志输出发送到网络套接字。基类使用 TCP 套接字。

class logging.handlers.SocketHandler(host, port)

返回 SocketHandler 类的新实例，旨在与远程机器通信，其地址由 host 和 port 给出。

在 3.4 版更改：如果 port 指定为 None，则使用 host 中的值创建 Unix 域套接字 - 否则为 TCP 套接字被建造。

close(): 关闭套接字。

emit(): Pickles 记录的属性字典并以二进制格式将其写入套接字。如果套接字出现错误，则静默丢弃数据包。如果连接先前丢失，则重新建立连接。要将接收端的记录解压缩为 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

请注意，泡菜并不完全安全。如果您担心安全性，您可能希望覆盖此方法以实现更安全的机制。例如，您可以使用 HMAC 对泡菜进行签名，然后在接收端对其进行验证，或者您可以在接收端禁用全局对象的解压。

send(packet)

将腌制的字节串 数据包 发送到套接字。发送的字节串的格式如 makePickle() 的文档中所述。

此功能允许部分发送，这可能在网络繁忙时发生。

createSocket()

尝试创建套接字；在失败时，使用指数退避算法。在初始失败时，处理程序将丢弃它试图发送的消息。当后续消息由同一个实例处理时，它不会尝试连接，直到一段时间过去。默认参数是这样的，初始延迟是一秒，如果在延迟之后仍然无法建立连接，处理程序将每次延迟加倍，最多 30 秒。

此行为由以下处理程序属性控制：

retryStart（初始延时，默认1.0秒）。
retryFactor（乘数，默认为2.0）。
retryMax（最大延迟，默认30.0秒）。

这意味着如果远程侦听器在 处理程序被使用后启动 ，您可能会丢失消息（因为处理程序在延迟过去之前甚至不会尝试连接，而是在处理过程中默默地丢弃消息）延迟时间）。

数据报处理器

DatagramHandler 类位于 logging.handlers 模块中，继承自 SocketHandler 以支持通过 UDP 套接字发送日志消息。

class logging.handlers.DatagramHandler(host, port)

返回 DatagramHandler 类的新实例，用于与远程机器通信，其地址由 host 和 port 给出。

3.4 版更改：如果 port 指定为 None，则使用 host 中的值创建 Unix 域套接字 - 否则为 UDP 套接字被建造。

emit(): Pickles 记录的属性字典并以二进制格式将其写入套接字。如果套接字出现错误，则静默丢弃数据包。要将接收端的记录解压缩为 LogRecord，请使用 makeLogRecord() 函数。

makeSocket(): SocketHandler 的工厂方法在这里被覆盖以创建一个 UDP 套接字（socket.SOCK_DGRAM）。

send(s): 将腌制的字节字符串发送到套接字。发送的字节串的格式如 SocketHandler.makePickle() 的文档中所述。

系统日志处理程序

SysLogHandler 类位于 logging.handlers 模块中，支持将日志消息发送到远程或本地 Unix 系统日志。

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

返回 SysLogHandler 类的新实例，用于与远程 Unix 机器通信，该机器的地址由 address 以 (host, port) 元组的形式给出。如果未指定 address，则使用 ('localhost', 514)。该地址用于打开套接字。提供 (host, port) 元组的替代方法是将地址作为字符串提供，例如“/dev/log”。在这种情况下，使用 Unix 域套接字将消息发送到系统日志。如果未指定 facility，则使用 LOG_USER。打开的套接字类型取决于 socktype 参数，默认为 socket.SOCK_DGRAM 并因此打开一个 UDP 套接字。要打开 TCP 套接字（用于与 rsyslog 等较新的 syslog 守护程序一起使用），请指定值 socket.SOCK_STREAM。

请注意，如果您的服务器未侦听 UDP 端口 514，则 SysLogHandler 可能无法正常工作。在这种情况下，请检查您应该为域套接字使用什么地址 - 它取决于系统。例如，在 Linux 上它通常是“/dev/log”，但在 OS/X 上它是“/var/run/syslog”。您需要检查您的平台并使用适当的地址（如果您的应用程序需要在多个平台上运行，您可能需要在运行时进行此检查）。在 Windows 上，您几乎必须使用 UDP 选项。

3.2 版更改：添加了 socktype。

close(): 关闭到远程主机的套接字。

emit(record): 记录被格式化，然后发送到系统日志服务器。如果存在异常信息，则不发送到服务器。

在 3.2.1 版中更改：（参见：:issue:`12168`。）在早期版本中，发送到 syslog 守护进程的消息总是以 NUL 字节终止，因为这些守护进程的早期版本期望 NUL 终止消息 - 即使它不在相关规范中（RFC 5424）。这些守护程序的更新版本不期望 NUL 字节，但如果它在那里，则将其剥离，甚至更新的守护程序（更接近于 RFC 5424）将 NUL 字节作为消息的一部分传递。

为了在面对所有这些不同的守护进程行为时更容易处理 syslog 消息，通过使用类级别属性 append_nul，NUL 字节的附加是可配置的。这默认为 True（保留现有行为）但可以在 SysLogHandler 实例上设置为 False，以便该实例不附加NUL 终止符。

在 3.3 版中更改：（参见：:issue:`12419`。）在早期版本中，没有使用“ident”或“tag”前缀来标识源的工具的消息。这现在可以使用类级别属性指定，默认为 "" 以保留现有行为，但可以在 SysLogHandler 实例上覆盖，以便该实例将 ident 添加到每个消息处理。请注意，提供的标识必须是文本，而不是字节，并且完全按原样添加到消息中。

encodePriority(facility, priority)

将设施和优先级编码为整数。您可以传入字符串或整数 - 如果传递字符串，则使用内部映射字典将它们转换为整数。

符号 LOG_ 值在 SysLogHandler 中定义并镜像 sys/syslog.h 头文件中定义的值。

优先事项

名称（字符串）	象征价值
`alert`	LOG_ALERT
`crit` 或 `critical`	LOG_CRIT
`debug`	日志调试
`emerg` 或 `panic`	LOG_EMERG
`err` 或 `error`	日志错误
`info`	日志信息
`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`	登录用户
`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): 将日志级别名称映射到系统日志优先级名称。如果您使用自定义级别，或者默认算法不适合您的需要，您可能需要覆盖它。默认算法将 DEBUG、INFO、WARNING、ERROR 和 CRITICAL 映射到等效的系统日志名称，并将所有其他级别名称映射到'警告'。

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 的名称，其中包含要在事件日志中使用的消息定义）。 日志类型 是 '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。

SMTP处理程序

SMTPHandler 类位于 logging.handlers 模块中，支持通过 SMTP 向电子邮件地址发送日志消息。

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

返回 SMTPHandler 类的新实例。该实例使用电子邮件的发件人和收件人地址以及主题行进行初始化。 toaddrs 应该是一个字符串列表。要指定非标准 SMTP 端口，请对 mailhost 参数使用 (host, port) 元组格式。如果使用字符串，则使用标准 SMTP 端口。如果您的 SMTP 服务器需要身份验证，您可以为 credentials 参数指定一个（用户名、密码）元组。

要指定使用安全协议 (TLS)，请将元组传递给 secure 参数。这仅在提供身份验证凭据时使用。元组应该是一个空元组，或者一个带有密钥文件名称的单值元组，或者一个带有密钥文件和证书文件名称的 2 值元组。（这个元组被传递给 smtplib.SMTP.starttls() 方法。）

可以使用 timeout 参数为与 SMTP 服务器的通信指定超时。

3.3 版新功能：添加了 timeout 参数。

emit(record): 格式化记录并将其发送给指定的收件人。

getSubject(record): 如果要指定与记录相关的主题行，请覆盖此方法。

内存处理器

MemoryHandler 类位于 logging.handlers 模块中，支持在内存中缓冲日志记录，定期将它们刷新到 target 处理程序。每当缓冲区已满时，或者看到某个严重性或更高级别的事件时，就会发生刷新。

MemoryHandler是更通用的BufferingHandler的子类，是一个抽象类。这会缓冲内存中的日志记录。每当每个记录添加到缓冲区时，都会通过调用 shouldFlush() 来检查缓冲区是否应该被刷新。如果应该，那么 flush() 预计会进行冲洗。

class logging.handlers.BufferingHandler(capacity)

使用指定容量的缓冲区初始化处理程序。这里，capacity 表示缓冲的日志记录数。

emit(record): 将记录追加到缓冲区。如果 shouldFlush() 返回 true，则调用 flush() 来处理缓冲区。

flush(): 您可以覆盖它以实现自定义刷新行为。这个版本只是将缓冲区清空。

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 或更高的记录。

HTTP处理程序

HTTPHandler 类位于 logging.handlers 模块中，支持使用 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 版更改：添加了 上下文 参数。

mapLogRecord(record): 提供基于 record 的字典，该字典将被 URL 编码并发送到 Web 服务器。默认实现只返回 record.__dict__。如果例如，可以覆盖此方法只有 LogRecord 的一个子集将被发送到 Web 服务器，或者如果需要对发送到服务器的内容进行更具体的定制。

emit(record): 将记录作为 URL 编码的字典发送到 Web 服务器。 mapLogRecord() 方法用于将记录转换为要发送的字典。

笔记

由于准备记录以将其发送到 Web 服务器与通用格式化操作不同，因此使用 setFormatter() 为 HTTPHandler 指定 Formatter没有效果。该处理程序不是调用 format()，而是先调用 mapLogRecord()，然后调用 urllib.parse.urlencode() 以适合发送的形式对字典进行编码到 Web 服务器。

队列处理器

3.2 版中的新功能。

QueueHandler 类位于 logging.handlers 模块中，支持将日志消息发送到队列，例如在 queue 或 multiprocessing 中实现的那些模块。

与 QueueListener 类一起，QueueHandler 可用于让处理程序在与执行日志记录的线程不同的线程上执行其工作。这在 Web 应用程序和其他服务应用程序中很重要，在这些应用程序中，为客户端提供服务的线程需要尽快响应，而任何可能较慢的操作（例如通过 SMTPHandler 发送电子邮件）都在单独的线程上完成。

class logging.handlers.QueueHandler(queue)

返回 QueueHandler 类的新实例。该实例使用队列进行初始化，以向其发送消息。 queue 可以是任何类似队列的对象；它由 enqueue() 方法按原样使用，该方法需要知道如何向其发送消息。队列不需要 ' 来拥有任务跟踪 API，这意味着您可以将 SimpleQueue 实例用于 queue。

emit(record): 将准备 LogRecord 的结果排入队列。如果发生异常（例如因为有界队列已经填满），调用 handleError() 方法来处理错误。这可能导致记录被悄悄删除（如果 logging.raiseExceptions 是 False）或打印到 sys.stderr 的消息（如果 logging.raiseExceptions 是 True ]）。

prepare(record)

准备排队记录。此方法返回的对象已入队。

基本实现格式化记录以合并消息、参数和异常信息（如果存在）。它还从原地记录中删除不可选择的项目。

如果您想将记录转换为 dict 或 JSON 字符串，或者在保持原始记录不变的情况下发送记录的修改副本，您可能需要覆盖此方法。

enqueue(record): 使用 put_nowait() 将记录排入队列；如果您想使用阻塞行为、超时或自定义队列实现，您可能需要覆盖它。

队列监听器

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。

如果 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 版中的新功能。

也可以看看

模块记录: 日志记录模块的 API 参考。
模块 logging.config: 日志模块的配置 API。

logging.handlers — 日志处理程序 — Python 文档

目录

logging.handlers — 日志处理程序

流处理器

文件处理器

空处理器

监视文件处理程序

BaseRotatingHandler

旋转文件处理器

定时旋转文件处理器

套接字处理程序

数据报处理器

系统日志处理程序

NTEventLogHandler

SMTP处理程序

内存处理器

HTTP处理程序

队列处理器

队列监听器