1179 lines
46 KiB
TeX
1179 lines
46 KiB
TeX
\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.
|
|
|
|
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, an \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{RotatingFileHandler} instances send error messages to disk
|
|
files, with support for maximum log file sizes and log file rotation.
|
|
|
|
\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.
|
|
|
|
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}{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}. The only keyword argument in
|
|
\var{kwargs} which is inspected is \var{exc_info} which, if it does not
|
|
evaluate as false, causes exception information (via a call to
|
|
\function{sys.exc_info()}) to be added to the logging message.
|
|
\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}{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. 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}{}
|
|
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.
|
|
\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.}
|
|
\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 in the root logger, or delegation to the parent in non-root
|
|
loggers).
|
|
\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}. The only keyword argument in
|
|
\var{kwargs} which is inspected is \var{exc_info} which, if it does not
|
|
evaluate as false, causes exception information (via a call to
|
|
\function{sys.exc_info()}) to be added to the logging message.
|
|
\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 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}
|
|
|
|
\begin{methoddesc}{removeFilter}{filt}
|
|
Removes the specified filter \var{filt} from this logger.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{filter}{record}
|
|
Applies this logger's filters to the record and returns a true value if
|
|
the record is to be processed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{addHandler}{hdlr}
|
|
Adds the specified handler \var{hdlr} to this logger.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{removeHandler}{hdlr}
|
|
Removes the specified handler \var{hdlr} from this logger.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{findCaller}{}
|
|
Finds the caller's source filename and line number. Returns the filename
|
|
and line number as a 2-element tuple.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle}{record}
|
|
Handles a record by passing it to all handlers associated with this logger
|
|
and its ancestors (until a false value of \var{propagate} is found).
|
|
This method is used for unpickled records received from a socket, as well
|
|
as those created locally. Logger-level filtering is applied using
|
|
\method{filter()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info}
|
|
This is a factory method which can be overridden in subclasses to create
|
|
specialized \class{LogRecord} instances.
|
|
\end{methoddesc}
|
|
|
|
\subsection{Handler Objects}
|
|
|
|
Handlers have the following attributes and methods. Note that
|
|
\class{Handler} is never instantiated directly; this class acts as a
|
|
base for more useful subclasses. However, the \method{__init__()}
|
|
method in subclasses needs to call \method{Handler.__init__()}.
|
|
|
|
\begin{methoddesc}{__init__}{level=\constant{NOTSET}}
|
|
Initializes the \class{Handler} instance by setting its level, setting
|
|
the list of filters to the empty list and creating a lock (using
|
|
\method{createLock()}) for serializing access to an I/O mechanism.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{createLock}{}
|
|
Initializes a thread lock which can be used to serialize access to
|
|
underlying I/O functionality which may not be threadsafe.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{acquire}{}
|
|
Acquires the thread lock created with \method{createLock()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{release}{}
|
|
Releases the thread lock acquired with \method{acquire()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{setLevel}{lvl}
|
|
Sets the threshold for this handler to \var{lvl}. Logging messages which are
|
|
less severe than \var{lvl} will be ignored. When a handler is created, the
|
|
level is set to \constant{NOTSET} (which causes all messages to be processed).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{setFormatter}{form}
|
|
Sets the \class{Formatter} for this handler to \var{form}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{addFilter}{filt}
|
|
Adds the specified filter \var{filt} to this handler.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{removeFilter}{filt}
|
|
Removes the specified filter \var{filt} from this handler.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{filter}{record}
|
|
Applies this handler's filters to the record and returns a true value if
|
|
the record is to be processed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{flush}{}
|
|
Ensure all logging output has been flushed. This version does
|
|
nothing and is intended to be implemented by subclasses.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Tidy up any resources used by the handler. This version does
|
|
nothing and is intended to be implemented by subclasses.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle}{record}
|
|
Conditionally emits the specified logging record, depending on
|
|
filters which may have been added to the handler. Wraps the actual
|
|
emission of the record with acquisition/release of the I/O thread
|
|
lock.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handleError}{}
|
|
This method should be called from handlers when an exception is
|
|
encountered during an emit() call. By default it does nothing,
|
|
which means that exceptions get silently ignored. This is what is
|
|
mostly wanted for a logging system - most users will not care
|
|
about errors in the logging system, they are more interested in
|
|
application errors. You could, however, replace this with a custom
|
|
handler if you wish.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{format}{record}
|
|
Do formatting for a record - if a formatter is set, use it.
|
|
Otherwise, use the default formatter for the module.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
Do whatever it takes to actually log the specified logging record.
|
|
This version is intended to be implemented by subclasses and so
|
|
raises a \exception{NotImplementedError}.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{StreamHandler}
|
|
|
|
The \class{StreamHandler} class sends logging output to streams such as
|
|
\var{sys.stdout}, \var{sys.stderr} or any file-like object (or, more
|
|
precisely, any object which supports \method{write()} and \method{flush()}
|
|
methods).
|
|
|
|
\begin{classdesc}{StreamHandler}{\optional{strm}}
|
|
Returns a new instance of the \class{StreamHandler} class. If \var{strm} is
|
|
specified, the instance will use it for logging output; otherwise,
|
|
\var{sys.stderr} will be used.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
If a formatter is specified, it is used to format the record.
|
|
The record is then written to the stream with a trailing newline.
|
|
If exception information is present, it is formatted using
|
|
\function{traceback.print_exception()} and appended to the stream.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{flush}{}
|
|
Flushes the stream by calling its \method{flush()} method. Note that
|
|
the \method{close()} method is inherited from \class{Handler} and
|
|
so does nothing, so an explicit \method{flush()} call may be needed
|
|
at times.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{FileHandler}
|
|
|
|
The \class{FileHandler} class sends logging output to a disk file.
|
|
It inherits the output functionality from \class{StreamHandler}.
|
|
|
|
\begin{classdesc}{FileHandler}{filename\optional{, mode}}
|
|
Returns a new instance of the \class{FileHandler} class. The specified
|
|
file is opened and used as the stream for logging. If \var{mode} is
|
|
not specified, \constant{'a'} is used. By default, the file grows
|
|
indefinitely.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Closes the file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
Outputs the record to the file.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{RotatingFileHandler}
|
|
|
|
The \class{RotatingFileHandler} class supports rotation of disk log files.
|
|
|
|
\begin{classdesc}{RotatingFileHandler}{filename\optional{, mode\optional{,
|
|
maxBytes\optional{, backupCount}}}}
|
|
Returns a new instance of the \class{RotatingFileHandler} class. The
|
|
specified file is opened and used as the stream for logging. If
|
|
\var{mode} is not specified, \code{'a'} is used. By default, the
|
|
file grows indefinitely. You can use the \var{maxBytes} and
|
|
\var{backupCount} values to allow the file to \dfn{rollover} at a
|
|
predetermined size. When the size is about to be exceeded, the file is
|
|
closed and a new file opened for output, transparently to the
|
|
caller. Rollover occurs whenever the current log file is nearly
|
|
\var{maxBytes} in length. If \var{backupCount} is >= 1, the system
|
|
will successively create new files with the same pathname as the base
|
|
file, but with extensions ".1", ".2" etc. appended to it. For example,
|
|
with a backupCount of 5 and a base file name of "app.log", you would
|
|
get "app.log", "app.log.1", "app.log.2", ... through to
|
|
"app.log.5". When the last file reaches its size limit, the logging
|
|
reverts to "app.log" which is truncated to zero length. If
|
|
\var{maxBytes} is zero, rollover never occurs.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{doRollover}{}
|
|
Does a rollover, as described above.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
Outputs the record to the file, catering for rollover as described
|
|
in \method{setRollover()}.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{SocketHandler}
|
|
|
|
The \class{SocketHandler} class sends logging output to a network
|
|
socket. The base class uses a TCP socket.
|
|
|
|
\begin{classdesc}{SocketHandler}{host, port}
|
|
Returns a new instance of the \class{SocketHandler} class intended to
|
|
communicate with a remote machine whose address is given by \var{host}
|
|
and \var{port}.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Closes the socket.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handleError}{}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{emit}{}
|
|
Pickles the record's attribute dictionary and writes it to the socket in
|
|
binary format. If there is an error with the socket, silently drops the
|
|
packet. If the connection was previously lost, re-establishes the connection.
|
|
To unpickle the record at the receiving end into a LogRecord, use the
|
|
\function{makeLogRecord} function.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handleError}{}
|
|
Handles an error which has occurred during \method{emit()}. The
|
|
most likely cause is a lost connection. Closes the socket so that
|
|
we can retry on the next event.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{makeSocket}{}
|
|
This is a factory method which allows subclasses to define the precise
|
|
type of socket they want. The default implementation creates a TCP
|
|
socket (\constant{socket.SOCK_STREAM}).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{makePickle}{record}
|
|
Pickles the record's attribute dictionary in binary format with a length
|
|
prefix, and returns it ready for transmission across the socket.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{send}{packet}
|
|
Send a pickled string \var{packet} to the socket. This function allows
|
|
for partial sends which can happen when the network is busy.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{DatagramHandler}
|
|
|
|
The \class{DatagramHandler} class inherits from \class{SocketHandler}
|
|
to support sending logging messages over UDP sockets.
|
|
|
|
\begin{classdesc}{DatagramHandler}{host, port}
|
|
Returns a new instance of the \class{DatagramHandler} class intended to
|
|
communicate with a remote machine whose address is given by \var{host}
|
|
and \var{port}.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{emit}{}
|
|
Pickles the record's attribute dictionary and writes it to the socket in
|
|
binary format. If there is an error with the socket, silently drops the
|
|
packet.
|
|
To unpickle the record at the receiving end into a LogRecord, use the
|
|
\function{makeLogRecord} function.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{makeSocket}{}
|
|
The factory method of \class{SocketHandler} is here overridden to create
|
|
a UDP socket (\constant{socket.SOCK_DGRAM}).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{send}{s}
|
|
Send a pickled string to a socket.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{SysLogHandler}
|
|
|
|
The \class{SysLogHandler} class supports sending logging messages to a
|
|
remote or local \UNIX{} syslog.
|
|
|
|
\begin{classdesc}{SysLogHandler}{\optional{address\optional{, facility}}}
|
|
Returns a new instance of the \class{SysLogHandler} class intended to
|
|
communicate with a remote \UNIX{} machine whose address is given by
|
|
\var{address} in the form of a \code{(\var{host}, \var{port})}
|
|
tuple. If \var{address} is not specified, \code{('localhost', 514)} is
|
|
used. The address is used to open a UDP socket. If \var{facility} is
|
|
not specified, \constant{LOG_USER} is used.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Closes the socket to the remote host.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
The record is formatted, and then sent to the syslog server. If
|
|
exception information is present, it is \emph{not} sent to the server.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{encodePriority}{facility, priority}
|
|
Encodes the facility and priority into an integer. You can pass in strings
|
|
or integers - if strings are passed, internal mapping dictionaries are used
|
|
to convert them to integers.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{NTEventLogHandler}
|
|
|
|
The \class{NTEventLogHandler} class supports sending logging messages
|
|
to a local Windows NT, Windows 2000 or Windows XP event log. Before
|
|
you can use it, you need Mark Hammond's Win32 extensions for Python
|
|
installed.
|
|
|
|
\begin{classdesc}{NTEventLogHandler}{appname\optional{,
|
|
dllname\optional{, logtype}}}
|
|
Returns a new instance of the \class{NTEventLogHandler} class. The
|
|
\var{appname} is used to define the application name as it appears in the
|
|
event log. An appropriate registry entry is created using this name.
|
|
The \var{dllname} should give the fully qualified pathname of a .dll or .exe
|
|
which contains message definitions to hold in the log (if not specified,
|
|
\code{'win32service.pyd'} is used - this is installed with the Win32
|
|
extensions and contains some basic placeholder message definitions.
|
|
Note that use of these placeholders will make your event logs big, as the
|
|
entire message source is held in the log. If you want slimmer logs, you have
|
|
to pass in the name of your own .dll or .exe which contains the message
|
|
definitions you want to use in the event log). The \var{logtype} is one of
|
|
\code{'Application'}, \code{'System'} or \code{'Security'}, and
|
|
defaults to \code{'Application'}.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
At this point, you can remove the application name from the registry as a
|
|
source of event log entries. However, if you do this, you will not be able
|
|
to see the events as you intended in the Event Log Viewer - it needs to be
|
|
able to access the registry to get the .dll name. The current version does
|
|
not do this (in fact it doesn't do anything).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
Determines the message ID, event category and event type, and then logs the
|
|
message in the NT event log.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getEventCategory}{record}
|
|
Returns the event category for the record. Override this if you
|
|
want to specify your own categories. This version returns 0.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getEventType}{record}
|
|
Returns the event type for the record. Override this if you want
|
|
to specify your own types. This version does a mapping using the
|
|
handler's typemap attribute, which is set up in \method{__init__()}
|
|
to a dictionary which contains mappings for \constant{DEBUG},
|
|
\constant{INFO}, \constant{WARNING}, \constant{ERROR} and
|
|
\constant{CRITICAL}. If you are using your own levels, you will either need
|
|
to override this method or place a suitable dictionary in the
|
|
handler's \var{typemap} attribute.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getMessageID}{record}
|
|
Returns the message ID for the record. If you are using your
|
|
own messages, you could do this by having the \var{msg} passed to the
|
|
logger being an ID rather than a format string. Then, in here,
|
|
you could use a dictionary lookup to get the message ID. This
|
|
version returns 1, which is the base message ID in
|
|
\file{win32service.pyd}.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{SMTPHandler}
|
|
|
|
The \class{SMTPHandler} class supports sending logging messages to an email
|
|
address via SMTP.
|
|
|
|
\begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject}
|
|
Returns a new instance of the \class{SMTPHandler} class. The
|
|
instance is initialized with the from and to addresses and subject
|
|
line of the email. The \var{toaddrs} should be a list of strings without
|
|
domain names (That's what the \var{mailhost} is for). To specify a
|
|
non-standard SMTP port, use the (host, port) tuple format for the
|
|
\var{mailhost} argument. If you use a string, the standard SMTP port
|
|
is used.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
Formats the record and sends it to the specified addressees.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getSubject}{record}
|
|
If you want to specify a subject line which is record-dependent,
|
|
override this method.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{MemoryHandler}
|
|
|
|
The \class{MemoryHandler} supports buffering of logging records in memory,
|
|
periodically flushing them to a \dfn{target} handler. Flushing occurs
|
|
whenever the buffer is full, or when an event of a certain severity or
|
|
greater is seen.
|
|
|
|
\class{MemoryHandler} is a subclass of the more general
|
|
\class{BufferingHandler}, which is an abstract class. This buffers logging
|
|
records in memory. Whenever each record is added to the buffer, a
|
|
check is made by calling \method{shouldFlush()} to see if the buffer
|
|
should be flushed. If it should, then \method{flush()} is expected to
|
|
do the needful.
|
|
|
|
\begin{classdesc}{BufferingHandler}{capacity}
|
|
Initializes the handler with a buffer of the specified capacity.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
Appends the record to the buffer. If \method{shouldFlush()} returns true,
|
|
calls \method{flush()} to process the buffer.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{flush}{}
|
|
You can override this to implement custom flushing behavior. This version
|
|
just zaps the buffer to empty.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{shouldFlush}{record}
|
|
Returns true if the buffer is up to capacity. This method can be
|
|
overridden to implement custom flushing strategies.
|
|
\end{methoddesc}
|
|
|
|
\begin{classdesc}{MemoryHandler}{capacity\optional{, flushLevel
|
|
\optional{, target}}}
|
|
Returns a new instance of the \class{MemoryHandler} class. The
|
|
instance is initialized with a buffer size of \var{capacity}. If
|
|
\var{flushLevel} is not specified, \constant{ERROR} is used. If no
|
|
\var{target} is specified, the target will need to be set using
|
|
\method{setTarget()} before this handler does anything useful.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Calls \method{flush()}, sets the target to \constant{None} and
|
|
clears the buffer.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{flush}{}
|
|
For a \class{MemoryHandler}, flushing means just sending the buffered
|
|
records to the target, if there is one. Override if you want
|
|
different behavior.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{setTarget}{target}
|
|
Sets the target handler for this handler.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{shouldFlush}{record}
|
|
Checks for buffer full or a record at the \var{flushLevel} or higher.
|
|
\end{methoddesc}
|
|
|
|
\subsubsection{HTTPHandler}
|
|
|
|
The \class{HTTPHandler} class supports sending logging messages to a
|
|
Web server, using either \samp{GET} or \samp{POST} semantics.
|
|
|
|
\begin{classdesc}{HTTPHandler}{host, url\optional{, method}}
|
|
Returns a new instance of the \class{HTTPHandler} class. The
|
|
instance is initialized with a host address, url and HTTP method.
|
|
If no \var{method} is specified, \samp{GET} is used.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{emit}{record}
|
|
Sends the record to the Web server as an URL-encoded dictionary.
|
|
\end{methoddesc}
|
|
|
|
\subsection{Formatter Objects}
|
|
|
|
\class{Formatter}s have the following attributes and methods. They are
|
|
responsible for converting a \class{LogRecord} to (usually) a string
|
|
which can be interpreted by either a human or an external system. The
|
|
base
|
|
\class{Formatter} allows a formatting string to be specified. If none is
|
|
supplied, the default value of \code{'\%(message)s\e'} is used.
|
|
|
|
A Formatter can be initialized with a format string which makes use of
|
|
knowledge of the \class{LogRecord} attributes - such as the default value
|
|
mentioned above making use of the fact that the user's message and
|
|
arguments are pre-formatted into a LogRecord's \var{message}
|
|
attribute. This format string contains standard python \%-style
|
|
mapping keys. See section \ref{typesseq-strings}, ``String Formatting
|
|
Operations,'' for more information on string formatting.
|
|
|
|
Currently, the useful mapping keys in a LogRecord are:
|
|
|
|
\begin{tableii}{l|l}{code}{Format}{Description}
|
|
\lineii{\%(name)s} {Name of the logger (logging channel).}
|
|
\lineii{\%(levelno)s} {Numeric logging level for the message
|
|
(\constant{DEBUG}, \constant{INFO},
|
|
\constant{WARNING}, \constant{ERROR},
|
|
\constant{CRITICAL}).}
|
|
\lineii{\%(levelname)s}{Text logging level for the message
|
|
(\code{'DEBUG'}, \code{'INFO'},
|
|
\code{'WARNING'}, \code{'ERROR'},
|
|
\code{'CRITICAL'}).}
|
|
\lineii{\%(pathname)s} {Full pathname of the source file where the logging
|
|
call was issued (if available).}
|
|
\lineii{\%(filename)s} {Filename portion of pathname.}
|
|
\lineii{\%(module)s} {Module (name portion of filename).}
|
|
\lineii{\%(lineno)d} {Source line number where the logging call was issued
|
|
(if available).}
|
|
\lineii{\%(created)f} {Time when the LogRecord was created (as
|
|
returned by \function{time.time()}).}
|
|
\lineii{\%(asctime)s} {Human-readable time when the LogRecord was created.
|
|
By default this is of the form
|
|
``2003-07-08 16:49:45,896'' (the numbers after the
|
|
comma are millisecond portion of the time).}
|
|
\lineii{\%(msecs)d} {Millisecond portion of the time when the
|
|
\class{LogRecord} was created.}
|
|
\lineii{\%(thread)d} {Thread ID (if available).}
|
|
\lineii{\%(process)d} {Process ID (if available).}
|
|
\lineii{\%(message)s} {The logged message, computed as \code{msg \% args}.}
|
|
\end{tableii}
|
|
|
|
\begin{classdesc}{Formatter}{\optional{fmt\optional{, datefmt}}}
|
|
Returns a new instance of the \class{Formatter} class. The
|
|
instance is initialized with a format string for the message as a whole,
|
|
as well as a format string for the date/time portion of a message. If
|
|
no \var{fmt} is specified, \code{'\%(message)s'} is used. If no \var{datefmt}
|
|
is specified, the ISO8601 date format is used.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{format}{record}
|
|
The record's attribute dictionary is used as the operand to a
|
|
string formatting operation. Returns the resulting string.
|
|
Before formatting the dictionary, a couple of preparatory steps
|
|
are carried out. The \var{message} attribute of the record is computed
|
|
using \var{msg} \% \var{args}. If the formatting string contains
|
|
\code{'(asctime)'}, \method{formatTime()} is called to format the
|
|
event time. If there is exception information, it is formatted using
|
|
\method{formatException()} and appended to the message.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{formatTime}{record\optional{, datefmt}}
|
|
This method should be called from \method{format()} by a formatter which
|
|
wants to make use of a formatted time. This method can be overridden
|
|
in formatters to provide for any specific requirement, but the
|
|
basic behavior is as follows: if \var{datefmt} (a string) is specified,
|
|
it is used with \function{time.strftime()} to format the creation time of the
|
|
record. Otherwise, the ISO8601 format is used. The resulting
|
|
string is returned.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{formatException}{exc_info}
|
|
Formats the specified exception information (a standard exception tuple
|
|
as returned by \function{sys.exc_info()}) as a string. This default
|
|
implementation just uses \function{traceback.print_exception()}.
|
|
The resulting string is returned.
|
|
\end{methoddesc}
|
|
|
|
\subsection{Filter Objects}
|
|
|
|
\class{Filter}s can be used by \class{Handler}s and \class{Logger}s for
|
|
more sophisticated filtering than is provided by levels. The base filter
|
|
class only allows events which are below a certain point in the logger
|
|
hierarchy. For example, a filter initialized 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 the empty string, all events are passed.
|
|
|
|
\begin{classdesc}{Filter}{\optional{name}}
|
|
Returns an instance of the \class{Filter} class. If \var{name} is specified,
|
|
it names a logger which, together with its children, will have its events
|
|
allowed through the filter. If no name is specified, allows every event.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{filter}{record}
|
|
Is the specified record to be logged? Returns zero for no, nonzero for
|
|
yes. If deemed appropriate, the record may be modified in-place by this
|
|
method.
|
|
\end{methoddesc}
|
|
|
|
\subsection{LogRecord Objects}
|
|
|
|
LogRecord instances are created every time something is logged. They
|
|
contain all the information pertinent to the event being logged. The
|
|
main information passed in is in msg and args, which are combined
|
|
using msg \% args to create the message field of the record. The record
|
|
also includes information such as when the record was created, the
|
|
source line where the logging call was made, and any exception
|
|
information to be logged.
|
|
|
|
LogRecord has no methods; it's just a repository for information about the
|
|
logging event. The only reason it's a class rather than a dictionary is to
|
|
facilitate extension.
|
|
|
|
\begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args,
|
|
exc_info}
|
|
Returns an instance of \class{LogRecord} initialized with interesting
|
|
information. The \var{name} is the logger name; \var{lvl} is the
|
|
numeric level; \var{pathname} is the absolute pathname of the source
|
|
file in which the logging call was made; \var{lineno} is the line
|
|
number in that file where the logging call is found; \var{msg} is the
|
|
user-supplied message (a format string); \var{args} is the tuple
|
|
which, together with \var{msg}, makes up the user message; and
|
|
\var{exc_info} is the exception tuple obtained by calling
|
|
\function{sys.exc_info() }(or \constant{None}, if no exception information
|
|
is available).
|
|
\end{classdesc}
|
|
|
|
\subsection{Thread Safety}
|
|
|
|
The logging module is intended to be thread-safe without any special work
|
|
needing to be done by its clients. It achieves this though using threading
|
|
locks; there is one lock to serialize access to the module's shared data,
|
|
and each handler also creates a lock to serialize access to its underlying
|
|
I/O.
|
|
|
|
\subsection{Configuration}
|
|
|
|
|
|
\subsubsection{Configuration functions}
|
|
|
|
The following functions allow the logging module to be
|
|
configured. Before they can be used, you must import
|
|
\module{logging.config}. Their use is optional --- you can configure
|
|
the logging module entirely by making calls to the main API (defined
|
|
in \module{logging} itself) and defining handlers which are declared
|
|
either in \module{logging} or \module{logging.handlers}.
|
|
|
|
\begin{funcdesc}{fileConfig}{fname\optional{, defaults}}
|
|
Reads the logging configuration from a ConfigParser-format file named
|
|
\var{fname}. This function can be called several times from an application,
|
|
allowing an end user the ability to select from various pre-canned
|
|
configurations (if the developer provides a mechanism to present the
|
|
choices and load the chosen configuration). Defaults to be passed to
|
|
ConfigParser can be specified in the \var{defaults} argument.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{listen}{\optional{port}}
|
|
Starts up a socket server on the specified port, and listens for new
|
|
configurations. If no port is specified, the module's default
|
|
\constant{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations
|
|
will be sent as a file suitable for processing by \function{fileConfig()}.
|
|
Returns a \class{Thread} instance on which you can call \method{start()}
|
|
to start the server, and which you can \method{join()} when appropriate.
|
|
To stop the server, call \function{stopListening()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{stopListening}{}
|
|
Stops the listening server which was created with a call to
|
|
\function{listen()}. This is typically called before calling \method{join()}
|
|
on the return value from \function{listen()}.
|
|
\end{funcdesc}
|
|
|
|
\subsubsection{Configuration file format}
|
|
|
|
The configuration file format understood by \function{fileConfig} is
|
|
based on ConfigParser functionality. The file must contain sections
|
|
called \code{[loggers]}, \code{[handlers]} and \code{[formatters]}
|
|
which identify by name the entities of each type which are defined in
|
|
the file. For each such entity, there is a separate section which
|
|
identified how that entity is configured. Thus, for a logger named
|
|
\code{log01} in the \code{[loggers]} section, the relevant
|
|
configuration details are held in a section
|
|
\code{[logger_log01]}. Similarly, a handler called \code{hand01} in
|
|
the \code{[handlers]} section will have its configuration held in a
|
|
section called \code{[handler_hand01]}, while a formatter called
|
|
\code{form01} in the \code{[formatters]} section will have its
|
|
configuration specified in a section called
|
|
\code{[formatter_form01]}. The root logger configuration must be
|
|
specified in a section called \code{[logger_root]}.
|
|
|
|
Examples of these sections in the file are given below.
|
|
|
|
\begin{verbatim}
|
|
[loggers]
|
|
keys=root,log02,log03,log04,log05,log06,log07
|
|
|
|
[handlers]
|
|
keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
|
|
|
|
[formatters]
|
|
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
|
|
\end{verbatim}
|
|
|
|
The root logger must specify a level and a list of handlers. An
|
|
example of a root logger section is given below.
|
|
|
|
\begin{verbatim}
|
|
[logger_root]
|
|
level=NOTSET
|
|
handlers=hand01
|
|
\end{verbatim}
|
|
|
|
The \code{level} entry can be one of \code{DEBUG, INFO, WARNING,
|
|
ERROR, CRITICAL} or \code{NOTSET}. For the root logger only,
|
|
\code{NOTSET} means that all messages will be logged. Level values are
|
|
\function{eval()}uated in the context of the \code{logging} package's
|
|
namespace.
|
|
|
|
The \code{handlers} entry is a comma-separated list of handler names,
|
|
which must appear in the \code{[handlers]} section. These names must
|
|
appear in the \code{[handlers]} section and have corresponding
|
|
sections in the configuration file.
|
|
|
|
For loggers other than the root logger, some additional information is
|
|
required. This is illustrated by the following example.
|
|
|
|
\begin{verbatim}
|
|
[logger_parser]
|
|
level=DEBUG
|
|
handlers=hand01
|
|
propagate=1
|
|
qualname=compiler.parser
|
|
\end{verbatim}
|
|
|
|
The \code{level} and \code{handlers} entries are interpreted as for
|
|
the root logger, except that if a non-root logger's level is specified
|
|
as \code{NOTSET}, the system consults loggers higher up the hierarchy
|
|
to determine the effective level of the logger. The \code{propagate}
|
|
entry is set to 1 to indicate that messages must propagate to handlers
|
|
higher up the logger hierarchy from this logger, or 0 to indicate that
|
|
messages are \strong{not} propagated to handlers up the hierarchy. The
|
|
\code{qualname} entry is the hierarchical channel name of the logger,
|
|
for example, the name used by the application to get the logger.
|
|
|
|
Sections which specify handler configuration are exemplified by the
|
|
following.
|
|
|
|
\begin{verbatim}
|
|
[handler_hand01]
|
|
class=StreamHandler
|
|
level=NOTSET
|
|
formatter=form01
|
|
args=(sys.stdout,)
|
|
\end{verbatim}
|
|
|
|
The \code{class} entry indicates the handler's class (as determined by
|
|
\function{eval()} in the \code{logging} package's namespace). The
|
|
\code{level} is interpreted as for loggers, and \code{NOTSET} is taken
|
|
to mean "log everything".
|
|
|
|
The \code{formatter} entry indicates the key name of the formatter for
|
|
this handler. If blank, a default formatter
|
|
(\code{logging._defaultFormatter}) is used. If a name is specified, it
|
|
must appear in the \code{[formatters]} section and have a
|
|
corresponding section in the configuration file.
|
|
|
|
The \code{args} entry, when \function{eval()}uated in the context of
|
|
the \code{logging} package's namespace, is the list of arguments to
|
|
the constructor for the handler class. Refer to the constructors for
|
|
the relevant handlers, or to the examples below, to see how typical
|
|
entries are constructed.
|
|
|
|
\begin{verbatim}
|
|
[handler_hand02]
|
|
class=FileHandler
|
|
level=DEBUG
|
|
formatter=form02
|
|
args=('python.log', 'w')
|
|
|
|
[handler_hand03]
|
|
class=handlers.SocketHandler
|
|
level=INFO
|
|
formatter=form03
|
|
args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
|
|
|
|
[handler_hand04]
|
|
class=handlers.DatagramHandler
|
|
level=WARN
|
|
formatter=form04
|
|
args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
|
|
|
|
[handler_hand05]
|
|
class=handlers.SysLogHandler
|
|
level=ERROR
|
|
formatter=form05
|
|
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
|
|
|
|
[handler_hand06]
|
|
class=NTEventLogHandler
|
|
level=CRITICAL
|
|
formatter=form06
|
|
args=('Python Application', '', 'Application')
|
|
|
|
[handler_hand07]
|
|
class=SMTPHandler
|
|
level=WARN
|
|
formatter=form07
|
|
args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
|
|
|
|
[handler_hand08]
|
|
class=MemoryHandler
|
|
level=NOTSET
|
|
formatter=form08
|
|
target=
|
|
args=(10, ERROR)
|
|
|
|
[handler_hand09]
|
|
class=HTTPHandler
|
|
level=NOTSET
|
|
formatter=form09
|
|
args=('localhost:9022', '/log', 'GET')
|
|
\end{verbatim}
|
|
|
|
Sections which specify formatter configuration are typified by the following.
|
|
|
|
\begin{verbatim}
|
|
[formatter_form01]
|
|
format=F1 %(asctime)s %(levelname)s %(message)s
|
|
datefmt=
|
|
\end{verbatim}
|
|
|
|
The \code{format} entry is the overall format string, and the
|
|
\code{datefmt} entry is the \function{strftime()}-compatible date/time format
|
|
string. If empty, the package substitutes ISO8601 format date/times, which
|
|
is almost equivalent to specifying the date format string "%Y-%m-%d %H:%M:%S".
|
|
The ISO8601 format also specifies milliseconds, which are appended to the
|
|
result of using the above format string, with a comma separator. An example
|
|
time in ISO8601 format is \code{2003-01-23 00:29:50,411}.
|
|
|
|
\subsection{Using the logging package}
|
|
|
|
\subsubsection{Basic example - log to a file}
|
|
|
|
Here's a simple logging example that just logs to a file. In order,
|
|
it creates a \class{Logger} instance, then a \class{FileHandler}
|
|
and a \class{Formatter}. It attaches the \class{Formatter} to the
|
|
\class{FileHandler}, then the \class{FileHandler} to the \class{Logger}.
|
|
Finally, it sets a debug level for the logger.
|
|
|
|
\begin{verbatim}
|
|
import logging
|
|
logger = logging.getLogger('myapp')
|
|
hdlr = logging.FileHandler('/var/tmp/myapp.log')
|
|
formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s')
|
|
hdlr.setFormatter(formatter)
|
|
logger.addHandler(hdlr)
|
|
logger.setLevel(logging.WARNING)
|
|
\end{verbatim}
|
|
|
|
We can use this logger object now to write entries to the log file:
|
|
|
|
\begin{verbatim}
|
|
logger.error('We have a problem')
|
|
logger.info('While this is just chatty')
|
|
\end{verbatim}
|
|
|
|
If we look in the file that was created, we'll see something like this:
|
|
\begin{verbatim}
|
|
2003-07-08 16:49:45,896 ERROR We have a problem
|
|
\end{verbatim}
|
|
|
|
The info message was not written to the file - we called the \method{setLevel}
|
|
method to say we only wanted \code{WARNING} or worse, so the info message is
|
|
discarded.
|
|
|
|
The timestamp is of the form
|
|
``year-month-day hour:minutes:seconds,milliseconds.''
|
|
Note that despite the three digits of precision in the milliseconds field,
|
|
not all systems provide time with this much precision.
|
|
|