liblogging.tex

xen虚拟机源代码安装包

\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