Skip to main content

16.8. logging.handlers —记录处理程序

源代码: Lib/logging/handlers.py


在包装中提供以下有用的处理器。注意,三个处理程序(StreamHandlerFileHandlerNullHandler)实际上是在 logging 模块本身中定义的,但是在这里与其他处理程序一起记录。

16.8.1. StreamHandler

位于核心 logging 包中的 StreamHandler 类将记录输出发送到诸如 sys.stdoutsys.stderr 或任何类似文件的对象(或者更准确地说,支持 write()flush() 方法的任何对象)的流。

class logging.StreamHandler(stream=None)

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

emit(record)

如果指定了格式化程序,它将用于格式化记录。然后使用终止符将记录写入流。如果存在异常信息,它将使用 traceback.print_exception() 格式化并附加到流。

flush()

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

在 3.2 版更改: StreamHandler 类现在具有 terminator 属性,默认值 '\n',当将格式化的记录写入流时,它用作终止符。如果您不想要此换行符终止,您可以将处理程序实例的 terminator 属性设置为空字符串。在早期版本中,终止符被硬编码为 '\n'

16.8.2. FileHandler

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

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

返回 FileHandler 类的新实例。将打开指定的文件并将其用作日志记录的流。如果未指定 mode,则使用 'a'。如果 encoding 不是 None,它用于打开具有该编码的文件。如果 delay 为true,那么文件打开被延迟,直到第一次调用 emit()。默认情况下,文件无限增长。

在 3.6 版更改: 除了字符串值,filename 参数也接受 Path 对象。

close()

关闭文件。

emit(record)

将记录输出到文件。

16.8.3. NullHandler

3.1 新版功能.

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

class logging.NullHandler

返回 NullHandler 类的新实例。

emit(record)

此方法不执行任何操作。

handle(record)

此方法不执行任何操作。

createLock()

此方法为锁返回 None,因为没有需要将访问序列化的基础I/O。

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

16.8.4. WatchedFileHandler

WatchedFileHandler 类位于 logging.handlers 模块中,它是一个 FileHandler,它监视它正在记录的文件。如果文件更改,它将关闭并使用文件名重新打开。

由于使用执行日志文件轮换的程序(如 newsysloglogrotate),可能会发生文件更改。这个处理程序打算在Unix/Linux下使用,监视文件以查看自上次发射后是否已更改。 (如果文件已更改,则认为文件已更改)。如果文件已更改,则关闭旧文件流,并打开该文件以获取新的流。

此处理程序不适合在Windows下使用,因为在Windows打开日志文件不能移动或重命名 - 日志记录使用排它锁打开文件,因此不需要这样的处理程序。此外,Windows下不支持 ST_INOstat() 总是为此值返回零。

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

返回 WatchedFileHandler 类的新实例。将打开指定的文件并将其用作日志记录的流。如果未指定 mode,则使用 'a'。如果 encoding 不是 None,它用于打开具有该编码的文件。如果 delay 为true,那么文件打开被延迟,直到第一次调用 emit()。默认情况下,文件无限增长。

在 3.6 版更改: 除了字符串值,filename 参数也接受 Path 对象。

reopenIfNeeded()

检查文件是否已更改。如果有,则刷新并关闭现有流,并且再次打开文件,通常作为将记录输出到文件的前体。

3.6 新版功能.

emit(record)

将记录输出到文件,但首先调用 reopenIfNeeded() 以重新打开文件(如果文件已更改)。

16.8.5. BaseRotatingHandler

位于 logging.handlers 模块中的 BaseRotatingHandler 类是旋转文件处理程序 RotatingFileHandlerTimedRotatingFileHandler 的基类。你不需要实例化这个类,但它有你可能需要重写的属性和方法。

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

参数为 FileHandler。属性是:

namer

如果此属性设置为可调用项,则 rotation_filename() 方法将委托给此可调项。传递给可调用的参数是传递给 rotation_filename() 的参数。

注解

在翻转期间,命名函数被称为相当多次,因此它应该尽可能简单和快速。对于给定的输入,它也应该每次返回相同的输出,否则翻转行为可能无法正常工作。

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 新版功能.

属性存在的原因是保存您不必子类化 - 您可以为 RotatingFileHandlerTimedRotatingFileHandler 的实例使用相同的可调用项。如果命名或旋转器可调用引发异常,则在 emit() 调用期间,将以与任何其它异常相同的方式处理,即通过处理程序的 handleError() 方法。

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

有关示例,请参阅 使用旋转器和命名器来自定义日志旋转处理

16.8.6. RotatingFileHandler

RotatingFileHandler 类位于 logging.handlers 模块中,支持磁盘日志文件的旋转。

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

返回 RotatingFileHandler 类的新实例。将打开指定的文件并将其用作日志记录的流。如果未指定 mode,则使用 'a'。如果 encoding 不是 None,它用于打开具有该编码的文件。如果 delay 为true,那么文件打开被延迟,直到第一次调用 emit()。默认情况下,文件无限增长。

您可以使用 maxBytesbackupCount 值以允许文件以预定大小到 rollover。当将要超过大小时,将关闭文件,并静默打开一个新文件以输出。当当前日志文件的长度接近 maxBytes 时,发生翻转;如果 maxBytesbackupCount 中的任一个为零,则不会发生翻转。如果 backupCount 不为零,系统将通过将扩展名’.1’,’.2’等附加到文件名来保存旧的日志文件。例如,如果 backupCount 为5,基本文件名为 app.log,您将获得 app.logapp.log.1app.log.2,最多为 app.log.5。正在写入的文件始终是 app.log。当该文件被填充时,它被关闭并重命名为 app.log.1,并且如果存在文件 app.log.1app.log.2 等,则它们分别被重命名为 app.log.2app.log.3 等。

在 3.6 版更改: 除了字符串值,filename 参数也接受 Path 对象。

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 类的新实例。将打开指定的文件并将其用作日志记录的流。在旋转它也设置文件名后缀。基于 wheninterval 的乘积进行旋转。

您可以使用 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 值被有效地用于计算 initial 滚动,并且随后的滚动将通过正常间隔计算来计算。

注解

初始翻转时间的计算是在处理程序初始化时完成的。仅当发生翻转时才进行后续翻转时间的计算,并且仅在发出输出时发生翻转。如果不记住这一点,它可能会导致一些混乱。例如,如果设置了“每分钟”的间隔,这并不意味着您将始终看到日志文件的时间(文件名中)以分钟为单位;如果在应用程序执行期间,记录输出比每分钟一次更频繁地生成,则 then 可以看到日志文件的时间以分钟为单位。另一方面,如果日志消息仅仅每五分钟(例如)输出一次,则在与没有输出(因此没有翻转)发生的分钟相对应的文件时间中将存在间隙。

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

在 3.6 版更改: 除了字符串值,filename 参数也接受 Path 对象。

doRollover()

执行滚动,如上所述。

emit(record)

将记录输出到文件,满足上述的翻转。

16.8.8. SocketHandler

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

class logging.handlers.SocketHandler(host, port)

返回 SocketHandler 类的一个新实例,该实例旨在与其地址由 hostport 给定的远程机器进行通信。

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

close()

关闭套接字。

emit()

选择记录的属性字典并将其以二进制格式写入套接字。如果套接字有错误,则静默丢弃数据包。如果连接以前丢失,请重新建立连接。要将接收端的记录解冻成 LogRecord,请使用 makeLogRecord() 功能。

handleError()

处理在 emit() 期间发生的错误。最可能的原因是连接断开。关闭套接字,以便我们可以在下一个事件上重试。

makeSocket()

这是一个工厂方法,允许子类定义他们想要的套接字的精确类型。默认实现创建一个TCP套接字(socket.SOCK_STREAM)。

makePickle(record)

选择具有长度前缀的二进制格式的记录的属性字典,并返回它准备通过套接字传输。

注意,腌菜不是完全安全的。如果您担心安全性,您可能想要覆盖此方法以实现更安全的机制。例如,您可以使用HMAC签署腌菜,然后在接收端验证它们,或者您也可以禁用接收端的全局对象取消剔除。

send(packet)

将腌制的字符串 packet 发送到套接字。此功能允许在网络忙时可能发生的部分发送。

createSocket()

尝试创建套接字; on失败时,使用指数退避算法。在初始失败时,处理程序将删除它试图发送的消息。当后续消息由同一个实例处理时,它将不会尝试连接,直到一段时间过去。默认参数使得初始延迟为1秒,如果在该延迟之后仍然不能进行连接,则处理器将每次延迟加倍,直到最大30秒。

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

  • retryStart (初始延迟,默认为1.0秒)。

  • retryFactor (乘数,默认为2.0)。

  • retryMax (最大延迟,默认为30.0秒)。

这意味着如果远程侦听器启动 after,处理程序已被使用,您可能会丢失消息(因为处理程序甚至不会尝试连接,直到延迟已过,但只是在延迟期间静默丢弃消息)。

16.8.9. DatagramHandler

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

class logging.handlers.DatagramHandler(host, port)

返回 DatagramHandler 类的一个新实例,该实例旨在与其地址由 hostport 给定的远程机器进行通信。

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

emit()

选择记录的属性字典并将其以二进制格式写入套接字。如果套接字有错误,则静默丢弃数据包。要将接收端的记录解冻成 LogRecord,请使用 makeLogRecord() 功能。

makeSocket()

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

send(s)

将腌制的字符串发送到套接字。

16.8.10. SysLogHandler

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域套接字将消息发送到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服务器。如果存在异常信息,则将 not 发送到服务器。

在 3.2.1 版更改: (见:issue 12168。)在早期版本中,发送到syslog守护进程的消息总是以NUL字节终止,因为这些守护进程的早期版本期望NUL终止的消息 - 即使它不在相关规范(RFC 5424)中。这些守护进程的更新版本不期望NUL字节,但如果它在那里,它会剥离它,甚至更多的最近的守护进程(更紧密地遵守RFC 5424)通过NUL字节作为消息的一部分。

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

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

encodePriority(facility, priority)

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

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

优先级

名称(字符串)

符号值

alert

LOG_ALERT

critcritical

LOG_CRIT

debug

LOG_DEBUG

emergpanic

LOG_EMERG

errerror

LOG_ERR

info

LOG_INFO

notice

LOG_NOTICE

warnwarning

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)

将日志记录级别名称映射到系统日志优先级名称。如果您使用自定义级别,或者如果默认算法不适合您的需要,则可能需要覆盖此选项。默认算法将 DEBUGINFOWARNINGERRORCRITICAL 映射到等效的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__() 中设置为包含 DEBUGINFOWARNINGERRORCRITICAL 的映射的字典。如果您使用自己的级别,您将需要重写此方法或在处理程序的 typemap 属性中放置一个合适的字典。

getMessageID(record)

返回记录的消息ID。如果您使用自己的消息,您可以通过将 msg 传递给记录器,而不是格式字符串来实现。然后,在这里,您可以使用字典查找获取消息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 类的新实例。实例使用电子邮件的from和to地址和主题行初始化。 toaddrs 应该是字符串列表。要指定非标准SMTP端口,请对 mailhost 参数使用(host,port)元组格式。如果使用字符串,则使用标准SMTP端口。如果您的SMTP服务器需要身份验证,您可以为 credentials 参数指定(用户名,密码)元组。

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

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

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

emit(record)

格式化记录并将其发送到指定的收件人。

getSubject(record)

如果要指定与记录相关的主题行,请覆盖此方法。

16.8.13. MemoryHandler

位于 logging.handlers 模块中的 MemoryHandler 类支持在存储器中缓冲日志记录,周期性地将它们刷新到 target 处理程序。每当缓冲器充满时,或当看到某种严重性或更大的事件时,发生冲洗。

MemoryHandler 是更通用的 BufferingHandler 的子类,BufferingHandler 是一个抽象类。这会将记录记录缓冲在内存中。每当每个记录被添加到缓冲区时,通过调用 shouldFlush() 来检查缓冲区是否应该被刷新。如果它应该,然后 flush() 预计做冲洗。

class logging.handlers.BufferingHandler(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,则当处理程序关闭时缓冲区被 not 刷新。如果未指定或指定为 True,则在处理程序关闭时将发生刷新缓冲区的先前行为。

在 3.6 版更改: 添加了 flushOnClose 参数。

close()

调用 flush(),将目标设置为 None 并清除缓冲区。

flush()

对于 MemoryHandler,刷新意味着只将缓冲的记录发送到目标(如果有的话)。发生这种情况时,缓冲区也会被清除。如果你想要不同的行为,覆盖。

setTarget(target)

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

shouldFlush(record)

检查缓冲区已满或 flushLevel 或更高级别的记录。

16.8.14. httpHandler

HTTPHandler 类位于 logging.handlers 模块中,支持使用 GETPOST 语义将日志消息发送到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,它应该是由用户标识和密码组成的2元组,它将使用基本认证放置在HTTP“授权”头中。如果指定凭据,则还应指定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服务器的形式对字典进行编码。

16.8.15. QueueHandler

3.2 新版功能.

QueueHandler 类位于 logging.handlers 模块中,支持将日志消息发送到队列,例如在 queuemultiprocessing 模块中实现的队列。

QueueListener 类一起,QueueHandler 可以用于让处理程序在与执行日志记录的线程不同的线程上执行它们的工作。这在Web应用程序以及其他服务应用程序中很重要,其中服务客户端的线程需要尽可能快地响应,而任何潜在的缓慢操作(例如通过 SMTPHandler 发送电子邮件)都是在单独的线程上完成的。

class logging.handlers.QueueHandler(queue)

返回 QueueHandler 类的新实例。实例使用发送消息的队列初始化。队列可以是任何类似队列的对象;它按照原样使用 enqueue() 方法,它需要知道如何向它发送消息。

emit(record)

将准备LogRecord的结果加入队列。

prepare(record)

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

基本实现格式化记录以合并消息和参数,并且从记录中原地移除不可消除的项目。

如果要将记录转换为dict或JSON字符串,或发送修改后的记录副本,同时保留原始文件,则可能想要覆盖此方法。

enqueue(record)

使用 put_nowait() 将队列中的记录排队;如果要使用阻塞行为,超时或自定义队列实现,您可能想要覆盖此选项。

16.8.16. QueueListener

3.2 新版功能.

位于 logging.handlers 模块中的 QueueListener 类支持从队列(例如在 queuemultiprocessing 模块中实现的队列)接收日志消息。消息从内部线程中的队列接收并在同一线程上传递到一个或多个处理程序以进行处理。虽然 QueueListener 本身不是一个处理程序,它在这里记录,因为它与 QueueHandler 携手工作。

QueueHandler 类一起,QueueListener 可以用于让处理程序在与执行日志记录的线程不同的线程上执行它们的工作。这在Web应用程序以及其他服务应用程序中很重要,其中服务客户端的线程需要尽可能快地响应,而任何潜在的缓慢操作(例如通过 SMTPHandler 发送电子邮件)都是在单独的线程上完成的。

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

返回 QueueListener 类的新实例。实例使用发送消息的队列和处理程序列表初始化,处理程序将处理放置在队列上的条目。队列可以是任何类似队列的对象;它按原样传递到 dequeue() 方法,它需要知道如何从中获取消息。如果 respect_handler_levelTrue,当决定是否向该处理程序传递消息时,处理程序的级别被遵守(与消息的级别相比);否则,该行为与以前的Python版本一样 - 总是将每个消息传递给每个处理程序。

在 3.5 版更改: 添加了 respect_handler_levels 参数。

dequeue(block)

出队记录并返回它,可选择阻塞。

基本实现使用 get()。如果要使用超时或使用自定义队列实现,您可能想要覆盖此方法。

prepare(record)

准备处理记录。

这个实现只返回传入的记录。如果您需要在将记录传递给处理程序之前对记录进行任何自定义编组或操作,那么您可能想要覆盖此方法。

handle(record)

处理记录。

这只是循环通过处理程序为他们提供处理的记录。传递给处理程序的实际对象是从 prepare() 返回的对象。

start()

启动侦听器。

这将启动一个后台线程来监视队列以使LogRecords处理。

stop()

停止侦听器。

这要求线程终止,然后等待它这样做。请注意,如果您在应用程序退出之前未调用此方法,则队列中可能仍有一些记录,这些记录不会被处理。

enqueue_sentinel()

将哨兵写入队列以告诉侦听器退出。此实现使用 put_nowait()。如果要使用超时或使用自定义队列实现,您可能想要覆盖此方法。

3.3 新版功能.

参见

模块 logging

日志模块的API参考。

模块 logging.config

日志模块的配置API。