New in version 2.3.
This module defines functions and classes which implement a flexible eventlogging system for applications and libraries.
The key benefit of having the logging API provided by a standard library moduleis that all Python modules can participate in logging, so your application logcan include your own messages integrated with messages from third-partymodules.
The module provides a lot of functionality and flexibility. If you areunfamiliar with logging, the best way to get to grips with it is to see thetutorials (see the links on the right).
The basic classes defined by the module, together with their functions, arelisted below.
Loggers have the following attributes and methods. Note that Loggers are neverinstantiated directly, but always through the module-level functionlogging.getLogger(name). Multiple calls to getLogger() with the samename will always return a reference to the same Logger object.
The name is potentially a period-separated hierarchical value, likefoo.bar.baz (though it could also be just plain foo, for example).Loggers that are further down in the hierarchical list are children of loggershigher up in the list. For example, given a logger with a name of foo,loggers with names of foo.bar, foo.bar.baz, and foo.bam are alldescendants of foo. The logger name hierarchy is analogous to the Pythonpackage hierarchy, and identical to it if you organise your loggers on aper-module basis using the recommended constructionlogging.getLogger(__name__). That’s because in a module, __name__is the module’s name in the Python package namespace.
If this evaluates to true, logging messages are passed by this logger and byits child loggers to the handlers of higher level (ancestor) loggers.Messages are passed directly to the ancestor loggers’ handlers - neither thelevel nor filters of the ancestor loggers in question are considered.
If this evaluates to false, logging messages are not passed to the handlersof ancestor loggers.
The constructor sets this attribute to True.
Sets the threshold for this logger to lvl. Logging messages which are lesssevere than lvl will be ignored. When a logger is created, the level is set toNOTSET (which causes all messages to be processed when the logger isthe root logger, or delegation to the parent when the logger is a non-rootlogger). Note that the root logger is created with level WARNING.
The term ‘delegation to the parent’ means that if a logger has a level ofNOTSET, its chain of ancestor loggers is traversed until either an ancestor witha level other than NOTSET is found, or the root is reached.
If an ancestor is found with a level other than NOTSET, then that ancestor’slevel is treated as the effective level of the logger where the ancestor searchbegan, and is used to determine how a logging event is handled.
If the root is reached, and it has a level of NOTSET, then all messages will beprocessed. Otherwise, the root’s level will be used as the effective level.
Indicates if a message of severity lvl would be processed by this logger.This method checks first the module-level level set bylogging.disable(lvl) and then the logger’s effective level as determinedby getEffectiveLevel().
Indicates the effective level for this logger. If a value other thanNOTSET has been set using setLevel(), it is returned. Otherwise,the hierarchy is traversed towards the root until a value other thanNOTSET is found, and that value is returned.
Returns a logger which is a descendant to this logger, as determined by the suffix.Thus, logging.getLogger('abc').getChild('def.ghi') would return the samelogger as would be returned by logging.getLogger('abc.def.ghi'). This is aconvenience method, useful when the parent logger is named using e.g. __name__rather than a literal string.
New in version 2.7.
Logs a message with level DEBUG on this logger. The msg is themessage format string, and the args are the arguments which are merged intomsg using the string formatting operator. (Note that this means that you canuse keywords in the format string, together with a single dictionary argument.)
There are two keyword arguments in kwargs which are inspected: exc_infowhich, if it does not evaluate as false, causes exception information to beadded to the logging message. If an exception tuple (in the format returned bysys.exc_info()) is provided, it is used; otherwise, sys.exc_info()is called to get the exception information.
The second keyword argument is extra which can be used to pass adictionary which is used to populate the __dict__ of the LogRecord created forthe logging event with user-defined attributes. These custom attributes can thenbe used as you like. For example, they could be incorporated into loggedmessages. For example:
FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'logging.basicConfig(format=FORMAT)d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}logger = logging.getLogger('tcpserver')logger.warning('Protocol problem: %s', 'connection reset', extra=d)would print something like
2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection resetThe keys in the dictionary passed in extra should not clash with the keys usedby the logging system. (See the Formatter documentation for moreinformation on which keys are used by the logging system.)
If you choose to use these attributes in logged messages, you need to exercisesome care. In the above example, for instance, the Formatter has beenset up with a format string which expects ‘clientip’ and ‘user’ in the attributedictionary of the LogRecord. If these are missing, the message will not belogged because a string formatting exception will occur. So in this case, youalways need to pass the extra dictionary with these keys.
While this might be annoying, this feature is intended for use in specializedcircumstances, such as multi-threaded servers where the same code executes inmany contexts, and interesting conditions which arise are dependent on thiscontext (such as remote client IP address and authenticated user name, in theabove example). In such circumstances, it is likely that specializedFormatters would be used with particular Handlers.
Logs a message with level INFO on this logger. The arguments areinterpreted as for debug().
Logs a message with level WARNING on this logger. The arguments areinterpreted as for debug().
Logs a message with level ERROR on this logger. The arguments areinterpreted as for debug().
Logs a message with level CRITICAL on this logger. The arguments areinterpreted as for debug().
Logs a message with integer level lvl on this logger. The other arguments areinterpreted as for debug().
Logs a message with level ERROR on this logger. The arguments areinterpreted as for debug(). Exception info is added to the loggingmessage. This method should only be called from an exception handler.
Adds the specified filter filt to this logger.
Removes the specified filter filt from this logger.
Applies this logger’s filters to the record and returns a true value if therecord is to be processed.
Adds the specified handler hdlr to this logger.
Removes the specified handler hdlr from this logger.
Finds the caller’s source filename and line number. Returns the filename, linenumber and function name as a 3-element tuple.
Changed in version 2.4: The function name was added. In earlier versions, the filename and linenumber were returned as a 2-element tuple.
Handles a record by passing it to all handlers associated with this logger andits ancestors (until a false value of propagate is found). This method is usedfor unpickled records received from a socket, as well as those created locally.Logger-level filtering is applied using filter().
This is a factory method which can be overridden in subclasses to createspecialized LogRecord instances.
Changed in version 2.5: func and extra were added.
Handlers have the following attributes and methods. Note that Handleris never instantiated directly; this class acts as a base for more usefulsubclasses. However, the __init__() method in subclasses needs to callHandler.__init__().
Initializes the Handler instance by setting its level, setting the listof filters to the empty list and creating a lock (using createLock()) forserializing access to an I/O mechanism.
Initializes a thread lock which can be used to serialize access to underlyingI/O functionality which may not be threadsafe.
Acquires the thread lock created with createLock().
Releases the thread lock acquired with acquire().
Sets the threshold for this handler to lvl. Logging messages which are lesssevere than lvl will be ignored. When a handler is created, the level is setto NOTSET (which causes all messages to be processed).
Sets the Formatter for this handler to form.
Adds the specified filter filt to this handler.
Removes the specified filter filt from this handler.
Applies this handler’s filters to the record and returns a true value if therecord is to be processed.
Ensure all logging output has been flushed. This version does nothing and isintended to be implemented by subclasses.
Tidy up any resources used by the handler. This version does no output butremoves the handler from an internal list of handlers which is closed whenshutdown() is called. Subclasses should ensure that this gets calledfrom overridden close() methods.
Conditionally emits the specified logging record, depending on filters which mayhave been added to the handler. Wraps the actual emission of the record withacquisition/release of the I/O thread lock.
This method should be called from handlers when an exception is encounteredduring an emit() call. If the module-level attributeraiseExceptions is False, exceptions get silently ignored. This iswhat is mostly wanted for a logging system - most users will not care abouterrors in the logging system, they are more interested in applicationerrors. You could, however, replace this with a custom handler if you wish.The specified record is the one which was being processed when the exceptionoccurred. (The default value of raiseExceptions is True, as that ismore useful during development).
Do formatting for a record - if a formatter is set, use it. Otherwise, use thedefault formatter for the module.
Do whatever it takes to actually log the specified logging record. This versionis intended to be implemented by subclasses and so raises aNotImplementedError.
For a list of handlers included as standard, see logging.handlers.
Formatter objects have the following attributes and methods. They areresponsible for converting a LogRecord to (usually) a string which canbe interpreted by either a human or an external system. The baseFormatter allows a formatting string to be specified. If none issupplied, the default value of '%(message)s' is used.
A Formatter can be initialized with a format string which makes use of knowledgeof the LogRecord attributes - such as the default value mentioned abovemaking use of the fact that the user’s message and arguments are pre-formattedinto a LogRecord‘s message attribute. This format string containsstandard Python %-style mapping keys. See section String Formatting Operationsfor more information on string formatting.
The useful mapping keys in a LogRecord are given in the section onLogRecord attributes.
Returns a new instance of the Formatter class. The instance isinitialized with a format string for the message as a whole, as well as aformat string for the date/time portion of a message. If no fmt isspecified, '%(message)s' is used. If no datefmt is specified, theISO8601 date format is used.
The record’s attribute dictionary is used as the operand to a stringformatting operation. Returns the resulting string. Before formatting thedictionary, a couple of preparatory steps are carried out. The messageattribute of the record is computed using msg % args. If theformatting string contains '(asctime)', formatTime() is calledto format the event time. If there is exception information, it isformatted using formatException() and appended to the message. Notethat the formatted exception information is cached in attributeexc_text. This is useful because the exception information can bepickled and sent across the wire, but you should be careful if you havemore than one Formatter subclass which customizes the formattingof exception information. In this case, you will have to clear the cachedvalue after a formatter has done its formatting, so that the nextformatter to handle the event doesn’t use the cached value butrecalculates it afresh.
This method should be called from format() by a formatter whichwants to make use of a formatted time. This method can be overridden informatters to provide for any specific requirement, but the basic behavioris as follows: if datefmt (a string) is specified, it is used withtime.strftime() to format the creation time of therecord. Otherwise, the ISO8601 format is used. The resulting string isreturned.
This function uses a user-configurable function to convert the creationtime to a tuple. By default, time.localtime() is used; to changethis for a particular formatter instance, set the converter attributeto a function with the same signature as time.localtime() ortime.gmtime(). To change it for all formatters, for example if youwant all logging times to be shown in GMT, set the converterattribute in the Formatter class.
Formats the specified exception information (a standard exception tuple asreturned by sys.exc_info()) as a string. This default implementationjust uses traceback.print_exception(). The resulting string isreturned.
Filters can be used by Handlers and Loggers for more sophisticatedfiltering than is provided by levels. The base filter class only allows eventswhich are below a certain point in the logger hierarchy. For example, a filterinitialized with ‘A.B’ will allow events logged by loggers ‘A.B’, ‘A.B.C’,‘A.B.C.D’, ‘A.B.D’ etc. but not ‘A.BB’, ‘B.A.B’ etc. If initialized with theempty string, all events are passed.
Returns an instance of the Filter class. If name is specified, itnames a logger which, together with its children, will have its events allowedthrough the filter. If name is the empty string, allows every event.
Is the specified record to be logged? Returns zero for no, nonzero foryes. If deemed appropriate, the record may be modified in-place by thismethod.
Note that filters attached to handlers are consulted whenever an event isemitted by the handler, whereas filters attached to loggers are consultedwhenever an event is logged to the handler (using debug(), info(),etc.) This means that events which have been generated by descendant loggerswill not be filtered by a logger’s filter setting, unless the filter has alsobeen applied to those descendant loggers.
You don’t actually need to subclass Filter: you can pass any instancewhich has a filter method with the same semantics.
Although filters are used primarily to filter records based on moresophisticated criteria than levels, they get to see every record which isprocessed by the handler or logger they’re attached to: this can be useful ifyou want to do things like counting how many records were processed by aparticular logger or handler, or adding, changing or removing attributes inthe LogRecord being processed. Obviously changing the LogRecord needs to bedone with some care, but it does allow the injection of contextual informationinto logs (see Using Filters to impart contextual information).
LogRecord instances are created automatically by the Loggerevery time something is logged, and can be created manually viamakeLogRecord() (for example, from a pickled event received over thewire).
Contains all the information pertinent to the event being logged.
The primary information is passed in msg and args, whichare combined using msg % args to create the message field of therecord.
| Parameters: |
|
|---|
Changed in version 2.5: func was added.
Returns the message for this LogRecord instance after merging anyuser-supplied arguments with the message. If the user-supplied messageargument to the logging call is not a string, str() is called on it toconvert it to a string. This allows use of user-defined classes asmessages, whose __str__ method can return the actual format string tobe used.
The LogRecord has a number of attributes, most of which are derived from theparameters to the constructor. (Note that the names do not always correspondexactly between the LogRecord constructor parameters and the LogRecordattributes.) These attributes can be used to merge data from the record intothe format string. The following table lists (in alphabetical order) theattribute names, their meanings and the corresponding placeholder in a %-styleformat string.
| Attribute name | Format | Description |
|---|---|---|
| args | You shouldn’t need toformat this yourself. | The tuple of arguments merged into msg toproduce message. |
| asctime | %(asctime)s | Human-readable time when theLogRecord was created. By defaultthis is of the form ‘2003-07-08 16:49:45,896’(the numbers after the comma are millisecondportion of the time). |
| created | %(created)f | Time when the LogRecord was created(as returned by time.time()). |
| exc_info | You shouldn’t need toformat this yourself. | Exception tuple (à la sys.exc_info) or,if no exception has occurred, None. |
| filename | %(filename)s | Filename portion of pathname. |
| funcName | %(funcName)s | Name of function containing the logging call. |
| levelname | %(levelname)s | Text logging level for the message('DEBUG', 'INFO', 'WARNING','ERROR', 'CRITICAL'). |
| levelno | %(levelno)s | Numeric logging level for the message(DEBUG, INFO,WARNING, ERROR,CRITICAL). |
| lineno | %(lineno)d | Source line number where the logging call wasissued (if available). |
| module | %(module)s | Module (name portion of filename). |
| msecs | %(msecs)d | Millisecond portion of the time when theLogRecord was created. |
| message | %(message)s | The logged message, computed as msg %args. This is set whenFormatter.format() is invoked. |
| msg | You shouldn’t need toformat this yourself. | The format string passed in the originallogging call. Merged with args toproduce message, or an arbitrary object(see Using arbitrary objects as messages). |
| name | %(name)s | Name of the logger used to log the call. |
| pathname | %(pathname)s | Full pathname of the source file where thelogging call was issued (if available). |
| process | %(process)d | Process ID (if available). |
| processName | %(processName)s | Process name (if available). |
| relativeCreated | %(relativeCreated)d | Time in milliseconds when the LogRecord wascreated, relative to the time the loggingmodule was loaded. |
| thread | %(thread)d | Thread ID (if available). |
| threadName | %(threadName)s | Thread name (if available). |
Changed in version 2.5: funcName was added.
Changed in version 2.6: processName was added.
LoggerAdapter instances are used to conveniently pass contextualinformation into logging calls. For a usage example , see the section onadding contextual information to your logging output.
New in version 2.6.
Returns an instance of LoggerAdapter initialized with anunderlying Logger instance and a dict-like object.
Modifies the message and/or keyword arguments passed to a logging call inorder to insert contextual information. This implementation takes the objectpassed as extra to the constructor and adds it to kwargs using key‘extra’. The return value is a (msg, kwargs) tuple which has the(possibly modified) versions of the arguments passed in.
In addition to the above, LoggerAdapter supports the followingmethods of Logger, i.e. debug(), info(), warning(),error(), exception(), critical(), log(),isEnabledFor(), getEffectiveLevel(), setLevel(),hasHandlers(). These methods have the same signatures as theircounterparts in Logger, so you can use the two types of instancesinterchangeably.
Changed in version 2.7: The isEnabledFor() method was added to LoggerAdapter. Thismethod delegates to the underlying logger.
The logging module is intended to be thread-safe without any special workneeding to be done by its clients. It achieves this though using threadinglocks; there is one lock to serialize access to the module’s shared data, andeach handler also creates a lock to serialize access to its underlying I/O.
If you are implementing asynchronous signal handlers using the signalmodule, you may not be able to use logging from within such handlers. This isbecause lock implementations in the threading module are not alwaysre-entrant, and so cannot be invoked from such signal handlers.
In addition to the classes described above, there are a number of module- levelfunctions.
Return a logger with the specified name or, if no name is specified, return alogger which is the root logger of the hierarchy. If specified, the name istypically a dot-separated hierarchical name like “a”, “a.b” or “a.b.c.d”.Choice of these names is entirely up to the developer who is using logging.
All calls to this function with a given name return the same logger instance.This means that logger instances never need to be passed between different partsof an application.
Return either the standard Logger class, or the last class passed tosetLoggerClass(). This function may be called from within a new classdefinition, to ensure that installing a customised Logger class willnot undo customisations already applied by other code. For example:
class MyLogger(logging.getLoggerClass()): # ... override behaviour hereLogs a message with level DEBUG on the root logger. The msg is themessage format string, and the args are the arguments which are merged intomsg using the string formatting operator. (Note that this means that you canuse keywords in the format string, together with a single dictionary argument.)
There are two keyword arguments in kwargs which are inspected: exc_infowhich, if it does not evaluate as false, causes exception information to beadded to the logging message. If an exception tuple (in the format returned bysys.exc_info()) is provided, it is used; otherwise, sys.exc_info()is called to get the exception information.
The other optional keyword argument is extra which can be used to pass adictionary which is used to populate the __dict__ of the LogRecord created forthe logging event with user-defined attributes. These custom attributes can thenbe used as you like. For example, they could be incorporated into loggedmessages. For example:
FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"logging.basicConfig(format=FORMAT)d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}logging.warning("Protocol problem: %s", "connection reset", extra=d)would print something like:
2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection resetThe keys in the dictionary passed in extra should not clash with the keys usedby the logging system. (See the Formatter documentation for moreinformation on which keys are used by the logging system.)
If you choose to use these attributes in logged messages, you need to exercisesome care. In the above example, for instance, the Formatter has beenset up with a format string which expects ‘clientip’ and ‘user’ in the attributedictionary of the LogRecord. If these are missing, the message will not belogged because a string formatting exception will occur. So in this case, youalways need to pass the extra dictionary with these keys.
While this might be annoying, this feature is intended for use in specializedcircumstances, such as multi-threaded servers where the same code executes inmany contexts, and interesting conditions which arise are dependent on thiscontext (such as remote client IP address and authenticated user name, in theabove example). In such circumstances, it is likely that specializedFormatters would be used with particular Handlers.
Changed in version 2.5: extra was added.
Logs a message with level INFO on the root logger. The arguments areinterpreted as for debug().
Logs a message with level WARNING on the root logger. The arguments areinterpreted as for debug().
Logs a message with level ERROR on the root logger. The arguments areinterpreted as for debug().
Logs a message with level CRITICAL on the root logger. The argumentsare interpreted as for debug().
Logs a message with level ERROR on the root logger. The arguments areinterpreted as for debug(). Exception info is added to the loggingmessage. This function should only be called from an exception handler.
Logs a message with level level on the root logger. The other arguments areinterpreted as for debug().
PLEASE NOTE: The above module-level functions which delegate to the rootlogger should not be used in threads, in versions of Python earlier than2.7.1 and 3.2, unless at least one handler has been added to the rootlogger before the threads are started. These convenience functions callbasicConfig() to ensure that at least one handler is available; inearlier versions of Python, this can (under rare circumstances) lead tohandlers being added multiple times to the root logger, which can in turnlead to multiple messages for the same event.
Provides an overriding level lvl for all loggers which takes precedence overthe logger’s own level. When the need arises to temporarily throttle loggingoutput down across the whole application, this function can be useful. Itseffect is to disable all logging calls of severity lvl and below, so thatif you call it with a value of INFO, then all INFO and DEBUG events would bediscarded, whereas those of severity WARNING and above would be processedaccording to the logger’s effective level. To undo the effect of a call tologging.disable(lvl), call logging.disable(logging.NOTSET).
Associates level lvl with text levelName in an internal dictionary, which isused to map numeric levels to a textual representation, for example when aFormatter formats a message. This function can also be used to defineyour own levels. The only constraints are that all levels used must beregistered using this function, levels should be positive integers and theyshould increase in increasing order of severity.
NOTE: If you are thinking of defining your own levels, please see the sectionon Custom Levels.
Returns the textual representation of logging level lvl. If the level is oneof the predefined levels CRITICAL, ERROR, WARNING,INFO or DEBUG then you get the corresponding string. If youhave associated levels with names using addLevelName() then the name youhave associated with lvl is returned. If a numeric value corresponding to oneof the defined levels is passed in, the corresponding string representation isreturned. Otherwise, the string “Level %s” % lvl is returned.
Creates and returns a new LogRecord instance whose attributes aredefined by attrdict. This function is useful for taking a pickledLogRecord attribute dictionary, sent over a socket, and reconstitutingit as a LogRecord instance at the receiving end.
Does basic configuration for the logging system by creating aStreamHandler with a default Formatter and adding it to theroot logger. The functions debug(), info(), warning(),error() and critical() will call basicConfig() automaticallyif no handlers are defined for the root logger.
This function does nothing if the root logger already has handlersconfigured for it.
Changed in version 2.4: Formerly, basicConfig() did not take any keyword arguments.
PLEASE NOTE: This function should be called from the main threadbefore other threads are started. In versions of Python prior to2.7.1 and 3.2, if this function is called from multiple threads,it is possible (in rare circumstances) that a handler will be addedto the root logger more than once, leading to unexpected resultssuch as messages being duplicated in the log.
The following keyword arguments are supported.
| Format | Description |
|---|---|
| filename | Specifies that a FileHandler be created,using the specified filename, rather than aStreamHandler. |
| filemode | Specifies the mode to open the file, iffilename is specified (if filemode isunspecified, it defaults to ‘a’). |
| format | Use the specified format string for thehandler. |
| datefmt | Use the specified date/time format. |
| level | Set the root logger level to the specifiedlevel. |
| stream | Use the specified stream to initialize theStreamHandler. Note that this argument isincompatible with ‘filename’ - if both arepresent, ‘stream’ is ignored. |
Informs the logging system to perform an orderly shutdown by flushing andclosing all handlers. This should be called at application exit and nofurther use of the logging system should be made after this call.
Tells the logging system to use the class klass when instantiating a logger.The class should define __init__() such that only a name argument isrequired, and the __init__() should call Logger.__init__(). Thisfunction is typically called before any loggers are instantiated by applicationswhich need to use custom logger behavior.
The captureWarnings() function can be used to integrate loggingwith the warnings module.
This function is used to turn the capture of warnings by logging on andoff.
If capture is True, warnings issued by the warnings module willbe redirected to the logging system. Specifically, a warning will beformatted using warnings.formatwarning() and the resulting stringlogged to a logger named 'py.warnings' with a severity of WARNING.
If capture is False, the redirection of warnings to the logging systemwill stop, and warnings will be redirected to their original destinations(i.e. those in effect before captureWarnings(True) was called).
See also
联系客服
