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

Important

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

• Basic Tutorial

• Advanced Tutorial

• Logging Cookbook

源代码： Lib/logging/handlers.py

---

软件包中提供了以下有用的处理程序。请注意，其中三个处理程序(StreamHandler，FileHandler和NullHandler)实际上是在logging模块本身中定义的，但已在此处与其他处理程序一起进行了说明。

15.9.1. StreamHandler

位于核心logging包中的StreamHandler类将日志记录输出发送到流，例如* sys.stdout ， sys.stderr *或任何类似文件的对象(或更准确地说，是任何支持write()和flush()方法的对象) 。

• • class * logging. StreamHandler(* stream = None *)
  • 返回StreamHandler类的新实例。如果指定了* stream ，则实例将使用它来记录输出；否则，实例将使用它来记录输出。否则，将使用 sys.stderr *。

• emit(记录)

  • 如果指定了格式化程序，则该格式化程序用于格式化记录。然后将记录与换行符一起写入流中。如果存在异常信息，则使用traceback.print_exception()对其进行格式化并附加到流中。

• flush ( )

  • pass调用其flush()方法刷新流。请注意，close()方法是从Handler继承的，因此没有输出，因此有时可能需要显式的flush()调用。

15.9.2. FileHandler

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

• • class * logging. FileHandler(* filename ， mode ='a'， encoding = None ， delay = False *)
  • 返回FileHandler类的新实例。将打开指定的文件，并将其用作记录流。如果未指定* mode ，则使用'a'。如果 encoding 不是None，它将用于使用该编码打开文件。如果 delay *为 true，则将文件打开时间推迟到首次调用emit()时。默认情况下，文件无限期增长。

在 2.6 版中进行了更改：添加了* delay *。

• close ( )

  • 关闭文件。

• emit(记录)

  • 将记录输出到文件。

15.9.3. NullHandler

2.7 版的新Function。

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

• 类别 logging. NullHandler

  • 返回NullHandler类的新实例。

• emit(记录)

  • 此方法不执行任何操作。

• handle(记录)

  • 此方法不执行任何操作。

• createLock ( )

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

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

15.9.4. WatchedFileHandler

2.6 版的新Function。

位于logging.handlers模块中的WatchedFileHandler类是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 *为 true，则将文件打开时间推迟到首次调用emit()时。默认情况下，文件无限期增长。

• emit(记录)

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

15.9.5. RotatingFileHandler

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

• • class * logging.handlers. RotatingFileHandler(* filename ， mode ='a'， maxBytes = 0 ， backupCount = 0 ， encoding = None ， delay = 0 *)
  • 返回RotatingFileHandler类的新实例。将打开指定的文件，并将其用作记录流。如果未指定* mode ，则使用'a'。如果 encoding 不是None，它将用于使用该编码打开文件。如果 delay *为 true，则将文件打开时间推迟到首次调用emit()时。默认情况下，文件无限期增长。

您可以使用* maxBytes 和 backupCount 值来允许文件以 sched 大小翻转*。当将要超过该大小时，将关闭该文件，并以静默方式打开一个新文件以进行输出。只要当前日志文件的长度接近* maxBytes ，就会发生翻转。如果 maxBytes 或 backupCount 中的任何一个为零，则永远不会发生翻转。如果 backupCount 不为零，则系统将pass在文件名后附加 extensions'.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 版中进行了更改：添加了* delay *。

• doRollover ( )

  • 如上所述，进行过渡。

• emit(记录)

  • 将记录输出到文件，以适应如上所述的过渡。

15.9.6. TimedRotatingFileHandler

位于logging.handlers模块中的TimedRotatingFileHandler类支持按特定的时间间隔旋转磁盘日志文件。

• • class * logging.handlers. TimedRotatingFileHandler(* filename ， when ='h'， interval = 1 ， backupCount = 0 ， encoding = None ， delay = False ， utc = False *)
  • 返回TimedRotatingFileHandler类的新实例。将打开指定的文件，并将其用作记录流。旋转时还会设置文件名后缀。旋转根据* when 和 interval *的乘积发生。

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

Value	间隔类型
'S'	Seconds
'M'	Minutes
'H'	Hours
'D'	Days
'W0'-'W6'	Weekday (0=Monday)
'midnight'	午夜翻转

使用基于工作日的轮播时，将“ W0”指定为星期一，将“ W1”指定为星期二，依此类推，直到“ W6”指定为星期日。在这种情况下，不使用为* interval *传递的值。

系统将pass在文件名后附加 extensions 来保存旧的日志文件。extensions 是基于日期和时间的，使用 strftime 格式%Y-%m-%d_%H-%M-%S或其前导部分，具体取决于过渡间隔。

首次(在创建处理程序时)计算下一个过渡时间时，将使用现有日志文件的最后修改时间或当前时间来计算何时发生下一个轮换。

如果* utc *参数为 true，则将使用 UTC 时间；否则使用当地时间。

如果* backupCount 不为零，则最多将保留 backupCount *文件，并且如果发生翻转时将创建更多文件，则最早的文件将被删除。删除逻辑使用间隔来确定要删除的文件，因此更改间隔可能会使旧文件留下来。

如果* delay *为 true，则将文件打开时间推迟到第一次调用emit()时。

在 2.6 版中进行了更改：添加了* delay 和 utc *。

• doRollover ( )

  • 如上所述，进行过渡。

• emit(记录)

  • 将记录输出到文件，以适应如上所述的过渡。

15.9.7. SocketHandler

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

• • class * logging.handlers. SocketHandler(* host ， port *)
  • 返回旨在与远程计算机通信的SocketHandler类的新实例，该远程计算机的地址由* host 和 port *给出。

• close ( )

  • 关闭 socket。

• emit ( )

  • 腌制记录的属性字典，并将其以二进制格式写入套接字。如果套接字有错误，请静默丢弃数据包。如果以前丢失了连接，请重新构建连接。要将接收端的记录释放到LogRecord中，请使用makeLogRecord()函数。

• handleError ( )

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

• makeSocket ( )

  • 这是一种工厂方法，允许子类定义所需的确切套接字类型。默认实现创建一个 TCP 套接字(socket.SOCK_STREAM)。

• makePickle(记录)

  • 用长度前缀的二进制格式对记录的属性字典进行 Pickling，然后将其返回以准备在套接字上传输。

请注意，pickle 并不完全安全。如果您担心安全性，则可能需要重写此方法以实现更安全的机制。例如，您可以使用 HMAC 对 pickle 进行签名，然后在接收端对其进行验证，或者，可以在接收端禁用对全局对象的取消 Pickling。

• send(数据包)

  • 将腌制的字符串* packet *发送到套接字。此Function允许在网络繁忙时发生部分发送。

• createSocket ( )

  • try创建一个套接字；故障时，使用指数补偿算法。初始失败时，处理程序将删除其try发送的消息。当后续消息由同一实例处理时，它将不会try连接，直到经过一段时间。默认参数是初始延迟为一秒，如果在此延迟之后仍无法构建连接，则处理程序将每次将延迟加倍，最多不超过 30 秒。

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

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

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

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

这意味着，如果在使用处理程序之后*远程侦听器启动，则可能会丢失消息(因为在延迟时间过去之前，处理程序甚至不会try连接，而只是在延迟期间静默删除消息)。

15.9.8. DatagramHandler

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

• • class * logging.handlers. DatagramHandler(* host ， port *)
  • 返回旨在与远程计算机通信的DatagramHandler类的新实例，该远程计算机的地址由* host 和 port *给出。

• emit ( )

  • 腌制记录的属性字典，并将其以二进制格式写入套接字。如果套接字有错误，请静默丢弃数据包。要将接收端的记录释放到LogRecord中，请使用makeLogRecord()函数。

• makeSocket ( )

  • 此处SocketHandler的工厂方法被覆盖以创建 UDP 套接字(socket.SOCK_DGRAM)。

• send(* s *)

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

15.9.9. SysLogHandler

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

• • class * logging.handlers. SysLogHandler(* address =('localhost'， SYSLOG_UDP_PORT)， facility = LOG_USER ， socktype = socket.SOCK_DGRAM *)
  • 返回旨在与远程 Unix 机器通信的SysLogHandler类的新实例，该机器的地址由* address 以(host, port)Tuples 的形式给出。如果未指定 address ，则使用('localhost', 514)。该地址用于打开套接字。提供(host, port)Tuples 的替代方法是提供一个地址作为字符串，例如'/ 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 选项。

在 2.7 版中进行了更改：添加了* socktype *。

• close ( )

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

• emit(记录)

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

• encodePriority(设施，优先级)

  • 将Function和优先级编码为整数。您可以传入字符串或整数-如果传入字符串，则使用内部 Map 字典将其转换为整数。

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

Priorities

Name (string)	Symbolic value
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

Facilities

Name (string)	Symbolic value
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 *)
  • 将日志记录级别名称 Map 到系统日志优先级名称。如果使用自定义级别，或者默认算法不适合您的需求，则可能需要覆盖此设置。默认算法将DEBUG，INFO，WARNING，ERROR和CRITICALMap 到等效的系统日志名称，并将所有其他级别名称 Map 到'warning'。

15.9.10. NTEventLogHandler

位于logging.handlers模块中的NTEventLogHandler类支持将日志消息发送到本地 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(记录)

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

• getEventCategory(记录)

  • 返回记录的事件类别。如果要指定自己的类别，请覆盖此内容。此版本返回 0.

• getEventType(记录)

  • 返回记录的事件类型。如果要指定自己的类型，请重写此方法。此版本使用处理程序的 typemap 属性进行 Map，该属性在init()中设置为字典，该字典包含DEBUG，INFO，WARNING，ERROR和CRITICAL的 Map。如果您使用自己的关卡，则将需要重写此方法或在处理程序的* typemap *属性中放置合适的字典。

• getMessageID(记录)

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

15.9.11. SMTPHandler

位于logging.handlers模块中的SMTPHandler类支持pass SMTP 将日志消息发送到电子邮件地址。

• • class * logging.handlers. SMTPHandler(* mailhost ， fromaddr ， toaddrs ， subject ， credentials = None ， secure = None *)
  • 返回SMTPHandler类的新实例。实例使用电子邮件的“从”和“至”地址以及主题行进行初始化。 * toaddrs 应该是字符串列表。要指定非标准 SMTP 端口，请对 mailhost 参数使用(主机，端口)Tuples 格式。如果使用字符串，则使用标准的 SMTP 端口。如果您的 SMTP 服务器需要身份验证，则可以为 credentials *参数指定一个(用户名，密码)Tuples。

要指定使用安全协议(TLS)，请将 Tuples 传递给* secure *参数。仅在提供身份验证凭据时使用。该 Tuples 应该是一个空 Tuples，或者是一个具有密钥文件名的单值 Tuples，或者是一个具有密钥文件和证书文件名的二值 Tuples。 (此 Tuples 传递给smtplib.SMTP.starttls()方法。)

在 2.6 版中进行了更改：添加了* credentials *。

在 2.7 版中进行了更改：添加了“安全”。

• emit(记录)

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

• getSubject(记录)

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

15.9.12. MemoryHandler

位于logging.handlers模块中的MemoryHandler类支持在内存中缓冲日志记录，并定期将其刷新到* target *处理程序。只要缓冲区已满，或者看到某种严重程度或更严重的事件，就会发生刷新。

MemoryHandler是更通用的BufferingHandler的子类，BufferingHandler是抽象类。这会将日志记录缓冲在内存中。每当将每条记录添加到缓冲区时，都会pass调用shouldFlush()进行检查以查看是否应刷新缓冲区。如果应该，则应flush()进行冲洗。

• 等级 logging.handlers. BufferingHandler(容量)

  • 使用指定容量的缓冲区初始化处理程序。

• emit(记录)

  • 将记录追加到缓冲区。如果shouldFlush()返回 true，则调用flush()处理缓冲区。

• flush ( )

  • 您可以重写此方法以实现自定义刷新行为。此版本仅将缓冲区清空为空。

• shouldFlush(记录)

  • 如果缓冲区已满，则返回 true。可以重写此方法以实现自定义冲洗策略。
• • class * logging.handlers. MemoryHandler(* capacity ， flushLevel = ERROR ， target = None *)
  • 返回MemoryHandler类的新实例。实例使用* capacity 的缓冲区大小进行初始化。如果未指定 flushLevel ，则使用ERROR。如果未指定 target *，则在此处理程序执行任何有用的操作之前，需要使用setTarget()设置目标。

• close ( )

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

• flush ( )

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

• setTarget(* target *)

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

• shouldFlush(记录)

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

15.9.13. HTTPHandler

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

• • class * logging.handlers. HTTPHandler(* host ， url ， method ='GET'*)
  • 返回HTTPHandler类的新实例。如果您需要使用特定的端口号，则host的格式可以为host:port。

• mapLogRecord(记录)

  • 提供一个基于record的字典，该字典将进行 URL 编码并发送到 Web 服务器。默认实现只返回record.__dict__。如果例如仅将LogRecord的一个子集发送到 Web 服务器，或者如果需要对发送到服务器的内容进行更具体的自定义。

• emit(记录)

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