liblogging.tex

xen虚拟机源代码安装包

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}{record}
This method should be called from handlers when an exception is
encountered during an \method{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. The specified record is the one which was being
processed when the exception occurred.
\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 is silently opened for output. Rollover occurs
whenever the current log file is nearly \var{maxBytes} in length; if
\var{maxBytes} is zero, rollover never occurs.  If \var{backupCount}
is non-zero, the system will save old log files by appending the
extensions ".1", ".2" etc., to the filename. For example, with
a \var{backupCount} of 5 and a base file name of
\file{app.log}, you would get \file{app.log},
\file{app.log.1}, \file{app.log.2}, up to \file{app.log.5}. The file being
written to is always \file{app.log}.  When this file is filled, it is
closed and renamed to \file{app.log.1}, and if files \file{app.log.1},
\file{app.log.2}, etc.  exist, then they are renamed to \file{app.log.2},
\file{app.log.3} etc.  respectively.
\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}