16.8. logging.handlers
—记录处理程序¶
在包装中提供以下有用的处理器。注意,三个处理程序(StreamHandler
,FileHandler
和 NullHandler
)实际上是在 logging
模块本身中定义的,但是在这里与其他处理程序一起记录。
16.8.1. StreamHandler¶
位于核心 logging
包中的 StreamHandler
类将记录输出发送到诸如 sys.stdout,sys.stderr 或任何类似文件的对象(或者更准确地说,支持 write()
和 flush()
方法的任何对象)的流。
-
class
logging.
StreamHandler
(stream=None)¶ 返回
StreamHandler
类的新实例。如果指定 stream,实例将使用它来记录输出;否则,将使用 sys.stderr。-
emit
(record)¶ 如果指定了格式化程序,它将用于格式化记录。然后使用终止符将记录写入流。如果存在异常信息,它将使用
traceback.print_exception()
格式化并附加到流。
-
在 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
,它监视它正在记录的文件。如果文件更改,它将关闭并使用文件名重新打开。
由于使用执行日志文件轮换的程序(如 newsyslog 和 logrotate),可能会发生文件更改。这个处理程序打算在Unix/Linux下使用,监视文件以查看自上次发射后是否已更改。 (如果文件已更改,则认为文件已更改)。如果文件已更改,则关闭旧文件流,并打开该文件以获取新的流。
此处理程序不适合在Windows下使用,因为在Windows打开日志文件不能移动或重命名 - 日志记录使用排它锁打开文件,因此不需要这样的处理程序。此外,Windows下不支持 ST_INO; stat()
总是为此值返回零。
-
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
类是旋转文件处理程序 RotatingFileHandler
和 TimedRotatingFileHandler
的基类。你不需要实例化这个类,但它有你可能需要重写的属性和方法。
-
class
logging.handlers.
BaseRotatingHandler
(filename, mode, encoding=None, delay=False)¶ 参数为
FileHandler
。属性是:-
namer
¶ 如果此属性设置为可调用项,则
rotation_filename()
方法将委托给此可调项。传递给可调用的参数是传递给rotation_filename()
的参数。注解
在翻转期间,命名函数被称为相当多次,因此它应该尽可能简单和快速。对于给定的输入,它也应该每次返回相同的输出,否则翻转行为可能无法正常工作。
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
的实例使用相同的可调用项。如果命名或旋转器可调用引发异常,则在 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()
。默认情况下,文件无限增长。您可以使用 maxBytes 和 backupCount 值以允许文件以预定大小到 rollover。当将要超过大小时,将关闭文件,并静默打开一个新文件以输出。当当前日志文件的长度接近 maxBytes 时,发生翻转;如果 maxBytes 或 backupCount 中的任一个为零,则不会发生翻转。如果 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
对象。-
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 的类型。可能值的列表如下。请注意,它们不区分大小写。
值
间隔类型
如果/如何使用 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
类的一个新实例,该实例旨在与其地址由 host 和 port 给定的远程机器进行通信。在 3.4 版更改: 如果
port
被指定为None
,则使用host
中的值创建Unix域套接字 - 否则创建TCP套接字。-
close
()¶ 关闭套接字。
-
emit
()¶ 选择记录的属性字典并将其以二进制格式写入套接字。如果套接字有错误,则静默丢弃数据包。如果连接以前丢失,请重新建立连接。要将接收端的记录解冻成
LogRecord
,请使用makeLogRecord()
功能。
-
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
类的一个新实例,该实例旨在与其地址由 host 和 port 给定的远程机器进行通信。在 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
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)¶ 将日志记录级别名称映射到系统日志优先级名称。如果您使用自定义级别,或者如果默认算法不适合您的需要,则可能需要覆盖此选项。默认算法将
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。此版本返回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 参数。
-
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 为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
模块中,支持将日志消息发送到队列,例如在 queue
或 multiprocessing
模块中实现的队列。
与 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
类支持从队列(例如在 queue
或 multiprocessing
模块中实现的队列)接收日志消息。消息从内部线程中的队列接收并在同一线程上传递到一个或多个处理程序以进行处理。虽然 QueueListener
本身不是一个处理程序,它在这里记录,因为它与 QueueHandler
携手工作。
与 QueueHandler
类一起,QueueListener
可以用于让处理程序在与执行日志记录的线程不同的线程上执行它们的工作。这在Web应用程序以及其他服务应用程序中很重要,其中服务客户端的线程需要尽可能快地响应,而任何潜在的缓慢操作(例如通过 SMTPHandler
发送电子邮件)都是在单独的线程上完成的。
-
class
logging.handlers.
QueueListener
(queue, *handlers, respect_handler_level=False)¶ 返回
QueueListener
类的新实例。实例使用发送消息的队列和处理程序列表初始化,处理程序将处理放置在队列上的条目。队列可以是任何类似队列的对象;它按原样传递到dequeue()
方法,它需要知道如何从中获取消息。如果respect_handler_level
是True
,当决定是否向该处理程序传递消息时,处理程序的级别被遵守(与消息的级别相比);否则,该行为与以前的Python版本一样 - 总是将每个消息传递给每个处理程序。在 3.5 版更改: 添加了
respect_handler_levels
参数。-
dequeue
(block)¶ 出队记录并返回它,可选择阻塞。
基本实现使用
get()
。如果要使用超时或使用自定义队列实现,您可能想要覆盖此方法。
-
prepare
(record)¶ 准备处理记录。
这个实现只返回传入的记录。如果您需要在将记录传递给处理程序之前对记录进行任何自定义编组或操作,那么您可能想要覆盖此方法。
-
start
()¶ 启动侦听器。
这将启动一个后台线程来监视队列以使LogRecords处理。
-
stop
()¶ 停止侦听器。
这要求线程终止,然后等待它这样做。请注意,如果您在应用程序退出之前未调用此方法,则队列中可能仍有一些记录,这些记录不会被处理。
-
enqueue_sentinel
()¶ 将哨兵写入队列以告诉侦听器退出。此实现使用
put_nowait()
。如果要使用超时或使用自定义队列实现,您可能想要覆盖此方法。3.3 新版功能.
-
参见
- 模块
logging
日志模块的API参考。
- 模块
logging.config
日志模块的配置API。