16.8. logging.handlers — 日志处理

源代码: Lib/logging/handlers.py

Important

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

• 基础教程
• 进阶教程
• Logging Cookbook

---

这个包提供了以下有用的处理程序。 请注意有三个处理程序类 (StreamHandler, FileHandler 和 NullHandler) 实际上是在 logging 模块本身定义的，但其文档与其他处理程序一同记录在此。

16.8.1. StreamHandler

StreamHandler 类位于核心 logging 包，它可将日志记录输出发送到数据流例如 sys.stdout, sys.stderr 或任何文件类对象（或者更精确地说，任何支持 write() 和 flush() 方法的对象）。

class logging.StreamHandler(stream=None)

返回一个新的 StreamHandler 类。 如果指定了 stream，则实例将用它作为日志记录输出；在其他情况下将使用 sys.stderr。

emit(record)

If a formatter is specified, it is used to format the record. The record is then written to the stream with a terminator. If exception information is present, it is formatted using traceback.print_exception() and appended to the stream.

flush()

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

在 3.2 版更改: The StreamHandler class now has a terminator attribute, default value '\n', which is used as the terminator when writing a formatted record to a stream. If you don’t want this newline termination, you can set the handler instance’s terminator attribute to the empty string. In earlier versions, the terminator was hardcoded as '\n'.

16.8.2. FileHandler

FileHandler 类位于核心 logging 包，它可将日志记录输出到磁盘文件中。 它从 StreamHandler 继承了输出功能。

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

Returns a new instance of the FileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not None, it is used to open the file with that encoding. If delay is true, then file opening is deferred until the first call to emit(). By default, the file grows indefinitely.

close()

关闭文件。

emit(record)

将记录输出到文件。

16.8.3. NullHandler

3.1 新版功能.

NullHandler 类位于核心 logging 包，它不执行任何格式化或输出。 它实际上是一个供库开发者使用的‘无操作’处理程序。

class logging.NullHandler

返回一个 NullHandler 类的新实例。

emit(record)

此方法不执行任何操作。

handle(record)

此方法不执行任何操作。

createLock()

此方法会对锁返回 None，因为没有下层 I/O 的访问需要被序列化。

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

16.8.4. WatchedFileHandler

WatchedFileHandler 类位于 logging.handlers 模块，这个 FileHandler 用于监视它所写入日志记录的文件。 如果文件发生变化，它会被关闭并使用文件名重新打开。

发生文件更改可能是由于使用了执行文件轮换的程序例如 newsyslog 和 logrotate。 这个处理程序在 Unix/Linux 下使用，它会监视文件来查看自上次发出数据后是否有更改。 （如果文件的设备或 inode 发生变化就认为已被更改。） 如果文件被更改，则会关闭旧文件流，并再打开文件以获得新文件流。

这个处理程序不适合在 Windows 下使用，因为在 Windows 下打开的日志文件无法被移动或改名 —— 日志记录会使用排他的锁来打开文件 —— 因此这样的处理程序是没有必要的。 此外，ST_INO 在 Windows 下不受支持；stat() 将总是为该值返回零。

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

Returns a new instance of the WatchedFileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not None, it is used to open the file with that encoding. If delay is true, then file opening is deferred until the first call to emit(). By default, the file grows indefinitely.

emit(record)

Outputs the record to the file, but first checks to see if the file has changed. If it has, the existing stream is flushed and closed and the file opened again, before outputting the record to the file.

16.8.5. BaseRotatingHandler

BaseRotatingHandler 类位于 logging.handlers 模块中，它是轮换文件处理程序类 RotatingFileHandler 和 TimedRotatingFileHandler 的基类。 你不需要实例化此类，但它具有你可能需要重载的属性和方法。

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

类的形参与 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 – 源文件名。 这通常为基本文件名，例如 ‘test.log’。
• dest – 目标文件名。 这通常是源被轮换后的名称，例如 ‘test.log.1’。

3.3 新版功能.

该属性存在的理由是让你不必进行子类化 —— 你可以使用与 RotatingFileHandler 和 TimedRotatingFileHandler 的实例相同的可调用对象。 如果 namer 或 rotator 可调用对象引发了异常，将会按照与 emit() 调用期间的任何其他异常相同的方式来处理，例如通过处理程序的 handleError() 方法。

如果你需要对轮换进程执行更多的修改，你可以重载这些方法。

请参阅 Using a rotator and namer to customize log rotation processing 获取具体示例。

16.8.6. RotatingFileHandler

RotatingFileHandler 类位于 logging.handlers 模块，它支持磁盘日志文件的轮换。

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

Returns a new instance of the RotatingFileHandler class. The specified file is opened and used as the stream for logging. If mode is not specified, 'a' is used. If encoding is not None, it is used to open the file with that encoding. If delay is true, then file opening is deferred until the first call to emit(). By default, the file grows indefinitely.

You can use the maxBytes and backupCount values to allow the file to rollover at a predetermined size. When the size is about to be exceeded, the file is closed and a new file is silently opened for output. Rollover occurs whenever the current log file is nearly maxBytes in length; if either of maxBytes or backupCount is zero, rollover never occurs. If backupCount is non-zero, the system will save old log files by appending the extensions ‘.1’, ‘.2’ etc., to the filename. For example, with a backupCount of 5 and a base file name of app.log, you would get app.log, app.log.1, app.log.2, up to app.log.5. The file being written to is always app.log. When this file is filled, it is closed and renamed to app.log.1, and if files app.log.1, app.log.2, etc. exist, then they are renamed to app.log.2, app.log.3 etc. respectively.

doRollover()

执行上文所描述的轮换。

emit(record)

将记录输出到文件，以适应上文所描述的轮换。

16.8.7. TimedRotatingFileHandler

TimedRotatingFileHandler 类位于 logging.handlers 模块，它支持基于特定时间间隔的磁盘日志文件轮换。

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

返回一个新的 TimedRotatingFileHandler 类实例。 指定的文件会被打开并用作日志记录的流。 对于轮换操作它还会设置文件名前缀。 轮换的发生是基于 when 和 interval 的积。

你可以使用 when 来指定 interval 的类型。 可能的值列表如下。 请注意它们不是大小写敏感的。

值	间隔类型
'S'	秒
'M'	分钟
'H'	小时
'D'	天
'W0'-'W6'	工作日(0=星期一)
'midnight'	Roll over at midnight

当使用基于星期的轮换时，星期一为 ‘W0’，星期二为 ‘W1’，以此类推直至星期日为 ‘W6’。 在这种情况下，传入的 interval 值不会被使用。

系统将通过为文件名添加扩展名来保存旧日志文件。 扩展名是基于日期和时间的，根据轮换间隔的长短使用 strftime 格式 %Y-%m-%d_%H-%M-%S 或是其中有变动的部分。

当首次计算下次轮换的时间时（即当处理程序被创建时），现有日志文件的上次被修改时间或者当前时间会被用来计算下次轮换的发生时间。

如果 utc 参数为真值，将使用 UTC 时间；否则会使用本地时间。

如果 backupCount 不为零，则最多将保留 backupCount 个文件，而如果当轮换发生时创建了更多的文件，则最旧的文件会被删除。 删除逻辑使用间隔时间来确定要删除的文件，因此改变间隔时间可能导致旧文件被继续保留。

如果 delay 为真值，则会将文件打开延迟到首次调用 emit() 的时候。

If atTime is not None, it must be a datetime.time instance which specifies the time of day when rollover occurs, for the cases where rollover is set to happen “at midnight” or “on a particular weekday”.

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

doRollover()

执行上文所描述的轮换。

emit(record)

将记录输出到文件，以适应上文所描述的轮换。

16.8.8. 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)

Pickles the record’s attribute dictionary in binary format with a length prefix, and returns it ready for transmission across the socket.

请注意封存操作不是绝对安全的。 如果你关心安全问题，你可能会想要重载此方法以实现更安全的机制。 例如，你可以使用 HMAC 对封存对象进行签名然后在接收端验证它们，或者你也可以在接收端禁用全局对象的解封操作。

send(packet)

Send a pickled string packet to the socket. This function allows for partial sends which can happen when the network is busy.

createSocket()

尝试创建一个套接字；失败时将使用指数化回退算法处理。 在失败初次发生时，处理程序将丢弃它正尝试发送的消息。 当后续消息交由同一实例处理时，它将不会尝试连接直到经过一段时间以后。 默认形参设置为初始延迟一秒，如果在延迟之后连接仍然无法建立，处理程序将每次把延迟翻倍直至达到 30 秒的最大值。

此行为由下列处理程序属性控制:

• retryStart (初始延迟，默认为 1.0 秒)。
• retryFactor (倍数，默认为 2.0)。
• retryMax (最大延迟，默认为 30.0 秒)。

这意味着如果远程监听器在处理程序被使用 之后 启动，你可能会丢失消息（因为处理程序在延迟结束之前甚至不会尝试连接，而在延迟期间静默地丢弃消息）。

16.8.9. DatagramHandler

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

class logging.handlers.DatagramHandler(host, port)

返回一个 DatagramHandler 类的新实例，该实例旨在与使用 host 与 port 给定地址的远程主机进行通信。

在 3.4 版更改: 如果 port 指定为 None，会使用 host 中的值来创建一个 Unix 域套接字 —— 在其他情况下，则会创建一个 TCP 套接字。

emit()

对记录的属性字典执行封存并以二进制格式将其写入套接字。 如果套接字存在错误，则静默地丢弃数据包。 要在接收端将记录解封并输出到 LogRecord，请使用 makeLogRecord() 函数。

makeSocket()

SocketHandler 的工厂方法会在此被重载以创建一个 UDP 套接字 (socket.SOCK_DGRAM)。

send(s)

Send a pickled string to a socket.

16.8.10. SysLogHandler

SysLogHandler 类位于 logging.handlers 模块，它支持将日志记录消息发送到远程或本地 Unix syslog。

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

返回一个 SysLogHandler 类的新实例用来与通过 address 以 (host, port) 元组形式给出地址的远程 Unix 机器进行通讯。 如果未指定 address，则使用 ('localhost', 514)。 该地址会被用于打开套接字。 提供 (host, port) 元组的一种替代方式是提供字符串形式的地址，例如 ‘/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 选项。

在 3.2 版更改: 添加了 socktype。

close()

关闭连接远程主机的套接字。

emit(record)

记录会被格式化，然后发送到 syslog 服务器。 如果存在异常信息，则它 不会 被发送到服务器。

在 3.2.1 版更改: (See: bpo-12168.) In earlier versions, the message sent to the syslog daemons was always terminated with a NUL byte, because early versions of these daemons expected a NUL terminated message - even though it’s not in the relevant specification (RFC 5424). More recent versions of these daemons don’t expect the NUL byte but strip it off if it’s there, and even more recent daemons (which adhere more closely to RFC 5424) pass the NUL byte on as part of the message.

为了在面对所有这些不同守护程序行为时能够更方便地处理 syslog 消息，通过使用类层级属性 append_nul，添加 NUL 字节的操作已被作为可配置项。 该属性默认为 True (保留现有行为) 但可在 SysLogHandler 实例上设为 False 以便让实例 不会 添加 NUL 结束符。

在 3.3 版更改: (参见: bpo-12419。) 在较早的版本中，没有 “ident” 或 “tag” 前缀工具可以用来标识消息的来源。 现在则可以使用一个类层级属性来设置它，该属性默认为 "" 表示保留现有行为，但可在 SysLogHandler 实例上重载以便让实例不会为所处理的每条消息添加标识。 请注意所提供的标识必须为文本而非字节串，并且它会被原封不动地添加到消息中。

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
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’。

16.8.11. 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.

16.8.12. SMTPHandler

SMTPHandler 类位于 logging.handlers 模块，它支持将日志记录消息通过 SMTP 发送到一个电子邮件地址。

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

返回一个 SMTPHandler 类的新实例。 该实例使用电子邮件的发件人、收件人地址和主题行进行初始化。 toaddrs 应当为字符串列表。 要指定一个非标准 SMTP 端口，请使用 (host, port) 元组格式作为 mailhost 参数。 如果你使用一个字符串，则会使用标准 SMTP 端口。 如果你的 SMTP 服务器要求验证，你可以指定一个 (username, password) 元组作为 credentials 参数。

要指定使用安全协议 (TLS)，请传入一个元组作为 secure 参数。 这将仅在提供了验证凭据时才能被使用。 元组应当或是一个空元组，或是一个包含密钥文件名的单值元组，或是一个包含密钥文件和证书文件的 2 值元组。 （此元组会被传给 smtplib.SMTP.starttls() 方法。）

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

3.3 新版功能: 增加了 timeout 参数。

emit(record)

对记录执行格式化并将其发送到指定的地址。

getSubject(record)

如果你想要指定一个基于记录的主题行，请重载此方法。

16.8.13. MemoryHandler

MemoryHandler 类位于 logging.handlers 模块，它支持在内存中缓冲日志记录，并定期将其刷新到 target 处理程序中。 刷新会在缓冲区满的时候，或是在遇到特定或更高严重程度事件的时候发生。

MemoryHandler 是更通用的 BufferingHandler 的子类，后者属于抽象类。 它会在内存中缓冲日志记录。 当每条记录被添加到缓冲区时，会通过调用 shouldFlush() 来检查缓冲区是否应当刷新。 如果应当刷新，则要使用 flush() 来执行刷新。

class logging.handlers.BufferingHandler(capacity)

Initializes the handler with a buffer of the specified capacity.

emit(record)

Appends the record to the buffer. If shouldFlush() returns true, calls flush() to process the buffer.

flush()

你可以重载此方法来实现自定义的刷新行为。 此版本只是将缓冲区清空。

shouldFlush(record)

Returns true if the buffer is up to capacity. This method can be overridden to implement custom flushing strategies.

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

Returns a new instance of the MemoryHandler class. The instance is initialized with a buffer size of capacity. If flushLevel is not specified, ERROR is used. If no target is specified, the target will need to be set using setTarget() before this handler does anything useful.

close()

调用 flush()，设置目标为 None 并清空缓冲区。

flush()

对于 MemoryHandler，刷新是指将缓冲的记录发送到目标，如果存在目标的话。 当此行为发生时缓冲区也将被清空。 如果你想要不同的行为请重载此方法。

setTarget(target)

设置此处理程序的目标处理程序。

shouldFlush(record)

检测缓冲区是否已满或是有记录为 flushLevel 或更高级别。

16.8.14. HTTPHandler

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 为真值，则将使用 HTTPS 连接。 context 形参可以设为一个 ssl.SSLContext 实例以配置用于 HTTPS 连接的 SSL 设置。 如果指定了 credentials，它应当为包含 userid 和 password 的二元组，该元组将被放入使用 Basic 验证的 HTTP ‘Authorization’ 标头中。 如果你指定了 credentials，你还应当指定 secure=True 这样你的 userid 和 password 就不会以纯文本形式在线路上传输。

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

mapLogRecord(record)

基于 record 提供一个字典，它将被执行 URL 编码并发送至 Web 服务器。 默认实现仅返回 record.__dict__。 在只需将 LogRecord 的某个子集发送至 Web 服务器，或者需要对发送至服务器的内容进行更多定制时可以重载此方法。

emit(record)

将记录以经 URL 编码的形式发送至 Web 服务器。 会使用 mapLogRecord() 方法来将要发送的记录转换为字典。

注解

由于记录发送至 Web 服务器所需的预处理与通用的格式化操作不同，使用 setFormatter() 来指定一个 Formatter 用于 HTTPHandler 是没有效果的。 此处理程序不会调用 format()，而是调用 mapLogRecord() 然后再调用 urllib.parse.urlencode() 来以适合发送至 Web 服务器的形式对字典进行编码。

16.8.15. QueueHandler

3.2 新版功能.

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

配合 QueueListener 类使用，QueueHandler 可用来使处理程序在与执行日志记录的线程不同的线程上完成工作。 这对 Web 应用程序以及其他服务于客户端的线程需要尽可能快地响应的服务应用程序来说很重要，任何潜在的慢速操作（例如通过 SMTPHandler 发送邮件）都要在单独的线程上完成。

class logging.handlers.QueueHandler(queue)

Returns a new instance of the QueueHandler class. The instance is initialized with the queue to send messages to. The queue can be any queue-like object; it’s used as-is by the enqueue() method, which needs to know how to send messages to it.

emit(record)

Enqueues the result of preparing the LogRecord.

prepare(record)

准备用于队列的记录。 此方法返回的对象会被排入队列。

The base implementation formats the record to merge the message and arguments, and removes unpickleable items from the record in-place.

如果你想要将记录转换为 dict 或 JSON 字符串，或者发送记录被修改后的副本而让初始记录保持原样，则你可能会想要重载此方法。

enqueue(record)

使用 put_nowait() 将记录排入队列；如果你想要使用阻塞行为，或超时设置，或自定义的队列实现，则你可能会想要重载此方法。

16.8.16. QueueListener

3.2 新版功能.

QueueListener 类位于 logging.handlers 模块，它支持从一个队列接收日志记录消息，例如在 queue 或 multiprocessing 模块中实现的队列。 消息是在内部线程中从队列接收并在同一线程上传递到一个或多个处理程序进行处理的。 尽管 QueueListener 本身并不是一个处理程序，但由于它要与 QueueHandler 配合工作，因此也在此处介绍。

配合 QueueHandler 类使用，QueueListener 可用来使处理程序在与执行日志记录的线程不同的线程上完成工作。 这对 Web 应用程序以及其他服务与客户端的线程需要尽可能快地响应的服务应用程序来说很重要，任何潜在的慢速动作（例如通过 SMTPHandler 发送邮件）都要在单独的线程上完成。

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

Returns a new instance of the QueueListener class. The instance is initialized with the queue to send messages to and a list of handlers which will handle entries placed on the queue. The queue can be any queue-like object; it’s passed as-is to the dequeue() method, which needs to know how to get messages from it. If respect_handler_level is True, a handler’s level is respected (compared with the level for the message) when deciding whether to pass messages to that handler; otherwise, the behaviour is as in previous Python versions - to always pass each message to each handler.

在 3.5 版更改: The respect_handler_levels argument was added.

dequeue(block)

从队列移出一条记录并将其返回，可以选择阻塞。

基本实现使用 get()。 如果你想要使用超时设置或自定义的队列实现，则你可能会想要重载此方法。

prepare(record)

准备一条要处理的记录。

该实现只是返回传入的记录。 如果你想要对记录执行任何自定义的 marshal 操作或在将其传给处理程序之前进行调整，则你可能会想要重载此方法。

handle(record)

处理一条记录。

此方法简单地循环遍历处理程序，向它们提供要处理的记录。 实际传给处理程序的对象就是从 prepare() 返回的对象。

start()

启动监听器。

此方法启动一个后台线程来监视 LogRecords 队列以进行处理。

stop()

停止监听器。

此方法要求线程终止，然后等待它完成终止操作。 请注意在你的应用程序退出之前如果你没有调用此方法，则可能会有一些记录在留在队列中，它们将不会被处理。

enqueue_sentinel()

将一个标记写入队列以通知监听器退出。 此实现会使用 put_nowait()。 如果你想要使得超时设置或自定义的队列实现，则你可能会想要重载此方法。

3.3 新版功能.

参见

模块 logging

日志记录模块的 API 参考。

模块 logging.config

日志记录模块的配置 API 。