15.9. logging.handlers — 日志处理程序 — Python 文档
15.9. 日志处理程序 — 日志处理程序
重要的
此页面仅包含参考信息。 有关教程，请参阅
源代码： :source:`Lib/logging/handlers.py`
包中提供了以下有用的处理程序。 请注意，其中三个处理程序（StreamHandler、FileHandler 和 NullHandler）实际上是在 logging 模块本身中定义的，但已被记录在案这里与其他处理程序一起。
15.9.1. 流处理器
StreamHandler 类位于核心 logging 包中，将日志输出发送到 sys.stdout、sys.stderr 或任何类似文件的对象（或更准确地说，支持 write() 和 flush() 方法的任何对象）。
- class logging.StreamHandler(stream=None)
返回 StreamHandler 类的新实例。 如果指定了 stream，则实例将使用它来记录输出； 否则，将使用 sys.stderr。
- emit(record)
如果指定了格式化程序，则它用于格式化记录。 然后将记录写入带有换行符终止符的流中。 如果存在异常信息，则使用 traceback.print_exception() 对其进行格式化并附加到流中。
15.9.2. 文件处理器
FileHandler 类位于核心 logging 包中，将日志输出发送到磁盘文件。 它继承了 StreamHandler 的输出功能。
- class logging.FileHandler(filename, mode='a', encoding=None, delay=False)
返回 FileHandler 类的新实例。 指定的文件被打开并用作记录流。 如果未指定 mode，则使用
'a'。 如果 encoding 不是None，则使用该编码打开文件。 如果 delay 为真，则文件打开将推迟到第一次调用 emit()。 默认情况下，文件无限增长。2.6 版更改：添加了 延迟 。
- close()
关闭文件。
- emit(record)
将记录输出到文件。
15.9.3. 空处理器
2.7 版中的新功能。
NullHandler 类位于核心 logging 包中，不进行任何格式化或输出。 它本质上是一个供库开发人员使用的“无操作”处理程序。
- class logging.NullHandler
返回 NullHandler 类的新实例。
- emit(record)
这个方法什么都不做。
- handle(record)
这个方法什么都不做。
- createLock()
此方法为锁返回
None，因为没有需要序列化访问的底层 I/O。
有关如何使用 NullHandler 的更多信息，请参阅 为库配置日志记录 。
15.9.4. 监视文件处理程序
2.6 版中的新功能。
WatchedFileHandler 类位于 logging.handlers 模块中，是一个 FileHandler，它监视它正在记录到的文件。 如果文件发生更改，则会关闭并使用文件名重新打开。
由于使用了执行日志文件轮换的程序，例如 newsyslog 和 logrotate，可能会发生文件更改。 此处理程序旨在在 Unix/Linux 下使用，监视文件以查看自上次发出以来它是否已更改。 （如果文件的设备或 inode 已更改，则认为文件已更改。）如果文件已更改，则关闭旧文件流，并打开文件以获取新流。
此处理程序不适合在 Windows 下使用，因为在 Windows 下无法移动或重命名打开的日志文件 - 日志记录使用排他锁打开文件 - 因此不需要这样的处理程序。 此外，Windows 下不支持 ST_INO； stat() 对于这个值总是返回零。
- class logging.handlers.WatchedFileHandler(filename[, mode[, encoding[, delay]]])
- 返回 WatchedFileHandler 类的新实例。 指定的文件被打开并用作记录流。 如果未指定 mode，则使用
'a'。 如果 encoding 不是None，则使用该编码打开文件。 如果 delay 为真，则文件打开将推迟到第一次调用 emit()。 默认情况下，文件无限增长。
- emit(record)
- 将记录输出到文件，但首先检查文件是否已更改。 如果是，则在将记录输出到文件之前，刷新并关闭现有流并再次打开文件。
15.9.5. 旋转文件处理器
RotatingFileHandler 类位于 logging.handlers 模块中，支持磁盘日志文件的轮换。
- class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=0)
返回 RotatingFileHandler 类的新实例。 指定的文件被打开并用作记录流。 如果未指定 mode，则使用
'a'。 如果 encoding 不是None，则使用该编码打开文件。 如果 delay 为真，则文件打开将推迟到第一次调用 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等。 分别。2.6 版更改：添加了 延迟 。
- doRollover()
进行翻转，如上所述。
- emit(record)
将记录输出到文件，满足前面所述的翻转。
15.9.6. 定时旋转文件处理器
TimedRotatingFileHandler 类位于 logging.handlers 模块中，支持以一定的时间间隔轮换磁盘日志文件。
- class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False)
返回 TimedRotatingFileHandler 类的新实例。 指定的文件被打开并用作记录流。 旋转时，它还设置文件名后缀。 旋转基于when和间隔的乘积。
您可以使用when来指定间隔的类型。 可能的值列表如下。 请注意，它们不区分大小写。
价值
间隔类型
'S'秒
'M'分钟
'H'小时
'D'天
'W0'-'W6'工作日（0=星期一）
'midnight'半夜翻身
使用基于工作日的轮换时，为星期一指定 'W0'，为星期二指定 'W1'，以此类推，直到星期日指定为 'W6'。 在这种情况下，不使用为 interval 传递的值。
系统将通过将扩展名附加到文件名来保存旧的日志文件。 扩展基于日期和时间，使用 strftime 格式
%Y-%m-%d_%H-%M-%S或其前导部分，具体取决于翻转间隔。当第一次计算下一次翻转时间时（当处理程序被创建时），现有日志文件的最后修改时间，或者当前时间，用于计算下一次轮换发生的时间。
如果 utc 参数为真，则将使用 UTC 时间； 否则使用本地时间。
如果 backupCount 不为零，则最多保留 backupCount 个文件，如果发生翻转时会创建更多文件，则删除最旧的文件。 删除逻辑使用间隔来确定要删除哪些文件，因此更改间隔可能会留下旧文件。
如果 delay 为真，则文件打开将推迟到第一次调用 emit()。
2.6 版更改：添加了 delay 和 utc。
- doRollover()
进行翻转，如上所述。
- emit(record)
将记录输出到文件，满足上述翻转。
15.9.7. 套接字处理程序
SocketHandler 类位于 logging.handlers 模块中，将日志输出发送到网络套接字。 基类使用 TCP 套接字。
- class logging.handlers.SocketHandler(host, port)
返回 SocketHandler 类的新实例，旨在与远程机器通信，其地址由 host 和 port 给出。
- close()
关闭套接字。
- emit()
Pickles 记录的属性字典并以二进制格式将其写入套接字。 如果套接字出现错误，则静默丢弃数据包。 如果连接先前丢失，则重新建立连接。 要将接收端的记录解压缩为 LogRecord，请使用 makeLogRecord() 函数。
- handleError()
处理在 emit() 期间发生的错误。 最可能的原因是连接丢失。 关闭套接字以便我们可以重试下一个事件。
- makeSocket()
这是一个工厂方法，它允许子类定义他们想要的精确套接字类型。 默认实现创建一个 TCP 套接字 (socket.SOCK_STREAM)。
- makePickle(record)
以带有长度前缀的二进制格式腌制记录的属性字典，并返回它准备好通过套接字传输。
请注意，泡菜并不完全安全。 如果您担心安全性，您可能希望覆盖此方法以实现更安全的机制。 例如，您可以使用 HMAC 对 pickles 进行签名，然后在接收端验证它们，或者您可以在接收端禁用全局对象的 unpickling。
- send(packet)
将腌制的字符串 packet 发送到套接字。 此功能允许在网络繁忙时可能发生的部分发送。
- createSocket()
尝试创建套接字； 在失败时，使用指数退避算法。 在初始失败时，处理程序将丢弃它试图发送的消息。 当后续消息由同一个实例处理时，它不会尝试连接，直到一段时间过去。 默认参数是这样的，初始延迟是一秒，如果在延迟之后仍然无法建立连接，处理程序将每次延迟加倍，最多 30 秒。
此行为由以下处理程序属性控制：
retryStart（初始延时，默认1.0秒）。retryFactor（乘数，默认为2.0）。retryMax（最大延迟，默认30.0秒）。
这意味着如果远程侦听器在 处理程序被使用后启动 ，您可能会丢失消息（因为处理程序在延迟过去之前甚至不会尝试连接，而是在处理过程中默默地丢弃消息）延迟时间）。
15.9.8. 数据报处理器
DatagramHandler 类位于 logging.handlers 模块中，继承自 SocketHandler 以支持通过 UDP 套接字发送日志消息。
- class logging.handlers.DatagramHandler(host, port)
返回 DatagramHandler 类的新实例，用于与远程机器通信，其地址由 host 和 port 给出。
- emit()
Pickles 记录的属性字典并以二进制格式将其写入套接字。 如果套接字出现错误，则静默丢弃数据包。 要将接收端的记录解压缩为 LogRecord，请使用 makeLogRecord() 函数。
- makeSocket()
SocketHandler 的工厂方法在这里被覆盖以创建一个 UDP 套接字（socket.SOCK_DGRAM）。
- send(s)
将腌制的字符串发送到套接字。
15.9.9. 系统日志处理程序
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 选项。
2.7 版更改：添加了 socktype。
- close()
关闭到远程主机的套接字。
- emit(record)
记录被格式化，然后发送到系统日志服务器。 如果存在异常信息，则 不 发送到服务器。
- encodePriority(facility, priority)
将设施和优先级编码为整数。 您可以传入字符串或整数 - 如果传递字符串，则使用内部映射字典将它们转换为整数。
符号
LOG_值在 SysLogHandler 中定义并镜像sys/syslog.h头文件中定义的值。优先事项
名称（字符串）
象征价值
alertLOG_ALERT
crit或criticalLOG_CRIT
debug日志调试
emerg或panicLOG_EMERG
err或error日志错误
info日志信息
notice日志通知
warn或warningLOG_WARNING
设施
名称（字符串）
象征价值
authLOG_AUTH
authprivLOG_AUTHPRIV
cronLOG_CRON
daemonLOG_DAEMON
ftpLOG_FTP
kernLOG_KERN
lprLOG_LPR
mailLOG_MAIL
newsLOG_NEWS
syslogLOG_SYSLOG
user登录用户
uucpLOG_UUCP
local0LOG_LOCAL0
local1LOG_LOCAL1
local2LOG_LOCAL2
local3LOG_LOCAL3
local4LOG_LOCAL4
local5LOG_LOCAL5
local6LOG_LOCAL6
local7LOG_LOCAL7
- mapPriority(levelname)
将日志级别名称映射到系统日志优先级名称。 如果您使用自定义级别，或者默认算法不适合您的需要，您可能需要覆盖它。 默认算法将
DEBUG、INFO、WARNING、ERROR和CRITICAL映射到等效的系统日志名称，并将所有其他级别名称映射到'警告'。
15.9.10。 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。
15.9.11。 SMTP处理程序
SMTPHandler 类位于 logging.handlers 模块中，支持通过 SMTP 向电子邮件地址发送日志消息。
- class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None)
返回 SMTPHandler 类的新实例。 该实例使用电子邮件的发件人和收件人地址以及主题行进行初始化。 toaddrs 应该是一个字符串列表。 要指定非标准 SMTP 端口，请对 mailhost 参数使用 (host, port) 元组格式。 如果使用字符串，则使用标准 SMTP 端口。 如果您的 SMTP 服务器需要身份验证，您可以为 credentials 参数指定一个（用户名、密码）元组。
要指定使用安全协议 (TLS)，请将元组传递给 secure 参数。 这仅在提供身份验证凭据时使用。 元组应该是一个空元组，或者一个带有密钥文件名称的单值元组，或者一个带有密钥文件和证书文件名称的 2 值元组。 （这个元组被传递给 smtplib.SMTP.starttls() 方法。）
在 2.6 版更改：添加了 凭据 。
在 2.7 版更改：添加了 secure。
- emit(record)
格式化记录并将其发送给指定的收件人。
- getSubject(record)
如果要指定与记录相关的主题行，请覆盖此方法。
15.9.12。 内存处理器
MemoryHandler 类位于 logging.handlers 模块中，支持在内存中缓冲日志记录，定期将它们刷新到 target 处理程序。 每当缓冲区已满时，或者看到某个严重性或更高级别的事件时，就会发生刷新。
MemoryHandler是更通用的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)
返回 MemoryHandler 类的新实例。 该实例使用 容量 的缓冲区大小进行初始化。 如果未指定 flushLevel，则使用
ERROR。 如果未指定 target，则在此处理程序执行任何有用的操作之前，需要使用 setTarget() 设置目标。- flush()
对于 MemoryHandler，刷新意味着只是将缓冲的记录发送到目标，如果有的话。 发生这种情况时，缓冲区也会被清除。 如果您想要不同的行为，请覆盖。
- setTarget(target)
设置此处理程序的目标处理程序。
- shouldFlush(record)
检查缓冲区已满或 flushLevel 或更高的记录。
15.9.13。 HTTP处理程序
HTTPHandler 类位于 logging.handlers 模块中，支持使用 GET 或 POST 语义向 Web 服务器发送日志消息。
- class logging.handlers.HTTPHandler(host, url, method='GET')
返回 HTTPHandler 类的新实例。
host可以采用host:port的形式，如果您需要使用特定的端口号。- mapLogRecord(record)
提供基于
record的字典，该字典将被 URL 编码并发送到 Web 服务器。 默认实现只返回record.__dict__。 如果例如，可以覆盖此方法 只有 LogRecord 的一个子集将被发送到 Web 服务器，或者如果需要对发送到服务器的内容进行更具体的定制。
- emit(record)
将记录作为 URL 编码的字典发送到 Web 服务器。 mapLogRecord() 方法用于将记录转换为要发送的字典。
笔记
由于准备将记录发送到 Web 服务器的记录与通用格式化操作不同，因此使用
setFormatter()为 HTTPHandler 指定Formatter无效。 该处理程序不调用 format()，而是调用 mapLogRecord() 和 urllib.urlencode() 以适合发送到网络服务器。
