Fixed a table that wasn't in a tableii block, and added a very simple

example to show how to log to a file.

Doc/lib/liblogging.tex

@@ -803,31 +803,35 @@ 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. Currently, the useful attributes in a LogRecord are
+attribute.  This format string contains standard python \%-style
-described by:
+mapping keys. See section \ref{typesseq-strings}, ``String Formatting
+Operations,'' for more information on string formatting.
 
-\%(name)s            Name of the logger (logging channel)
+Currently, the useful mapping keys in a LogRecord are:
-\%(levelno)s         Numeric logging level for the message (DEBUG, INFO,
+
-                     WARNING, ERROR, CRITICAL)
+\begin{tableii}{l|l}{formats}{Format}{Description}
-\%(levelname)s       Text logging level for the message ("DEBUG", "INFO",
+\lineii{\%(name)s}{Name of the logger (logging channel).}
-                     "WARNING", "ERROR", "CRITICAL")
+\lineii{\%(levelno)s}{Numeric logging level for the message (DEBUG, INFO,
-\%(pathname)s        Full pathname of the source file where the logging
+WARNING, ERROR, CRITICAL).}
-                     call was issued (if available)
+\lineii{\%(levelname)s}{Text logging level for the message ("DEBUG", "INFO",
-\%(filename)s        Filename portion of pathname
+"WARNING", "ERROR", "CRITICAL").}
-\%(module)s          Module (name portion of filename)
+\lineii{\%(pathname)s}{Full pathname of the source file where the logging
-\%(lineno)d          Source line number where the logging call was issued
+call was issued (if available).}
-                     (if available)
+\lineii{\%(filename)s}{Filename portion of pathname.}
-\%(created)f         Time when the LogRecord was created (time.time()
+\lineii{\%(module)s}{Module (name portion of filename).}
-                     return value)
+\lineii{\%(lineno)d}{Source line number where the logging call was issued
-\%(asctime)s         Textual time when the LogRecord was created
+(if available).}
-\%(msecs)d           Millisecond portion of the creation time
+\lineii{\%(created)f}{Time when the LogRecord was created (as returned by
-\%(relativeCreated)d Time in milliseconds when the LogRecord was created,
+\code{time.time()}).}
-                     relative to the time the logging module was loaded
+\lineii{\%(asctime)s}{Human-readable time when the LogRecord was created.
-                     (typically at application startup time)
+By default this is of the form ``2003-07-08 16:49:45,896'' (the numbers
-\%(thread)d          Thread ID (if available)
+after the comma are millisecond portion of the time).}
-\%(process)d         Process ID (if available)
+\lineii{\%(msecs)d}{Millisecond portion of the time when the LogRecord
-\%(message)s         The result of msg \% args, computed just as the
+was created.}
-                     record is emitted
+\lineii{\%(thread)d}{Thread ID (if available).}
+\lineii{\%(process)d}{Process ID (if available).}
+\lineii{\%(message)s}{The logged message, computed as  msg \% args.}
+\end{tableii}
 
 \begin{classdesc}{Formatter}{\optional{fmt\optional{, datefmt}}}
 Returns a new instance of the \class{Formatter} class. The
@@ -1124,3 +1128,45 @@ 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.
+