python / 3.7.2rc1 / all / library-logging.handlers.html

logging.handlers —日志处理程序

源代码: Lib/logging/handlers.py

Important

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


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

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()调用。
  • setStream()

    • 如果实例的流不同,则将其设置为指定的值。在设置新流之前,将刷新旧流。
  • Parameters

     - **stream**  – The stream that the handler should use\.
    
    • Returns

      • 旧流(如果已更改),或(如果未更改)。

3.7 版中的新Function。

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

FileHandler

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

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

在版本 3.6 中进行了更改:除字符串值外,* filename *参数也接受Path个对象。

  • close ( )

    • 关闭文件。
  • emit(记录)

    • 将记录输出到文件。

NullHandler

3.1 版中的新Function。

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

  • 类别 logging. NullHandler

  • emit(记录)

    • 此方法不执行任何操作。
  • handle(记录)

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

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

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

WatchedFileHandler

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

由于使用诸如* newsyslog logrotate *之类的程序来执行日志文件轮换,因此可能会发生文件更改。该处理程序旨在在 Unix/Linux 下使用,它监视文件以查看自上一次发出以来是否已更改。 (如果文件的设备或 inode 发生更改,则认为该文件已更改.)如果文件已更改,则关闭旧文件流,并打开该文件以获取新的流。

该处理程序不适用于 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 版的新Function。

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

BaseRotatingHandler

位于logging.handlers模块中的BaseRotatingHandler类是旋转文件处理程序RotatingFileHandlerTimedRotatingFileHandler的 Base Class。您不需要实例化此类,但是它具有您可能需要覆盖的属性和方法。

    • class * logging.handlers. BaseRotatingHandler(* filename mode encoding = None delay = False *)
    • 参数与FileHandler相同。这些属性是:
  • namer

Note

在过渡期间,多次调用了 namer 函数,因此它应该尽可能简单和快速。对于给定的 Importing,它每次也应该返回相同的输出,否则翻转行为可能无法按预期工作。

版本 3.3 中的新Function。

  • rotator
    • 如果此属性设置为可调用,则rotate()方法委托给此可调用。传递给可调用对象的参数是传递给rotate()的参数。

版本 3.3 中的新Function。

  • rotation_filename(* default_name *)
    • 轮换时修改日志文件的文件名。

提供此名称是为了提供自定义文件名。

默认实现调用处理程序的'namer'属性(如果可以调用),并将默认名称传递给该属性。如果该属性不可调用(默认值为None),则名称将保持不变。

  • Parameters

     - **default_name**  – The default name for the log file\.
    

版本 3.3 中的新Function。

  • rotate(来源目标)
    • 旋转时,旋转当前日志。

默认实现调用处理程序的'rotator'属性(如果可以调用的话),并将 source 和 dest 参数传递给它。如果该属性不可调用(默认值为None),则仅将源重命名为目标。

  • Parameters

     - - **source**  – The source filename\. This is normally the base filename, e\.g\. 'test\.log'\.
    
  • dest –目标文件名。这通常是光源旋转到的位置,例如'test.log.1'。

版本 3.3 中的新Function。

属性存在的原因是省去了子类化的麻烦-您可以对RotatingFileHandlerTimedRotatingFileHandler的实例使用相同的可调用对象。如果 namer 或 rotator 可调用项引发异常,则在emit()调用期间,即pass处理程序的handleError()方法,将以与其他任何异常相同的方式处理该异常。

如果需要对轮换处理进行更重要的更改,则可以覆盖这些方法。

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

RotatingFileHandler

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

    • 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 值来允许文件以 sched 大小翻转*。当将要超过该大小时,将关闭该文件,并以静默方式打开一个新文件以进行输出。只要当前日志文件的长度接近* maxBytes ,就会发生翻转。但是如果 maxBytes backupCount 中的任何一个为零,则永远不会发生翻转,因此您通常希望将 backupCount 设置为至少 1,并且 maxBytes 为非零。当 backupCount 不为零时,系统将pass在文件名后附加 extensions'.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(记录)

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

TimedRotatingFileHandler

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

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

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

Value 间隔类型 是否/如何使用* atTime *
'S' Seconds Ignored
'M' Minutes Ignored
'H' Hours Ignored
'D' Days Ignored
'W0'-'W6' Weekday (0=Monday) 用于计算初始过渡时间
'midnight' 如果未指定* atTime ,则在午夜翻转;否则,在 atTime *的时间翻转 用于计算初始过渡时间

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

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

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

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

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

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

如果* atTime 不是None,则它必须是datetime.time实例,该实例指定发生翻转的一天中的时间,对于将翻转设置为“在午夜”或“在特定工作日”发生的情况。请注意,在这些情况下, atTime 值可有效地用于计算 initial *过渡,随后的过渡将pass正常间隔计算来计算。

Note

初始化处理程序时,将完成初始翻转时间的计算。仅当发生翻转时才进行后续翻转时间的计算,而仅在发出输出时才发生翻转。如果不牢记这一点,可能会导致混乱。例如,如果将时间间隔设置为“每分钟”,这并不意味着您将始终看到时间(在文件名中)以一分钟为间隔的日志文件。如果在应用程序执行期间,日志记录输出的生成频率超过每分钟一次,那么那么您可以期望看到时间间隔为一分钟的日志文件。另一方面,如果日志消息每五分钟仅输出一次(例如),则文件时间中将存在间隔,该间隔对应于没有输出(因此也没有翻转)的分钟。

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

在版本 3.6 中进行了更改:除字符串值外,* filename *参数也接受Path个对象。

  • doRollover ( )

    • 如上所述,进行过渡。
  • emit(记录)

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

SocketHandler

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

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

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

  • close ( )

    • 关闭 socket。
  • emit ( )

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

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

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

    • 用长度前缀的二进制格式对记录的属性字典进行 Pickling,然后将其返回以准备在套接字上传输。此操作的详细信息等效于:
data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

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

  • send(数据包)
    • 发送一个腌制的字节串数据包到套接字。发送的字节字符串的格式如makePickle()的文档中所述。

此Function允许部分发送,这可能在网络繁忙时发生。

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

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

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

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

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

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

DatagramHandler

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

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

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

  • emit ( )

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

  • send(* s *)

    • 发送一个腌制的字节串到套接字。发送的字节字符串的格式如SocketHandler.makePickle()的文档中所述。

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 选项。

在版本 3.2 中更改:添加了* socktype *。

  • close ( )

    • 关闭套接字到远程主机。
  • emit(记录)

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

在版本 3.2.1 中进行了更改:(请参阅:bpo-12168。)在早期版本中,发送到 syslog 守护程序的消息始终以 NUL 字节终止,因为这些守护程序的早期版本期望以 NUL 终止的消息-即使它不在相关规范( RFC 5424)。这些守护程序的最新版本不希望使用 NUL 字节,而是将其剥离(如果存在),甚至更新的守护程序(更紧密地遵循 RFC 5424)将 NUL 字节作为消息的一部分传递。

为了面对所有这些不同的守护程序行为,能够更轻松地处理 syslog 消息,pass使用类级属性append_nul,可以将 NUL 字节的附加添加配置为可配置的。默认值为True(保留现有行为),但可以在SysLogHandler实例上将其设置为False,以便该实例附加 NUL 终止符。

在版本 3.3 中进行了更改:(请参阅:bpo-12419。)在早期版本中,没有用于“ ident”或“ tag”前缀的Function来标识消息的来源。现在可以使用类级别的属性来指定此属性,默认为""以保留现有的行为,但是可以在SysLogHandler实例上覆盖该属性,以使该实例在所有处理的消息之前添加 ident。请注意,提供的标识符必须是文本,而不是字节,并且完全照原样添加到消息中。

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

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

Priorities

Name (string) Symbolic value
alert LOG_ALERT
critcritical LOG_CRIT
debug LOG_DEBUG
emergpanic LOG_EMERG
errerror LOG_ERR
info LOG_INFO
notice LOG_NOTICE
warnwarning 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 到系统日志优先级名称。如果使用自定义级别,或者默认算法不适合您的需求,则可能需要覆盖此设置。默认算法将DEBUGINFOWARNINGERRORCRITICALMap 到等效的系统日志名称,并将所有其他级别名称 Map 到'warning'。

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()中设置为字典,该字典包含DEBUGINFOWARNINGERRORCRITICAL的 Map。如果您使用自己的关卡,则将需要重写此方法或在处理程序的* typemap *属性中放置合适的字典。
  • getMessageID(记录)

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

SMTPHandler

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

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

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

可以使用* timeout *参数指定与 SMTP 服务器进行通信的超时时间。

版本 3.3 中的新增Function:添加了* timeout *参数。

  • emit(记录)

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

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

MemoryHandler

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

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

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

    • 使用指定容量的缓冲区初始化处理程序。在这里,“容量”是指缓冲的日志记录数。
  • emit(记录)

  • flush ( )

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

    • 如果缓冲区已满,则返回True。可以重写此方法以实现自定义冲洗策略。
    • class * logging.handlers. MemoryHandler(* capacity flushLevel = ERROR target = None flushOnClose = True *)
    • 返回MemoryHandler类的新实例。实例使用* capacity (缓冲的记录数)的缓冲区大小进行初始化。如果未指定 flushLevel ,则使用ERROR。如果未指定 target ,则在此处理程序执行任何有用的操作之前,需要使用setTarget()设置目标。如果将 flushOnClose *指定为False,则在关闭处理程序时不刷新缓冲区。如果未指定或指定为True,则在关闭处理程序时,将发生刷新缓冲区的先前行为。

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

  • close ( )

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

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

    • 设置此处理程序的目标处理程序。
  • shouldFlush(记录)

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

HTTPHandler

位于logging.handlers模块中的HTTPHandler类支持使用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 *,则它应该是一个由用户 ID 和密码组成的 2Tuples,将使用基本身份验证将其放置在 HTTP“ Authorization”Headers 中。如果指定凭据,则还应指定 secure = True,以便您的用户名和密码不会以明文形式pass网络传递。

在版本 3.5 中更改:添加了* context *参数。

  • mapLogRecord(记录)

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

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

Note

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

QueueHandler

3.2 版中的新Function。

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

QueueListener类一起使用QueueHandler可用于使处理程序在与进行日志记录的线程不同的单独线程上完成其工作。这在 Web 应用程序以及其他服务应用程序中很重要,在这些应用程序中,服务 Client 端的线程需要尽快响应,而任何潜在的慢速操作(例如passSMTPHandler发送电子邮件)都在单独的线程上完成。

  • 类别 logging.handlers. QueueHandler(队列)

    • 返回QueueHandler类的新实例。实例使用队列进行初始化以向其发送消息。 * queue 可以是任何类似于队列的对象; enqueue()方法按原样使用它,该方法需要知道如何向它发送消息。不需要队列具有任务跟踪 API,这意味着您可以将SimpleQueue实例用于* queue *。
  • emit(记录)

    • 使准备 LogRecord 的结果入队。如果发生异常(例如,由于队列已满),则调用handleError()方法来处理错误。这可能导致记录被静默删除(如果logging.raiseExceptionsFalse)或将消息打印到sys.stderr(如果logging.raiseExceptionsTrue)。
  • prepare(记录)

    • 准备要排队的记录。此方法返回的对象已入队。

基本实现格式化记录以合并消息,参数和异常信息(如果存在)。它还会从原位 Logging 删除无法挑剔的项目。

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

  • enqueue(记录)
    • 使用put_nowait()将记录放入队列中;如果要使用阻止行为,超时或自定义队列实现,则可能需要覆盖此方法。

QueueListener

3.2 版中的新Function。

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

QueueHandler类一起使用QueueListener可用于使处理程序在与进行日志记录的线程不同的单独线程上完成其工作。这在 Web 应用程序以及其他服务应用程序中很重要,在这些应用程序中,服务 Client 端的线程需要尽快响应,而任何潜在的慢速操作(例如passSMTPHandler发送电子邮件)都在单独的线程上完成。

    • class * logging.handlers. QueueListener(* queue * handlers respect_handler_level = False *)
    • 返回QueueListener类的新实例。实例使用队列进行初始化,以向其发送消息,并使用处理程序列表来处理放置在队列中的条目。队列可以是任何类似队列的对象;它将按原样传递给dequeue()方法,该方法需要知道如何从中获取消息。不需要队列具有任务跟踪 API(尽管可用),这意味着您可以将SimpleQueue实例用于 queue *。

如果respect_handler_levelTrue,则在决定是否将消息传递给该处理程序时,将遵守处理程序的级别(与消息的级别相比);否则,行为与以前的 Python 版本相同-始终将每个消息传递给每个处理程序。

在版本 3.5 中更改:添加了respect_handler_level参数。

  • dequeue(* block *)
    • 使记录出队并返回它,可以选择阻塞。

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

  • prepare(记录)
    • 准备要处理的记录。

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

  • handle(记录)
    • 处理记录。

这只是遍历处理程序,为它们提供要处理的记录。传递给处理程序的实际对象是从prepare()返回的对象。

  • start ( )
    • 启动监听器。

这将启动一个后台线程,以监视要处理 LogRecords 的队列。

  • stop ( )
    • 停止监听器。

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

  • enqueue_sentinel ( )
    • 将标记写入队列以告知侦听器退出。此实现使用put_nowait()。如果要使用超时或使用自定义队列实现,则可能要覆盖此方法。

版本 3.3 中的新Function。

See also

  • Module logging

  • 日志记录模块的 API 参考。

  • Module logging.config

  • 日志记录模块的配置 API。