liblogging.tex

xen虚拟机源代码安装包

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,
that is to say 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{Simplest usage}

Here's a simple example which shows the most casual usage of the logging
package.

\begin{verbatim}
import logging
logging.debug("Houston, we have a %s", "thorny problem")
logging.info("Houston, we have a %s", "interesting problem")
logging.warning("Houston, we have a %s", "bit of a problem")
logging.error("Houston, we have a %s", "major problem")
logging.critical("Houston, we have a %s", "major disaster")
try:
	infinity = 1 / 0
except:
	logging.exception("Houston, we have an %s", "unexpected problem")
\end{verbatim}

If you run the above example, this will produce:

\begin{verbatim}
WARNING:root:Houston, we have a bit of a problem
ERROR:root:Houston, we have a major problem
CRITICAL:root:Houston, we have a major disaster
ERROR:root:Houston, we have an unexpected problem
Traceback (most recent call last):
  File "C:\Projects\RDC\Python\packages\logging\test\tmp.py", line 8, in ?
    infinity = 1 / 0
ZeroDivisionError: integer division or modulo by zero
\end{verbatim}

The reason you get this output is that the default format is

\begin{verbatim}
"%(levelname)s:%(name)s:%(message)s".
\end{verbatim}

When you invoke functions \function{info()}, \function{warning()} etc. in the
logging package itself, these calls are delegated to the correspondingly
named methods in the root logger. This is why the logger name shown in the above
logging output is "root". If the root logger has no handlers configured, the
logging package creates a console handler and adds it to the root logger
automatically. (It does this by calling the \function{basicConfig()}, which you
can also call directly from your own code.)

By default, events with a severity below WARNING are suppressed. Notice
that the \function{exception()} function acts like \function{error()}, except
that a traceback is appended to the log entry.

\subsubsection{Logging to the console}

Here's a simple example which logs all messages to the console. We use a named
logger:

\begin{verbatim}
import logging
logging.basicConfig()
logger = logging.getLogger('myapp')
logger.setLevel(logging.DEBUG)
logger.debug("Houston, we have a %s", "thorny problem")
logger.info("Houston, we have a %s", "interesting problem")
logger.warning("Houston, we have a %s", "bit of a problem")
logger.error("Houston, we have a %s", "major problem")
logger.critical("Houston, we have a %s", "major disaster")
try:
	infinity = 1 / 0
except:
	logger.exception("Houston, we have an %s", "unexpected problem")
\end{verbatim}

Here's the corresponding output:

\begin{verbatim}
DEBUG:myapp:Houston, we have a thorny problem
INFO:myapp:Houston, we have a interesting problem
WARNING:myapp:Houston, we have a bit of a problem
ERROR:myapp:Houston, we have a major problem
CRITICAL:myapp:Houston, we have a major disaster
ERROR:myapp:Houston, we have an unexpected problem
Traceback (most recent call last):
  File "C:\Projects\RDC\Python\packages\logging\test\tmp.py", line 11, in ?
    infinity = 1 / 0
ZeroDivisionError: integer division or modulo by zero
\end{verbatim}

As you can see, the specified logger name now appears in the output, and
DEBUG and INFO messages are included in the output because we explicitly
asked for them via the call to \method{setLevel()}.

\subsubsection{Logging 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.

\subsubsection{Logging to a rotating set of files}