\section{\module{logging} --- Logging facility for Python} \declaremodule{standard}{logging} % These apply to all modules, and may be given more than once: \moduleauthor{Vinay Sajip}{vinay_sajip@red-dove.com}\sectionauthor{Vinay Sajip}{vinay_sajip@red-dove.com} \modulesynopsis{Logging module for Python based on \pep{282}.} \indexii{Errors}{logging} \versionadded{2.3}This module defines functions and classes which implement a flexibleerror logging system for applications. Logging is performed by calling methods on instances of the\class{Logger} class (hereafter called \dfn{loggers}). Each instance has aname, and they are conceptually arranged in a name space hierarchyusing dots (periods) as separators. For example, a logger named"scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf".Logger names can be anything you want, and indicate the area of anapplication in which a logged message originates. Logged messages also have levels of importance associated with them.The default levels provided are \constant{DEBUG}, \constant{INFO},\constant{WARNING}, \constant{ERROR} and \constant{CRITICAL}. As aconvenience, you indicate the importance of a logged message by callingan appropriate method of \class{Logger}. The methods are\method{debug()}, \method{info()}, \method{warning()}, \method{error()} and\method{critical()}, which mirror the default levels. You are notconstrained to use these levels: you can specify your own and use amore general \class{Logger} method, \method{log()}, which takes anexplicit level argument. The numeric values of logging levels are given in the following table. Theseare primarily of interest if you want to define your own levels, and needthem to have specific values relative to the predefined levels. If youdefine a level with the same numeric value, it overwrites the predefinedvalue; the predefined name is lost. \begin{tableii}{l|l}{code}{Level}{Numeric value} \lineii{CRITICAL}{50} \lineii{ERROR}{40} \lineii{WARNING}{30} \lineii{INFO}{20} \lineii{DEBUG}{10} \lineii{NOTSET}{0}\end{tableii} Levels can also be associated with loggers, being set either by thedeveloper or through loading a saved logging configuration. When alogging method is called on a logger, the logger compares its ownlevel with the level associated with the method call. If the logger'slevel is higher than the method call's, no logging message is actuallygenerated. This is the basic mechanism controlling the verbosity oflogging output. Logging messages are encoded as instances of the \class{LogRecord} class.When a logger decides to actually log an event, a \class{LogRecord}instance is created from the logging message. Logging messages are subjected to a dispatch mechanism through theuse of \dfn{handlers}, which are instances of subclasses of the\class{Handler} class. Handlers are responsible for ensuring that a loggedmessage (in the form of a \class{LogRecord}) ends up in a particularlocation (or set of locations) which is useful for the target audience forthat message (such as end users, support desk staff, system administrators,developers). Handlers are passed \class{LogRecord} instances intended forparticular destinations. Each logger can have zero, one or more handlersassociated with it (via the \method{addHandler()} method of \class{Logger}).In addition to any handlers directly associated with a logger,\emph{all handlers associated with all ancestors of the logger} arecalled to dispatch the message. Just as for loggers, handlers can have levels associated with them.A handler's level acts as a filter in the same way as a logger's level does.If a handler decides to actually dispatch an event, the \method{emit()} methodis used to send the message to its destination. Most user-defined subclassesof \class{Handler} will need to override this \method{emit()}. In addition to the base \class{Handler} class, many useful subclassesare provided: \begin{enumerate} \item \class{StreamHandler} instances send error messages tostreams (file-like objects). \item \class{FileHandler} instances send error messages to diskfiles. \item \class{BaseRotatingHandler} is the base class for handlers thatrotate log files at a certain point. It is not meant to be instantiateddirectly. Instead, use \class{RotatingFileHandler} or\class{TimedRotatingFileHandler}. \item \class{RotatingFileHandler} instances send error messages to diskfiles, with support for maximum log file sizes and log file rotation. \item \class{TimedRotatingFileHandler} instances send error messages todisk files rotating the log file at certain timed intervals. \item \class{SocketHandler} instances send error messages toTCP/IP sockets. \item \class{DatagramHandler} instances send error messages to UDPsockets. \item \class{SMTPHandler} instances send error messages to adesignated email address. \item \class{SysLogHandler} instances send error messages to a\UNIX{} syslog daemon, possibly on a remote machine. \item \class{NTEventLogHandler} instances send error messages to aWindows NT/2000/XP event log. \item \class{MemoryHandler} instances send error messages to abuffer in memory, which is flushed whenever specific criteria aremet. \item \class{HTTPHandler} instances send error messages to anHTTP server using either \samp{GET} or \samp{POST} semantics. \end{enumerate} The \class{StreamHandler} and \class{FileHandler} classes are definedin the core logging package. The other handlers are defined in a sub-module, \module{logging.handlers}. (There is also another sub-module,\module{logging.config}, for configuration functionality.) Logged messages are formatted for presentation through instances of the\class{Formatter} class. They are initialized with a format stringsuitable for use with the \% operator and a dictionary. For formatting multiple messages in a batch, instances of\class{BufferingFormatter} can be used. In addition to the format string(which is applied to each message in the batch), there is provision forheader and trailer format strings. When filtering based on logger level and/or handler level is not enough,instances of \class{Filter} can be added to both \class{Logger} and\class{Handler} instances (through their \method{addFilter()} method).Before deciding to process a message further, both loggers and handlersconsult all their filters for permission. If any filter returns a falsevalue, the message is not processed further. The basic \class{Filter} functionality allows filtering by specific loggername. If this feature is used, messages sent to the named logger and itschildren are allowed through the filter, and all others dropped. In addition to the classes described above, there are a number of module-level functions. \begin{funcdesc}{getLogger}{\optional{name}}Return a logger with the specified name or, if no name is specified, returna logger which is the root logger of the hierarchy. If specified, the nameis typically a dot-separated hierarchical name like \var{"a"}, \var{"a.b"}or \var{"a.b.c.d"}. Choice of these names is entirely up to the developerwho 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 differentparts of an application.\end{funcdesc} \begin{funcdesc}{getLoggerClass}{}Return either the standard \class{Logger} class, or the last class passed to\function{setLoggerClass()}. This function may be called from within a newclass definition, to ensure that installing a customised \class{Logger} classwill not undo customisations already applied by other code. For example: \begin{verbatim} class MyLogger(logging.getLoggerClass()): # ... override behaviour here\end{verbatim} \end{funcdesc} \begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{DEBUG} on the root logger.The \var{msg} is the message format string, and the \var{args} are thearguments which are merged into \var{msg} using the string formattingoperator. (Note that this means that you can use keywords in theformat string, together with a single dictionary argument.) There are two keyword arguments in \var{kwargs} which are inspected:\var{exc_info} which, if it does not evaluate as false, causes exceptioninformation to be added to the logging message. If an exception tuple (in theformat returned by \function{sys.exc_info()}) is provided, it is used;otherwise, \function{sys.exc_info()} is called to get the exceptioninformation. The other optional keyword argument is \var{extra} which can be used to passa dictionary which is used to populate the __dict__ of the LogRecord createdfor the logging event with user-defined attributes. These custom attributescan then be used as you like. For example, they could be incorporated intologged messages. For example: \begin{verbatim} FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" logging.basicConfig(format=FORMAT) dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' } logging.warning("Protocol problem: %s", "connection reset", extra=d)\end{verbatim} would print something like\begin{verbatim}2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset\end{verbatim} The keys in the dictionary passed in \var{extra} should not clash with the keysused by the logging system. (See the \class{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 \class{Formatter} has beenset up with a format string which expects 'clientip' and 'user' in theattribute dictionary of the LogRecord. If these are missing, the message willnot be logged because a string formatting exception will occur. So in thiscase, you always need to pass the \var{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 executesin many 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 specialized\class{Formatter}s would be used with particular \class{Handler}s. \versionchanged[\var{extra} was added]{2.5} \end{funcdesc} \begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{INFO} on the root logger.The arguments are interpreted as for \function{debug()}.\end{funcdesc} \begin{funcdesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{WARNING} on the root logger.The arguments are interpreted as for \function{debug()}.\end{funcdesc} \begin{funcdesc}{error}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{ERROR} on the root logger.The arguments are interpreted as for \function{debug()}.\end{funcdesc} \begin{funcdesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{CRITICAL} on the root logger.The arguments are interpreted as for \function{debug()}.\end{funcdesc} \begin{funcdesc}{exception}{msg\optional{, *args}}Logs a message with level \constant{ERROR} on the root logger.The arguments are interpreted as for \function{debug()}. Exception infois added to the logging message. This function should only be calledfrom an exception handler.\end{funcdesc} \begin{funcdesc}{log}{level, msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \var{level} on the root logger.The other arguments are interpreted as for \function{debug()}.\end{funcdesc} \begin{funcdesc}{disable}{lvl}Provides an overriding level \var{lvl} for all loggers which takesprecedence over the logger's own level. When the need arises totemporarily throttle logging output down across the whole application,this function can be useful.\end{funcdesc} \begin{funcdesc}{addLevelName}{lvl, levelName}Associates level \var{lvl} with text \var{levelName} in an internaldictionary, which is used to map numeric levels to a textualrepresentation, for example when a \class{Formatter} formats a message.This function can also be used to define your own levels. The onlyconstraints are that all levels used must be registered using thisfunction, levels should be positive integers and they should increasein increasing order of severity.\end{funcdesc} \begin{funcdesc}{getLevelName}{lvl}Returns the textual representation of logging level \var{lvl}. If thelevel is one of the predefined levels \constant{CRITICAL},\constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG}then you get the corresponding string. If you have associated levelswith names using \function{addLevelName()} then the name you have associatedwith \var{lvl} is returned. If a numeric value corresponding to one of thedefined levels is passed in, the corresponding string representation isreturned. Otherwise, the string "Level \%s" \% lvl is returned.\end{funcdesc} \begin{funcdesc}{makeLogRecord}{attrdict}Creates and returns a new \class{LogRecord} instance whose attributes aredefined by \var{attrdict}. This function is useful for taking a pickled\class{LogRecord} attribute dictionary, sent over a socket, and reconstitutingit as a \class{LogRecord} instance at the receiving end.\end{funcdesc} \begin{funcdesc}{basicConfig}{\optional{**kwargs}}Does basic configuration for the logging system by creating a\class{StreamHandler} with a default \class{Formatter} and adding it tothe root logger. The functions \function{debug()}, \function{info()},\function{warning()}, \function{error()} and \function{critical()} will call\function{basicConfig()} automatically if no handlers are defined for theroot logger. \versionchanged[Formerly, \function{basicConfig} did not take any keywordarguments]{2.4} The following keyword arguments are supported. \begin{tableii}{l|l}{code}{Format}{Description}\lineii{filename}{Specifies that a FileHandler be created, using thespecified filename, rather than a StreamHandler.}\lineii{filemode}{Specifies the mode to open the file, if filename isspecified (if filemode is unspecified, it defaults to 'a').}\lineii{format}{Use the specified format string for the handler.}\lineii{datefmt}{Use the specified date/time format.}\lineii{level}{Set the root logger level to the specified level.}\lineii{stream}{Use the specified stream to initialize the StreamHandler.Note that this argument is incompatible with 'filename' - if bothare present, 'stream' is ignored.}\end{tableii} \end{funcdesc} \begin{funcdesc}{shutdown}{}Informs the logging system to perform an orderly shutdown by flushing andclosing all handlers.\end{funcdesc} \begin{funcdesc}{setLoggerClass}{klass}Tells the logging system to use the class \var{klass} when instantiating alogger. The class should define \method{__init__()} such that only a nameargument is required, and the \method{__init__()} should call\method{Logger.__init__()}. This function is typically called before anyloggers are instantiated by applications which need to use custom loggerbehavior.\end{funcdesc} \begin{seealso} \seepep{282}{A Logging System} {The proposal which described this feature for inclusion in the Python standard library.} \seelink{http://www.red-dove.com/python_logging.html} {Original Python \module{logging} package} {This is the original source for the \module{logging} package. The version of the package available from this site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x, which do not include the \module{logging} package in the standard library.}\end{seealso} \subsection{Logger Objects} Loggers have the following attributes and methods. Note that Loggers arenever instantiated directly, but always through the module-level function\function{logging.getLogger(name)}. \begin{datadesc}{propagate}If this evaluates to false, logging messages are not passed by thislogger or by child loggers to higher level (ancestor) loggers. Theconstructor sets this attribute to 1.\end{datadesc} \begin{methoddesc}{setLevel}{lvl}Sets the threshold for this logger to \var{lvl}. Logging messageswhich are less severe than \var{lvl} will be ignored. When a logger iscreated, the level is set to \constant{NOTSET} (which causes all messagesto be processed when the logger is the root logger, or delegation to theparent when the logger is a non-root logger). Note that the root loggeris created with level \constant{WARNING}. The term "delegation to the parent" means that if a logger has a levelof NOTSET, its chain of ancestor loggers is traversed until either anancestor with a level other than NOTSET is found, or the root isreached. If an ancestor is found with a level other than NOTSET, then thatancestor's level is treated as the effective level of the logger wherethe ancestor search began, and is used to determine how a loggingevent is handled. If the root is reached, and it has a level of NOTSET, then allmessages will be processed. Otherwise, the root's level will be usedas the effective level.\end{methoddesc} \begin{methoddesc}{isEnabledFor}{lvl}Indicates if a message of severity \var{lvl} would be processed bythis logger. This method checks first the module-level level set by\function{logging.disable(lvl)} and then the logger's effective level asdetermined by \method{getEffectiveLevel()}.\end{methoddesc} \begin{methoddesc}{getEffectiveLevel}{}Indicates the effective level for this logger. If a value other than\constant{NOTSET} has been set using \method{setLevel()}, it is returned.Otherwise, the hierarchy is traversed towards the root until a valueother than \constant{NOTSET} is found, and that value is returned.\end{methoddesc} \begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{DEBUG} on this logger.The \var{msg} is the message format string, and the \var{args} are thearguments which are merged into \var{msg} using the string formattingoperator. (Note that this means that you can use keywords in theformat string, together with a single dictionary argument.) There are two keyword arguments in \var{kwargs} which are inspected:\var{exc_info} which, if it does not evaluate as false, causes exceptioninformation to be added to the logging message. If an exception tuple (in theformat returned by \function{sys.exc_info()}) is provided, it is used;otherwise, \function{sys.exc_info()} is called to get the exceptioninformation. The other optional keyword argument is \var{extra} which can be used to passa dictionary which is used to populate the __dict__ of the LogRecord createdfor the logging event with user-defined attributes. These custom attributescan then be used as you like. For example, they could be incorporated intologged messages. For example: \begin{verbatim} FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" logging.basicConfig(format=FORMAT) dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' } logger = logging.getLogger("tcpserver") logger.warning("Protocol problem: %s", "connection reset", extra=d)\end{verbatim} would print something like\begin{verbatim}2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset\end{verbatim} The keys in the dictionary passed in \var{extra} should not clash with the keysused by the logging system. (See the \class{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 \class{Formatter} has beenset up with a format string which expects 'clientip' and 'user' in theattribute dictionary of the LogRecord. If these are missing, the message willnot be logged because a string formatting exception will occur. So in thiscase, you always need to pass the \var{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 executesin many 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 specialized\class{Formatter}s would be used with particular \class{Handler}s. \versionchanged[\var{extra} was added]{2.5} \end{methoddesc} \begin{methoddesc}{info}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{INFO} on this logger.The arguments are interpreted as for \method{debug()}.\end{methoddesc} \begin{methoddesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{WARNING} on this logger.The arguments are interpreted as for \method{debug()}.\end{methoddesc} \begin{methoddesc}{error}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{ERROR} on this logger.The arguments are interpreted as for \method{debug()}.\end{methoddesc} \begin{methoddesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}Logs a message with level \constant{CRITICAL} on this logger.The arguments are interpreted as for \method{debug()}.\end{methoddesc} \begin{methoddesc}{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}Logs a message with integer level \var{lvl} on this logger.The other arguments are interpreted as for \method{debug()}.\end{methoddesc} \begin{methoddesc}{exception}{msg\optional{, *args}}Logs a message with level \constant{ERROR} on this logger.The arguments are interpreted as for \method{debug()}. Exception infois added to the logging message. This method should only be calledfrom an exception handler.\end{methoddesc} \begin{methoddesc}{addFilter}{filt}Adds the specified filter \var{filt} to this logger.\end{methoddesc} Lines 1–500 of 1729. Load more
\section{\module{logging} --- Logging facility for Python} \declaremodule{standard}{logging} % These apply to all modules, and may be given more than once: \moduleauthor{Vinay Sajip}{vinay_sajip@red-dove.com} \sectionauthor{Vinay Sajip}{vinay_sajip@red-dove.com} \modulesynopsis{Logging module for Python based on \pep{282}.} \indexii{Errors}{logging} \versionadded{2.3} This module defines functions and classes which implement a flexible error logging system for applications. Logging is performed by calling methods on instances of the \class{Logger} class (hereafter called \dfn{loggers}). Each instance has a name, and they are conceptually arranged in a name space hierarchy using dots (periods) as separators. For example, a logger named "scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want, and indicate the area of an application in which a logged message originates. Logged messages also have levels of importance associated with them. The default levels provided are \constant{DEBUG}, \constant{INFO}, \constant{WARNING}, \constant{ERROR} and \constant{CRITICAL}. As a convenience, you indicate the importance of a logged message by calling an appropriate method of \class{Logger}. The methods are \method{debug()}, \method{info()}, \method{warning()}, \method{error()} and \method{critical()}, which mirror the default levels. You are not constrained to use these levels: you can specify your own and use a more general \class{Logger} method, \method{log()}, which takes an explicit level argument. The numeric values of logging levels are given in the following table. These are primarily of interest if you want to define your own levels, and need them to have specific values relative to the predefined levels. If you define a level with the same numeric value, it overwrites the predefined value; the predefined name is lost. \begin{tableii}{l|l}{code}{Level}{Numeric value} \lineii{CRITICAL}{50} \lineii{ERROR}{40} \lineii{WARNING}{30} \lineii{INFO}{20} \lineii{DEBUG}{10} \lineii{NOTSET}{0} \end{tableii} Levels can also be associated with loggers, being set either by the developer or through loading a saved logging configuration. When a logging method is called on a logger, the logger compares its own level with the level associated with the method call. If the logger's level is higher than the method call's, no logging message is actually generated. This is the basic mechanism controlling the verbosity of logging output. Logging messages are encoded as instances of the \class{LogRecord} class. When a logger decides to actually log an event, a \class{LogRecord} instance is created from the logging message. Logging messages are subjected to a dispatch mechanism through the use of \dfn{handlers}, which are instances of subclasses of the \class{Handler} class. Handlers are responsible for ensuring that a logged message (in the form of a \class{LogRecord}) ends up in a particular location (or set of locations) which is useful for the target audience for that message (such as end users, support desk staff, system administrators, developers). Handlers are passed \class{LogRecord} instances intended for particular destinations. Each logger can have zero, one or more handlers associated with it (via the \method{addHandler()} method of \class{Logger}). In addition to any handlers directly associated with a logger, \emph{all handlers associated with all ancestors of the logger} are called to dispatch the message. Just as for loggers, handlers can have levels associated with them. A handler's level acts as a filter in the same way as a logger's level does. If a handler decides to actually dispatch an event, the \method{emit()} method is used to send the message to its destination. Most user-defined subclasses of \class{Handler} will need to override this \method{emit()}. In addition to the base \class{Handler} class, many useful subclasses are provided: \begin{enumerate} \item \class{StreamHandler} instances send error messages to streams (file-like objects). \item \class{FileHandler} instances send error messages to disk files. \item \class{BaseRotatingHandler} is the base class for handlers that rotate log files at a certain point. It is not meant to be instantiated directly. Instead, use \class{RotatingFileHandler} or \class{TimedRotatingFileHandler}. \item \class{RotatingFileHandler} instances send error messages to disk files, with support for maximum log file sizes and log file rotation. \item \class{TimedRotatingFileHandler} instances send error messages to disk files rotating the log file at certain timed intervals. \item \class{SocketHandler} instances send error messages to TCP/IP sockets. \item \class{DatagramHandler} instances send error messages to UDP sockets. \item \class{SMTPHandler} instances send error messages to a designated email address. \item \class{SysLogHandler} instances send error messages to a \UNIX{} syslog daemon, possibly on a remote machine. \item \class{NTEventLogHandler} instances send error messages to a Windows NT/2000/XP event log. \item \class{MemoryHandler} instances send error messages to a buffer in memory, which is flushed whenever specific criteria are met. \item \class{HTTPHandler} instances send error messages to an HTTP server using either \samp{GET} or \samp{POST} semantics. \end{enumerate} The \class{StreamHandler} and \class{FileHandler} classes are defined in the core logging package. The other handlers are defined in a sub- module, \module{logging.handlers}. (There is also another sub-module, \module{logging.config}, for configuration functionality.) Logged messages are formatted for presentation through instances of the \class{Formatter} class. They are initialized with a format string suitable for use with the \% operator and a dictionary. For formatting multiple messages in a batch, instances of \class{BufferingFormatter} can be used. In addition to the format string (which is applied to each message in the batch), there is provision for header and trailer format strings. When filtering based on logger level and/or handler level is not enough, instances of \class{Filter} can be added to both \class{Logger} and \class{Handler} instances (through their \method{addFilter()} method). Before deciding to process a message further, both loggers and handlers consult all their filters for permission. If any filter returns a false value, the message is not processed further. The basic \class{Filter} functionality allows filtering by specific logger name. If this feature is used, messages sent to the named logger and its children are allowed through the filter, and all others dropped. In addition to the classes described above, there are a number of module- level functions. \begin{funcdesc}{getLogger}{\optional{name}} Return a logger with the specified name or, if no name is specified, return a logger which is the root logger of the hierarchy. If specified, the name is typically a dot-separated hierarchical name like \var{"a"}, \var{"a.b"} or \var{"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 parts of an application. \end{funcdesc} \begin{funcdesc}{getLoggerClass}{} Return either the standard \class{Logger} class, or the last class passed to \function{setLoggerClass()}. This function may be called from within a new class definition, to ensure that installing a customised \class{Logger} class will not undo customisations already applied by other code. For example: \begin{verbatim} class MyLogger(logging.getLoggerClass()): # ... override behaviour here \end{verbatim} \end{funcdesc} \begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{DEBUG} on the root logger. The \var{msg} is the message format string, and the \var{args} are the arguments which are merged into \var{msg} using the string formatting operator. (Note that this means that you can use keywords in the format string, together with a single dictionary argument.) There are two keyword arguments in \var{kwargs} which are inspected: \var{exc_info} which, if it does not evaluate as false, causes exception information to be added to the logging message. If an exception tuple (in the format returned by \function{sys.exc_info()}) is provided, it is used; otherwise, \function{sys.exc_info()} is called to get the exception information. The other optional keyword argument is \var{extra} which can be used to pass a dictionary which is used to populate the __dict__ of the LogRecord created for the logging event with user-defined attributes. These custom attributes can then be used as you like. For example, they could be incorporated into logged messages. For example: \begin{verbatim} FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" logging.basicConfig(format=FORMAT) dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' } logging.warning("Protocol problem: %s", "connection reset", extra=d) \end{verbatim} would print something like \begin{verbatim} 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset \end{verbatim} The keys in the dictionary passed in \var{extra} should not clash with the keys used by the logging system. (See the \class{Formatter} documentation for more information on which keys are used by the logging system.) If you choose to use these attributes in logged messages, you need to exercise some care. In the above example, for instance, the \class{Formatter} has been set up with a format string which expects 'clientip' and 'user' in the attribute dictionary of the LogRecord. If these are missing, the message will not be logged because a string formatting exception will occur. So in this case, you always need to pass the \var{extra} dictionary with these keys. While this might be annoying, this feature is intended for use in specialized circumstances, such as multi-threaded servers where the same code executes in many contexts, and interesting conditions which arise are dependent on this context (such as remote client IP address and authenticated user name, in the above example). In such circumstances, it is likely that specialized \class{Formatter}s would be used with particular \class{Handler}s. \versionchanged[\var{extra} was added]{2.5} \end{funcdesc} \begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{INFO} on the root logger. The arguments are interpreted as for \function{debug()}. \end{funcdesc} \begin{funcdesc}{warning}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{WARNING} on the root logger. The arguments are interpreted as for \function{debug()}. \end{funcdesc} \begin{funcdesc}{error}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{ERROR} on the root logger. The arguments are interpreted as for \function{debug()}. \end{funcdesc} \begin{funcdesc}{critical}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{CRITICAL} on the root logger. The arguments are interpreted as for \function{debug()}. \end{funcdesc} \begin{funcdesc}{exception}{msg\optional{, *args}} Logs a message with level \constant{ERROR} on the root logger. The arguments are interpreted as for \function{debug()}. Exception info is added to the logging message. This function should only be called from an exception handler. \end{funcdesc} \begin{funcdesc}{log}{level, msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \var{level} on the root logger. The other arguments are interpreted as for \function{debug()}. \end{funcdesc} \begin{funcdesc}{disable}{lvl} Provides an overriding level \var{lvl} for all loggers which takes precedence over the logger's own level. When the need arises to temporarily throttle logging output down across the whole application, this function can be useful. \end{funcdesc} \begin{funcdesc}{addLevelName}{lvl, levelName} Associates level \var{lvl} with text \var{levelName} in an internal dictionary, which is used to map numeric levels to a textual representation, for example when a \class{Formatter} formats a message. This function can also be used to define your own levels. The only constraints are that all levels used must be registered using this function, levels should be positive integers and they should increase in increasing order of severity. \end{funcdesc} \begin{funcdesc}{getLevelName}{lvl} Returns the textual representation of logging level \var{lvl}. If the level is one of the predefined levels \constant{CRITICAL}, \constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG} then you get the corresponding string. If you have associated levels with names using \function{addLevelName()} then the name you have associated with \var{lvl} is returned. If a numeric value corresponding to one of the defined levels is passed in, the corresponding string representation is returned. Otherwise, the string "Level \%s" \% lvl is returned. \end{funcdesc} \begin{funcdesc}{makeLogRecord}{attrdict} Creates and returns a new \class{LogRecord} instance whose attributes are defined by \var{attrdict}. This function is useful for taking a pickled \class{LogRecord} attribute dictionary, sent over a socket, and reconstituting it as a \class{LogRecord} instance at the receiving end. \end{funcdesc} \begin{funcdesc}{basicConfig}{\optional{**kwargs}} Does basic configuration for the logging system by creating a \class{StreamHandler} with a default \class{Formatter} and adding it to the root logger. The functions \function{debug()}, \function{info()}, \function{warning()}, \function{error()} and \function{critical()} will call \function{basicConfig()} automatically if no handlers are defined for the root logger. \versionchanged[Formerly, \function{basicConfig} did not take any keyword arguments]{2.4} The following keyword arguments are supported. \begin{tableii}{l|l}{code}{Format}{Description} \lineii{filename}{Specifies that a FileHandler be created, using the specified filename, rather than a StreamHandler.} \lineii{filemode}{Specifies the mode to open the file, if filename is specified (if filemode is unspecified, it defaults to 'a').} \lineii{format}{Use the specified format string for the handler.} \lineii{datefmt}{Use the specified date/time format.} \lineii{level}{Set the root logger level to the specified level.} \lineii{stream}{Use the specified stream to initialize the StreamHandler. Note that this argument is incompatible with 'filename' - if both are present, 'stream' is ignored.} \end{tableii} \end{funcdesc} \begin{funcdesc}{shutdown}{} Informs the logging system to perform an orderly shutdown by flushing and closing all handlers. \end{funcdesc} \begin{funcdesc}{setLoggerClass}{klass} Tells the logging system to use the class \var{klass} when instantiating a logger. The class should define \method{__init__()} such that only a name argument is required, and the \method{__init__()} should call \method{Logger.__init__()}. This function is typically called before any loggers are instantiated by applications which need to use custom logger behavior. \end{funcdesc} \begin{seealso} \seepep{282}{A Logging System} {The proposal which described this feature for inclusion in the Python standard library.} \seelink{http://www.red-dove.com/python_logging.html} {Original Python \module{logging} package} {This is the original source for the \module{logging} package. The version of the package available from this site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x, which do not include the \module{logging} package in the standard library.} \end{seealso} \subsection{Logger Objects} Loggers have the following attributes and methods. Note that Loggers are never instantiated directly, but always through the module-level function \function{logging.getLogger(name)}. \begin{datadesc}{propagate} If this evaluates to false, logging messages are not passed by this logger or by child loggers to higher level (ancestor) loggers. The constructor sets this attribute to 1. \end{datadesc} \begin{methoddesc}{setLevel}{lvl} Sets the threshold for this logger to \var{lvl}. Logging messages which are less severe than \var{lvl} will be ignored. When a logger is created, the level is set to \constant{NOTSET} (which causes all messages to be processed when the logger is the root logger, or delegation to the parent when the logger is a non-root logger). Note that the root logger is created with level \constant{WARNING}. The term "delegation to the parent" means that if a logger has a level of NOTSET, its chain of ancestor loggers is traversed until either an ancestor with a 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's level is treated as the effective level of the logger where the ancestor search began, 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 be processed. Otherwise, the root's level will be used as the effective level. \end{methoddesc} \begin{methoddesc}{isEnabledFor}{lvl} Indicates if a message of severity \var{lvl} would be processed by this logger. This method checks first the module-level level set by \function{logging.disable(lvl)} and then the logger's effective level as determined by \method{getEffectiveLevel()}. \end{methoddesc} \begin{methoddesc}{getEffectiveLevel}{} Indicates the effective level for this logger. If a value other than \constant{NOTSET} has been set using \method{setLevel()}, it is returned. Otherwise, the hierarchy is traversed towards the root until a value other than \constant{NOTSET} is found, and that value is returned. \end{methoddesc} \begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{DEBUG} on this logger. The \var{msg} is the message format string, and the \var{args} are the arguments which are merged into \var{msg} using the string formatting operator. (Note that this means that you can use keywords in the format string, together with a single dictionary argument.) There are two keyword arguments in \var{kwargs} which are inspected: \var{exc_info} which, if it does not evaluate as false, causes exception information to be added to the logging message. If an exception tuple (in the format returned by \function{sys.exc_info()}) is provided, it is used; otherwise, \function{sys.exc_info()} is called to get the exception information. The other optional keyword argument is \var{extra} which can be used to pass a dictionary which is used to populate the __dict__ of the LogRecord created for the logging event with user-defined attributes. These custom attributes can then be used as you like. For example, they could be incorporated into logged messages. For example: \begin{verbatim} FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" logging.basicConfig(format=FORMAT) dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' } logger = logging.getLogger("tcpserver") logger.warning("Protocol problem: %s", "connection reset", extra=d) \end{verbatim} would print something like \begin{verbatim} 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset \end{verbatim} The keys in the dictionary passed in \var{extra} should not clash with the keys used by the logging system. (See the \class{Formatter} documentation for more information on which keys are used by the logging system.) If you choose to use these attributes in logged messages, you need to exercise some care. In the above example, for instance, the \class{Formatter} has been set up with a format string which expects 'clientip' and 'user' in the attribute dictionary of the LogRecord. If these are missing, the message will not be logged because a string formatting exception will occur. So in this case, you always need to pass the \var{extra} dictionary with these keys. While this might be annoying, this feature is intended for use in specialized circumstances, such as multi-threaded servers where the same code executes in many contexts, and interesting conditions which arise are dependent on this context (such as remote client IP address and authenticated user name, in the above example). In such circumstances, it is likely that specialized \class{Formatter}s would be used with particular \class{Handler}s. \versionchanged[\var{extra} was added]{2.5} \end{methoddesc} \begin{methoddesc}{info}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{INFO} on this logger. The arguments are interpreted as for \method{debug()}. \end{methoddesc} \begin{methoddesc}{warning}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{WARNING} on this logger. The arguments are interpreted as for \method{debug()}. \end{methoddesc} \begin{methoddesc}{error}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{ERROR} on this logger. The arguments are interpreted as for \method{debug()}. \end{methoddesc} \begin{methoddesc}{critical}{msg\optional{, *args\optional{, **kwargs}}} Logs a message with level \constant{CRITICAL} on this logger. The arguments are interpreted as for \method{debug()}. \end{methoddesc} \begin{methoddesc}{log}{lvl, msg\optional{, *args\optional{, **kwargs}}} Logs a message with integer level \var{lvl} on this logger. The other arguments are interpreted as for \method{debug()}. \end{methoddesc} \begin{methoddesc}{exception}{msg\optional{, *args}} Logs a message with level \constant{ERROR} on this logger. The arguments are interpreted as for \method{debug()}. Exception info is added to the logging message. This method should only be called from an exception handler. \end{methoddesc} \begin{methoddesc}{addFilter}{filt} Adds the specified filter \var{filt} to this logger. \end{methoddesc}