logging.handlers

重要

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

• 基本教程

• 高级教程

• 记录手册

源代码： Lib / logging / handlers.py

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

1. StreamHandler

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

class logging.StreamHandler(stream=None)

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

emit(record)

如果指定了格式化程序，则用它来格式化记录。 然后该记录用换行符结束符写入流中。 如果存在异常信息，则使用traceback.print_exception（）格式化并附加到流中。

flush()

通过调用其flush（）方法刷新流。 请注意，close（）方法从Handler继承，因此没有输出，因此有时需要显式flush（）调用。

2. FileHandler

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

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

返回FileHandler类的新实例。 指定的文件将被打开并用作日志记录的流。 如果没有指定模式，则使用'a'。 如果编码不是无，它将用于使用该编码打开文件。 如果延迟成立，则文件打开将延迟到第一次调用emit（）。 默认情况下，文件无限增长。

在版本2.6中进行了更改：添加了延迟。

close()

关闭文件。

emit(record)

将记录输出到文件。

3. NullHandler

2.7版本的新功能。

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

class logging.NullHandler

返回NullHandler类的新实例。

emit(record)

这种方法什么都不做。

handle(record)

这种方法什么都不做。

createLock()

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

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

4. WatchedFileHandler

2.6版本中的新功能。

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

由于使用诸如执行日志文件旋转的newsyslog和logrotate等程序，文件更改可能会发生。这个处理程序，打算在Unix / Linux下使用，监视该文件以查看自上次发出后是否发生了更改。（如果文件的设备或inode已更改，则认为文件已更改。）如果文件已更改，则旧文件流将关闭，并打开文件以获取新流。

这个处理程序不适合在Windows下使用，因为在Windows下打开日志文件不能被移动或重命名 - 日志打开带有排它锁的文件 - 因此不需要这样的处理程序。此外，Windows下不支持ST_INO ; stat()始终为此值返回零。

class logging.handlers.WatchedFileHandler(filename[, mode[, encoding[, delay]]])

返回WatchedFileHandler类的新实例。 指定的文件将被打开并用作日志记录的流。 如果没有指定模式，则使用'a'。 如果编码不是无，它将用于使用该编码打开文件。 如果延迟成立，则文件打开将延迟到第一次调用emit（）。 默认情况下，文件无限增长。

emit(record)

将记录输出到文件，但首先检查文件是否已更改。如果存在，则在将记录输出到文件之前，刷新和关闭现有流并重新打开该文件。

5. RotatingFileHandler

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

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

返回RotatingFileHandler类的新实例。 指定的文件将被打开并用作日志记录的流。 如果没有指定模式，则使用'a'。 如果编码不是none，它将用于使用该编码打开文件。 如果延迟成立，则文件打开将延迟到第一次调用emit（）。 默认情况下，文件无限增长。

您可以使用maxBytes和backupCount值来允许文件以预定大小翻转。 当即将超过大小时，文件将被关闭，并且将静默打开一个新文件以进行输出。 只要当前日志文件的长度接近maxBytes，就会发生翻转; 如果maxBytes或backupCount中的任一个为零，则不会发生翻转。 如果backupCount非零，系统将通过将扩展名“.1”，“.2”等附加到文件名来保存旧的日志文件。 例如，使用5的backupCount和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()

如上所述进行roll操作。

emit(record)

如前所述，将记录输出到文件，以适应翻滚。

6. TimedRotatingFileHandler

该TimedRotatingFileHandler级，位于在logging.handlers模块，支持以一定的时间间隔的盘日志文件旋转。

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

返回TimedRotatingFileHandler类的新实例。 指定的文件将被打开并用作日志记录的流。 在旋转它也设置文件名后缀。 旋转基于时间和间隔的乘积而发生。

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

当使用以工作日为基础的轮换时，星期一指定'W0'，星期二指定'W1'，星期日指定'W6'。在这种情况下，不会使用为时间间隔传递的值。

系统将通过将扩展名附加到文件名来保存旧的日志文件。 这些扩展名基于日期和时间，使用strftime格式，取决于翻转间隔，使用strftime格式％Y％m％d％H％M％S或其前导部分。

第一次计算下一个翻转时间（创建处理程序时），现有日志文件的最后修改时间或当前时间用于计算下一次旋转的发生时间。

如果utc参数为true，则将使用UTC中的时间; 否则使用本地时间。

如果backupCount不为零，则至多backupCount文件将被保留，并且如果在发生滚动时会创建更多，则会删除最旧的一个。删除逻辑使用间隔来确定要删除哪些文件，因此更改间隔可能会使旧文件处于闲置状态。

如果延迟是真的，则文件打开被推迟到第一次呼叫emit()。

在版本2.6中进行了更改：添加了延迟和utc。

doRollover()

如上所述进行roll。

emit(record)

将记录输出到文件，以适应上述的翻转。

7. SocketHandler

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

class logging.handlers.SocketHandler(host, port)

返回SocketHandler该类的新实例，用于与其地址由主机和端口给定的远程计算机进行通信。

close()

关闭socket。

emit()

Pickles记录的属性字典并以二进制格式将其写入套接字。如果套接字发生错误，则以静默方式丢弃数据包。如果连接先前丢失，请重新建立连接。要将接收端的记录解开为LogRecord，请使用该makeLogRecord()功能。

handleError()

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

makeSocket()

这是一种工厂方法，它允许子类定义他们想要的确切类型的套接字。默认实现创建一个TCP套接字（socket.SOCK_STREAM）。

makePickle(record)

使用长度前缀以二进制格式浸泡记录的属性字典，并将其返回，以便通过套接字进行传输。

请注意，pickles并不完全安全。如果您担心安全问题，则可能需要重写此方法以实现更安全的机制。例如，您可以使用HMAC签署酱菜，然后在接收端验证它们，或者您也可以在接收端禁用取消全局对象。

send(packet)

发送一个pickled字符串包到套接字。此功能允许在网络繁忙时发生部分发送。

createSocket()

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

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

• retryStart （初始延迟，默认为1.0秒）。

• retryFactor （乘数，默认为2.0）。

• retryMax （最大延迟时间，默认为30.0秒）。

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

8. DatagramHandler

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

class logging.handlers.DatagramHandler(host, port)

返回DatagramHandler该类的新实例，用于与其地址由主机和端口给定的远程计算机进行通信。

emit()

Pickles记录的属性字典并以二进制格式将其写入套接字。如果套接字发生错误，则以静默方式丢弃数据包。要将接收端的记录解开为 LogRecord，请使用该makeLogRecord()功能。

makeSocket()

此方法在SocketHandler这里被覆盖以创建一个UDP套接字（socket.SOCK_DGRAM）。

send(s)

发送pickled字符串到套接字。

9. SysLogHandler

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

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

返回SyslogHandler类的新实例，用于与远程Unix机器进行通信，该机器的地址由（主机，端口）元组形式的地址给出。 如果未指定地址，则使用（'localhost'，514）。 该地址用于打开套接字。 提供（主机，端口）元组的替代方法是将地址作为字符串提供，例如'/ dev / log'。 在这种情况下，使用Unix域套接字将消息发送到系统日志。 如果没有指定设施，则使用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选项。

在版本2.7中更改：添加了socktype。

close()

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

emit(record)

记录被格式化，然后发送到系统日志服务器。如果存在异常信息，则不会将其发送到服务器。

encodePriority(facility, priority)

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

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

优先级

设备

mapPriority(levelname)

将日志记录级别名称映射到系统日志优先级名称。 如果您使用的是自定义级别，或者默认算法不适合您的需要，则可能需要覆盖此设置。 默认算法将DEBUG，INFO，WARNING，ERROR和CRITICAL映射到等效syslog名称，并将所有其他级别名称映射为'warning'。

10. NTEventLogHandler

该模块NTEventLogHandler位于logging.handlers模块中，支持将日志消息发送到本地Windows NT，Windows 2000或Windows XP事件日志。在您使用它之前，您需要安装Mark Hammond的Win32 Python扩展。

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')

返回NTEventLogHandler类的新实例。 应用程序名称用于定义应用程序名称，因为它出现在事件日志中。 使用此名称创建适当的注册表项。 dllname应该提供包含消息定义的.dll或.exe的全限定路径名，以保存在日志中（如果未指定，则使用'win32service.pyd' - 它与Win32扩展一起安装并包含一些基本的占位符消息 请注意，使用这些占位符将使您的事件日志变大，因为整个消息源都保存在日志中。如果您希望更轻松的日志，则必须传入自己的.dll或.exe的名称，其中包含 您想在事件日志中使用的消息定义）。 日志类型是“应用程序”，“系统”或“安全性”之一，默认为“应用程序”。

close()

此时，您可以从注册表中删除应用程序名称作为事件日志条目的来源。但是，如果您这样做，您将无法按照您在事件日志查看器中预期的方式查看事件 - 它需要能够访问注册表以获取.dll名称。目前的版本不这样做。

emit(record)

确定消息ID，事件类别和事件类型，然后在NT事件日志中记录消息。

getEventCategory(record)

返回记录的事件类别。如果您想指定自己的类别，请覆盖此选项。该版本返回0。

getEventType(record)

返回记录的事件类型。 如果你想指定你自己的类型，覆盖这个。 该版本使用处理程序的typemap属性进行映射，该属性在__init __（）中设置为包含DEBUG，INFO，WARNING，ERROR和CRITICAL映射的字典。 如果您使用自己的级别，则需要重写此方法或在处理程序的typemap属性中放置合适的字典。

getMessageID(record)

返回记录的消息ID。 如果您使用的是自己的消息，则可以通过将消息传递给记录器作为ID而不是格式字符串来实现此目的。 然后，在这里，您可以使用字典查找来获取消息ID。 此版本返回1，它是win32service.pyd中的基本消息ID。

11. SMTPHandler

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

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

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

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

在版本2.6中更改：添加了凭据。

版本2.7中更改：已添加安全。

emit(record)

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

getSubject(record)

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

12. MemoryHandler

该MemoryHandler级，位于在logging.handlers模块，支持在内存中的日志记录缓冲，定期将其冲洗到目标处理程序。每当缓冲区已满时，或者发现某个严重程度或更高的事件时，都会发生刷新。

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。 如果未指定目标，则在此处理程序执行任何有用的操作之前，需要使用setTarget（）设置目标。

close()

调用flush（），将目标设置为None并清除缓冲区。

flush()

对于MemoryHandler来说，flush意味着将缓冲的记录发送到目标（如果有的话）。发生这种情况时，缓冲区也会被清除。覆盖，如果你想要不同的行为。

setTarget(target)

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

shouldFlush(record)

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

13. HTTPHandler

位于logging.handlers模块中的HTTPHandler类支持使用GET或POST语义将日志消息发送到Web服务器。

class logging.handlers.HTTPHandler(host, url, method='GET')

返回HTTPHandler类的新实例。 如果您需要使用特定的端口号，主机可以是host：port形式。

mapLogRecord(record)

提供一个字典，基于该字典record进行URL编码并发送到Web服务器。默认实现只是返回record.__dict__。如果只有一部分LogRecord要发送到Web服务器，或者需要更多特定的发送到服务器的内容，则可以覆盖此方法。

emit(record)

将记录作为URL编码字典发送到Web服务器。 mapLogRecord（）方法用于将记录转换为要发送的字典。

注意

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

扩展内容

Module logging 记录模块的API参考。 Module logging.config 记录模块的配置API。