Doc/lib/liblogging.tex

   1 \section{\module{logging} ---
   2          Logging facility for Python}
   3
   4 \declaremodule{standard}{logging}
   5
   6 % These apply to all modules, and may be given more than once:
   7
   8 \moduleauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
   9 \sectionauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
  10
  11 \modulesynopsis{Logging module for Python based on \pep{282}.}
  12
  13 \indexii{Errors}{logging}
  14
  15 \versionadded{2.3}
  16 This module defines functions and classes which implement a flexible
  17 error logging system for applications.
  18
  19 Logging is performed by calling methods on instances of the
  20 \class{Logger} class (hereafter called \dfn{loggers}). Each instance has a
  21 name, and they are conceptually arranged in a name space hierarchy
  22 using dots (periods) as separators. For example, a logger named
  23 "scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf".
  24 Logger names can be anything you want, and indicate the area of an
  25 application in which a logged message originates.
  26
  27 Logged messages also have levels of importance associated with them.
  28 The default levels provided are \constant{DEBUG}, \constant{INFO},
  29 \constant{WARNING}, \constant{ERROR} and \constant{CRITICAL}. As a
  30 convenience, you indicate the importance of a logged message by calling
  31 an appropriate method of \class{Logger}. The methods are
  32 \method{debug()}, \method{info()}, \method{warning()}, \method{error()} and
  33 \method{critical()}, which mirror the default levels. You are not
  34 constrained to use these levels: you can specify your own and use a
  35 more general \class{Logger} method, \method{log()}, which takes an
  36 explicit level argument.
  37
  38 The numeric values of logging levels are given in the following table. These
  39 are primarily of interest if you want to define your own levels, and need
  40 them to have specific values relative to the predefined levels. If you
  41 define a level with the same numeric value, it overwrites the predefined
  42 value; the predefined name is lost.
  43
  44 \begin{tableii}{l|l}{code}{Level}{Numeric value}
  45   \lineii{CRITICAL}{50}
  46   \lineii{ERROR}{40}
  47   \lineii{WARNING}{30}
  48   \lineii{INFO}{20}
  49   \lineii{DEBUG}{10}
  50   \lineii{NOTSET}{0}
  51 \end{tableii}
  52
  53 Levels can also be associated with loggers, being set either by the
  54 developer or through loading a saved logging configuration. When a
  55 logging method is called on a logger, the logger compares its own
  56 level with the level associated with the method call. If the logger's
  57 level is higher than the method call's, no logging message is actually
  58 generated. This is the basic mechanism controlling the verbosity of
  59 logging output.
  60
  61 Logging messages are encoded as instances of the \class{LogRecord} class.
  62 When a logger decides to actually log an event, an \class{LogRecord}
  63 instance is created from the logging message.
  64
  65 Logging messages are subjected to a dispatch mechanism through the
  66 use of \dfn{handlers}, which are instances of subclasses of the
  67 \class{Handler} class. Handlers are responsible for ensuring that a logged
  68 message (in the form of a \class{LogRecord}) ends up in a particular
  69 location (or set of locations) which is useful for the target audience for
  70 that message (such as end users, support desk staff, system administrators,
  71 developers). Handlers are passed \class{LogRecord} instances intended for
  72 particular destinations. Each logger can have zero, one or more handlers
  73 associated with it (via the \method{addHandler()} method of \class{Logger}).
  74 In addition to any handlers directly associated with a logger,
  75 \emph{all handlers associated with all ancestors of the logger} are
  76 called to dispatch the message.
  77
  78 Just as for loggers, handlers can have levels associated with them.
  79 A handler's level acts as a filter in the same way as a logger's level does.
  80 If a handler decides to actually dispatch an event, the \method{emit()} method
  81 is used to send the message to its destination. Most user-defined subclasses
  82 of \class{Handler} will need to override this \method{emit()}.
  83
  84 In addition to the base \class{Handler} class, many useful subclasses
  85 are provided:
  86
  87 \begin{enumerate}
  88
  89 \item \class{StreamHandler} instances send error messages to
  90 streams (file-like objects).
  91
  92 \item \class{FileHandler} instances send error messages to disk
  93 files.
  94
  95 \item \class{BaseRotatingHandler} is the base class for handlers that
  96 rotate log files at a certain point. It is not meant to be  instantiated
  97 directly. Instead, use \class{RotatingFileHandler} or
  98 \class{TimedRotatingFileHandler}.
  99
 100 \item \class{RotatingFileHandler} instances send error messages to disk
 101 files, with support for maximum log file sizes and log file rotation.
 102
 103 \item \class{TimedRotatingFileHandler} instances send error messages to
 104 disk files rotating the log file at certain timed intervals.
 105
 106 \item \class{SocketHandler} instances send error messages to
 107 TCP/IP sockets.
 108
 109 \item \class{DatagramHandler} instances send error messages to UDP
 110 sockets.
 111
 112 \item \class{SMTPHandler} instances send error messages to a
 113 designated email address.
 114
 115 \item \class{SysLogHandler} instances send error messages to a
 116 \UNIX{} syslog daemon, possibly on a remote machine.
 117
 118 \item \class{NTEventLogHandler} instances send error messages to a
 119 Windows NT/2000/XP event log.
 120
 121 \item \class{MemoryHandler} instances send error messages to a
 122 buffer in memory, which is flushed whenever specific criteria are
 123 met.
 124
 125 \item \class{HTTPHandler} instances send error messages to an
 126 HTTP server using either \samp{GET} or \samp{POST} semantics.
 127
 128 \end{enumerate}
 129
 130 The \class{StreamHandler} and \class{FileHandler} classes are defined
 131 in the core logging package. The other handlers are defined in a sub-
 132 module, \module{logging.handlers}. (There is also another sub-module,
 133 \module{logging.config}, for configuration functionality.)
 134
 135 Logged messages are formatted for presentation through instances of the
 136 \class{Formatter} class. They are initialized with a format string
 137 suitable for use with the \% operator and a dictionary.
 138
 139 For formatting multiple messages in a batch, instances of
 140 \class{BufferingFormatter} can be used. In addition to the format string
 141 (which is applied to each message in the batch), there is provision for
 142 header and trailer format strings.
 143
 144 When filtering based on logger level and/or handler level is not enough,
 145 instances of \class{Filter} can be added to both \class{Logger} and
 146 \class{Handler} instances (through their \method{addFilter()} method).
 147 Before deciding to process a message further, both loggers and handlers
 148 consult all their filters for permission. If any filter returns a false
 149 value, the message is not processed further.
 150
 151 The basic \class{Filter} functionality allows filtering by specific logger
 152 name. If this feature is used, messages sent to the named logger and its
 153 children are allowed through the filter, and all others dropped.
 154
 155 In addition to the classes described above, there are a number of module-
 156 level functions.
 157
 158 \begin{funcdesc}{getLogger}{\optional{name}}
 159 Return a logger with the specified name or, if no name is specified, return
 160 a logger which is the root logger of the hierarchy. If specified, the name
 161 is typically a dot-separated hierarchical name like \var{"a"}, \var{"a.b"}
 162 or \var{"a.b.c.d"}. Choice of these names is entirely up to the developer
 163 who is using logging.
 164
 165 All calls to this function with a given name return the same logger instance.
 166 This means that logger instances never need to be passed between different
 167 parts of an application.
 168 \end{funcdesc}
 169
 170 \begin{funcdesc}{getLoggerClass}{}
 171 Return either the standard \class{Logger} class, or the last class passed to
 172 \function{setLoggerClass()}. This function may be called from within a new
 173 class definition, to ensure that installing a customised \class{Logger} class
 174 will not undo customisations already applied by other code. For example:
 175
 176 \begin{verbatim}
 177  class MyLogger(logging.getLoggerClass()):
 178      # ... override behaviour here
 179 \end{verbatim}
 180
 181 \end{funcdesc}
 182
 183 \begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
 184 Logs a message with level \constant{DEBUG} on the root logger.
 185 The \var{msg} is the message format string, and the \var{args} are the
 186 arguments which are merged into \var{msg}. The only keyword argument in
 187 \var{kwargs} which is inspected is \var{exc_info} which, if it does not
 188 evaluate as false, causes exception information to be added to the logging
 189 message. If an exception tuple (in the format returned by
 190 \function{sys.exc_info()}) is provided, it is used; otherwise,
 191 \function{sys.exc_info()} is called to get the exception information.
 192 \end{funcdesc}
 193
 194 \begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
 195 Logs a message with level \constant{INFO} on the root logger.
 196 The arguments are interpreted as for \function{debug()}.
 197 \end{funcdesc}
 198
 199 \begin{funcdesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
 200 Logs a message with level \constant{WARNING} on the root logger.
 201 The arguments are interpreted as for \function{debug()}.
 202 \end{funcdesc}
 203
 204 \begin{funcdesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
 205 Logs a message with level \constant{ERROR} on the root logger.
 206 The arguments are interpreted as for \function{debug()}.
 207 \end{funcdesc}
 208
 209 \begin{funcdesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
 210 Logs a message with level \constant{CRITICAL} on the root logger.
 211 The arguments are interpreted as for \function{debug()}.
 212 \end{funcdesc}
 213
 214 \begin{funcdesc}{exception}{msg\optional{, *args}}
 215 Logs a message with level \constant{ERROR} on the root logger.
 216 The arguments are interpreted as for \function{debug()}. Exception info
 217 is added to the logging message. This function should only be called
 218 from an exception handler.
 219 \end{funcdesc}
 220
 221 \begin{funcdesc}{log}{level, msg\optional{, *args\optional{, **kwargs}}}
 222 Logs a message with level \var{level} on the root logger.
 223 The other arguments are interpreted as for \function{debug()}.
 224 \end{funcdesc}
 225
 226 \begin{funcdesc}{disable}{lvl}
 227 Provides an overriding level \var{lvl} for all loggers which takes
 228 precedence over the logger's own level. When the need arises to
 229 temporarily throttle logging output down across the whole application,
 230 this function can be useful.
 231 \end{funcdesc}
 232
 233 \begin{funcdesc}{addLevelName}{lvl, levelName}
 234 Associates level \var{lvl} with text \var{levelName} in an internal
 235 dictionary, which is used to map numeric levels to a textual
 236 representation, for example when a \class{Formatter} formats a message.
 237 This function can also be used to define your own levels. The only
 238 constraints are that all levels used must be registered using this
 239 function, levels should be positive integers and they should increase
 240 in increasing order of severity.
 241 \end{funcdesc}
 242
 243 \begin{funcdesc}{getLevelName}{lvl}
 244 Returns the textual representation of logging level \var{lvl}. If the
 245 level is one of the predefined levels \constant{CRITICAL},
 246 \constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG}
 247 then you get the corresponding string. If you have associated levels
 248 with names using \function{addLevelName()} then the name you have associated
 249 with \var{lvl} is returned. If a numeric value corresponding to one of the
 250 defined levels is passed in, the corresponding string representation is
 251 returned. Otherwise, the string "Level \%s" \% lvl is returned.
 252 \end{funcdesc}
 253
 254 \begin{funcdesc}{makeLogRecord}{attrdict}
 255 Creates and returns a new \class{LogRecord} instance whose attributes are
 256 defined by \var{attrdict}. This function is useful for taking a pickled
 257 \class{LogRecord} attribute dictionary, sent over a socket, and reconstituting
 258 it as a \class{LogRecord} instance at the receiving end.
 259 \end{funcdesc}
 260
 261 \begin{funcdesc}{basicConfig}{\optional{**kwargs}}
 262 Does basic configuration for the logging system by creating a
 263 \class{StreamHandler} with a default \class{Formatter} and adding it to
 264 the root logger. The functions \function{debug()}, \function{info()},
 265 \function{warning()}, \function{error()} and \function{critical()} will call
 266 \function{basicConfig()} automatically if no handlers are defined for the
 267 root logger.
 268
 269 \versionchanged[Formerly, \function{basicConfig} did not take any keyword
 270 arguments]{2.4}
 271
 272 The following keyword arguments are supported.
 273
 274 \begin{tableii}{l|l}{code}{Format}{Description}
 275 \lineii{filename}{Specifies that a FileHandler be created, using the
 276 specified filename, rather than a StreamHandler.}
 277 \lineii{filemode}{Specifies the mode to open the file, if filename is
 278 specified (if filemode is unspecified, it defaults to 'a').}
 279 \lineii{format}{Use the specified format string for the handler.}
 280 \lineii{datefmt}{Use the specified date/time format.}
 281 \lineii{level}{Set the root logger level to the specified level.}
 282 \lineii{stream}{Use the specified stream to initialize the StreamHandler.
 283 Note that this argument is incompatible with 'filename' - if both
 284 are present, 'stream' is ignored.}
 285 \end{tableii}
 286
 287 \end{funcdesc}
 288
 289 \begin{funcdesc}{shutdown}{}
 290 Informs the logging system to perform an orderly shutdown by flushing and
 291 closing all handlers.
 292 \end{funcdesc}
 293
 294 \begin{funcdesc}{setLoggerClass}{klass}
 295 Tells the logging system to use the class \var{klass} when instantiating a
 296 logger. The class should define \method{__init__()} such that only a name
 297 argument is required, and the \method{__init__()} should call
 298 \method{Logger.__init__()}. This function is typically called before any
 299 loggers are instantiated by applications which need to use custom logger
 300 behavior.
 301 \end{funcdesc}
 302
 303
 304 \begin{seealso}
 305   \seepep{282}{A Logging System}
 306          {The proposal which described this feature for inclusion in
 307           the Python standard library.}
 308   \seelink{http://www.red-dove.com/python_logging.html}
 309           {Original Python \module{logging} package}
 310           {This is the original source for the \module{logging}
 311            package.  The version of the package available from this
 312            site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x,
 313            which do not include the \module{logging} package in the standard
 314            library.}
 315 \end{seealso}
 316
 317
 318 \subsection{Logger Objects}
 319
 320 Loggers have the following attributes and methods. Note that Loggers are
 321 never instantiated directly, but always through the module-level function
 322 \function{logging.getLogger(name)}.
 323
 324 \begin{datadesc}{propagate}
 325 If this evaluates to false, logging messages are not passed by this
 326 logger or by child loggers to higher level (ancestor) loggers. The
 327 constructor sets this attribute to 1.
 328 \end{datadesc}
 329
 330 \begin{methoddesc}{setLevel}{lvl}
 331 Sets the threshold for this logger to \var{lvl}. Logging messages
 332 which are less severe than \var{lvl} will be ignored. When a logger is
 333 created, the level is set to \constant{NOTSET} (which causes all messages
 334 to be processed when the logger is the root logger, or delegation to the
 335 parent when the logger is a non-root logger). Note that the root logger
 336 is created with level \constant{WARNING}.
 337
 338 The term "delegation to the parent" means that if a logger has a level
 339 of NOTSET, its chain of ancestor loggers is traversed until either an
 340 ancestor with a level other than NOTSET is found, or the root is
 341 reached.
 342
 343 If an ancestor is found with a level other than NOTSET, then that
 344 ancestor's level is treated as the effective level of the logger where
 345 the ancestor search began, and is used to determine how a logging
 346 event is handled.
 347
 348 If the root is reached, and it has a level of NOTSET, then all
 349 messages will be processed. Otherwise, the root's level will be used
 350 as the effective level.
 351 \end{methoddesc}
 352
 353 \begin{methoddesc}{isEnabledFor}{lvl}
 354 Indicates if a message of severity \var{lvl} would be processed by
 355 this logger.  This method checks first the module-level level set by
 356 \function{logging.disable(lvl)} and then the logger's effective level as
 357 determined by \method{getEffectiveLevel()}.
 358 \end{methoddesc}
 359
 360 \begin{methoddesc}{getEffectiveLevel}{}
 361 Indicates the effective level for this logger. If a value other than
 362 \constant{NOTSET} has been set using \method{setLevel()}, it is returned.
 363 Otherwise, the hierarchy is traversed towards the root until a value
 364 other than \constant{NOTSET} is found, and that value is returned.
 365 \end{methoddesc}
 366
 367 \begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
 368 Logs a message with level \constant{DEBUG} on this logger.
 369 The \var{msg} is the message format string, and the \var{args} are the
 370 arguments which are merged into \var{msg}. The only keyword argument in
 371 \var{kwargs} which is inspected is \var{exc_info} which, if it does not
 372 evaluate as false, causes exception information to be added to the logging
 373 message. If an exception tuple (as provided by \function{sys.exc_info()})
 374 is provided, it is used; otherwise, \function{sys.exc_info()} is called
 375 to get the exception information.
 376 \end{methoddesc}
 377
 378 \begin{methoddesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
 379 Logs a message with level \constant{INFO} on this logger.
 380 The arguments are interpreted as for \method{debug()}.
 381 \end{methoddesc}
 382
 383 \begin{methoddesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
 384 Logs a message with level \constant{WARNING} on this logger.
 385 The arguments are interpreted as for \method{debug()}.
 386 \end{methoddesc}
 387
 388 \begin{methoddesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
 389 Logs a message with level \constant{ERROR} on this logger.
 390 The arguments are interpreted as for \method{debug()}.
 391 \end{methoddesc}
 392
 393 \begin{methoddesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
 394 Logs a message with level \constant{CRITICAL} on this logger.
 395 The arguments are interpreted as for \method{debug()}.
 396 \end{methoddesc}
 397
 398 \begin{methoddesc}{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
 399 Logs a message with integer level \var{lvl} on this logger.
 400 The other arguments are interpreted as for \method{debug()}.
 401 \end{methoddesc}
 402
 403 \begin{methoddesc}{exception}{msg\optional{, *args}}
 404 Logs a message with level \constant{ERROR} on this logger.
 405 The arguments are interpreted as for \method{debug()}. Exception info
 406 is added to the logging message. This method should only be called
 407 from an exception handler.
 408 \end{methoddesc}
 409
 410 \begin{methoddesc}{addFilter}{filt}
 411 Adds the specified filter \var{filt} to this logger.
 412 \end{methoddesc}
 413
 414 \begin{methoddesc}{removeFilter}{filt}
 415 Removes the specified filter \var{filt} from this logger.
 416 \end{methoddesc}
 417
 418 \begin{methoddesc}{filter}{record}
 419 Applies this logger's filters to the record and returns a true value if
 420 the record is to be processed.
 421 \end{methoddesc}
 422
 423 \begin{methoddesc}{addHandler}{hdlr}
 424 Adds the specified handler \var{hdlr} to this logger.
 425 \end{methoddesc}
 426
 427 \begin{methoddesc}{removeHandler}{hdlr}
 428 Removes the specified handler \var{hdlr} from this logger.
 429 \end{methoddesc}
 430
 431 \begin{methoddesc}{findCaller}{}
 432 Finds the caller's source filename and line number. Returns the filename
 433 and line number as a 2-element tuple.
 434 \end{methoddesc}
 435
 436 \begin{methoddesc}{handle}{record}
 437 Handles a record by passing it to all handlers associated with this logger
 438 and its ancestors (until a false value of \var{propagate} is found).
 439 This method is used for unpickled records received from a socket, as well
 440 as those created locally. Logger-level filtering is applied using
 441 \method{filter()}.
 442 \end{methoddesc}
 443
 444 \begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info}
 445 This is a factory method which can be overridden in subclasses to create
 446 specialized \class{LogRecord} instances.
 447 \end{methoddesc}
 448
 449 \subsection{Basic example \label{minimal-example}}
 450
 451 \versionchanged[formerly \function{basicConfig} did not take any keyword
 452 arguments]{2.4}
 453
 454 The \module{logging} package provides a lot of flexibility, and its
 455 configuration can appear daunting.  This section demonstrates that simple
 456 use of the logging package is possible.
 457
 458 The simplest example shows logging to the console:
 459
 460 \begin{verbatim}
 461 import logging
 462
 463 logging.debug('A debug message')
 464 logging.info('Some information')
 465 logging.warning('A shot across the bows')
 466 \end{verbatim}
 467
 468 If you run the above script, you'll see this:
 469 \begin{verbatim}
 470 WARNING:root:A shot across the bows
 471 \end{verbatim}
 472
 473 Because no particular logger was specified, the system used the root logger.
 474 The debug and info messages didn't appear because by default, the root
 475 logger is configured to only handle messages with a severity of WARNING
 476 or above. The message format is also a configuration default, as is the output
 477 destination of the messages - \code{sys.stderr}. The severity level,
 478 the message format and destination can be easily changed, as shown in
 479 the example below:
 480
 481 \begin{verbatim}
 482 import logging
 483
 484 logging.basicConfig(level=logging.DEBUG,
 485                     format='%(asctime)s %(levelname)s %(message)s',
 486                     filename='/tmp/myapp.log',
 487                     filemode='w')
 488 logging.debug('A debug message')
 489 logging.info('Some information')
 490 logging.warning('A shot across the bows')
 491 \end{verbatim}
 492
 493 The \method{basicConfig()} method is used to change the configuration
 494 defaults, which results in output (written to \code{/tmp/myapp.log})
 495 which should look something like the following:
 496
 497 \begin{verbatim}
 498 2004-07-02 13:00:08,743 DEBUG A debug message
 499 2004-07-02 13:00:08,743 INFO Some information
 500 2004-07-02 13:00:08,743 WARNING A shot across the bows
 501 \end{verbatim}
 502
 503 This time, all messages with a severity of DEBUG or above were handled,
 504 and the format of the messages was also changed, and output went to the
 505 specified file rather than the console.
 506
 507 Formatting uses standard Python string formatting - see section
 508 \ref{typesseq-strings}. The format string takes the following
 509 common specifiers. For a complete list of specifiers, consult the
 510 \class{Formatter} documentation.
 511
 512 \begin{tableii}{l|l}{code}{Format}{Description}
 513 \lineii{\%(name)s}     {Name of the logger (logging channel).}
 514 \lineii{\%(levelname)s}{Text logging level for the message
 515                         (\code{'DEBUG'}, \code{'INFO'},
 516                         \code{'WARNING'}, \code{'ERROR'},
 517                         \code{'CRITICAL'}).}
 518 \lineii{\%(asctime)s}  {Human-readable time when the \class{LogRecord}
 519                         was created.  By default this is of the form
 520                         ``2003-07-08 16:49:45,896'' (the numbers after the
 521                         comma are millisecond portion of the time).}
 522 \lineii{\%(message)s}  {The logged message.}
 523 \end{tableii}
 524
 525 To change the date/time format, you can pass an additional keyword parameter,
 526 \var{datefmt}, as in the following:
 527
 528 \begin{verbatim}
 529 import logging
 530
 531 logging.basicConfig(level=logging.DEBUG,
 532                     format='%(asctime)s %(levelname)-8s %(message)s',
 533                     datefmt='%a, %d %b %Y %H:%M:%S',
 534                     filename='/temp/myapp.log',
 535                     filemode='w')
 536 logging.debug('A debug message')
 537 logging.info('Some information')
 538 logging.warning('A shot across the bows')
 539 \end{verbatim}
 540
 541 which would result in output like
 542
 543 \begin{verbatim}
 544 Fri, 02 Jul 2004 13:06:18 DEBUG    A debug message
 545 Fri, 02 Jul 2004 13:06:18 INFO     Some information
 546 Fri, 02 Jul 2004 13:06:18 WARNING  A shot across the bows
 547 \end{verbatim}
 548
 549 The date format string follows the requirements of \function{strftime()} -
 550 see the documentation for the \refmodule{time} module.
 551
 552 If, instead of sending logging output to the console or a file, you'd rather
 553 use a file-like object which you have created separately, you can pass it
 554 to \function{basicConfig()} using the \var{stream} keyword argument. Note
 555 that if both \var{stream} and \var{filename} keyword arguments are passed,
 556 the \var{stream} argument is ignored.
 557
 558 Of course, you can put variable information in your output. To do this,
 559 simply have the message be a format string and pass in additional arguments
 560 containing the variable information, as in the following example:
 561
 562 \begin{verbatim}
 563 import logging
 564
 565 logging.basicConfig(level=logging.DEBUG,
 566                     format='%(asctime)s %(levelname)-8s %(message)s',
 567                     datefmt='%a, %d %b %Y %H:%M:%S',
 568                     filename='/temp/myapp.log',
 569                     filemode='w')
 570 logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs')
 571 \end{verbatim}
 572
 573 which would result in
 574
 575 \begin{verbatim}
 576 Wed, 21 Jul 2004 15:35:16 ERROR    Pack my box with 5 dozen liquor jugs
 577 \end{verbatim}
 578
 579 \subsection{Logging to multiple destinations \label{multiple-destinations}}
 580
 581 Let's say you want to log to console and file with different message formats
 582 and in differing circumstances. Say you want to log messages with levels
 583 of DEBUG and higher to file, and those messages at level INFO and higher to
 584 the console. Let's also assume that the file should contain timestamps, but
 585 the console messages should not. Here's how you can achieve this:
 586
 587 \begin{verbatim}
 588 import logging
 589
 590 # set up logging to file - see previous section for more details
 591 logging.basicConfig(level=logging.DEBUG,
 592                     format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
 593                     datefmt='%m-%d %H:%M',
 594                     filename='/temp/myapp.log',
 595                     filemode='w')
 596 # define a Handler which writes INFO messages or higher to the sys.stderr
 597 console = logging.StreamHandler()
 598 console.setLevel(logging.INFO)
 599 # set a format which is simpler for console use
 600 formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
 601 # tell the handler to use this format
 602 console.setFormatter(formatter)
 603 # add the handler to the root logger
 604 logging.getLogger('').addHandler(console)
 605
 606 # Now, we can log to the root logger, or any other logger. First the root...
 607 logging.info('Jackdaws love my big sphinx of quartz.')
 608
 609 # Now, define a couple of other loggers which might represent areas in your
 610 # application:
 611
 612 logger1 = logging.getLogger('myapp.area1')
 613 logger2 = logging.getLogger('myapp.area2')
 614
 615 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
 616 logger1.info('How quickly daft jumping zebras vex.')
 617 logger2.warning('Jail zesty vixen who grabbed pay from quack.')
 618 logger2.error('The five boxing wizards jump quickly.')
 619 \end{verbatim}
 620
 621 When you run this, on the console you will see
 622
 623 \begin{verbatim}
 624 root        : INFO     Jackdaws love my big sphinx of quartz.
 625 myapp.area1 : INFO     How quickly daft jumping zebras vex.
 626 myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.
 627 myapp.area2 : ERROR    The five boxing wizards jump quickly.
 628 \end{verbatim}
 629
 630 and in the file you will see something like
 631
 632 \begin{verbatim}
 633 10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.
 634 10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.
 635 10-22 22:19 myapp.area1  INFO     How quickly daft jumping zebras vex.
 636 10-22 22:19 myapp.area2  WARNING  Jail zesty vixen who grabbed pay from quack.
 637 10-22 22:19 myapp.area2  ERROR    The five boxing wizards jump quickly.
 638 \end{verbatim}
 639
 640 As you can see, the DEBUG message only shows up in the file. The other
 641 messages are sent to both destinations.
 642
 643 This example uses console and file handlers, but you can use any number and
 644 combination of handlers you choose.
 645
 646 \subsection{Sending and receiving logging events across a network
 647 \label{network-logging}}
 648
 649 Let's say you want to send logging events across a network, and handle them
 650 at the receiving end. A simple way of doing this is attaching a
 651 \class{SocketHandler} instance to the root logger at the sending end:
 652
 653 \begin{verbatim}
 654 import logging, logging.handlers
 655
 656 rootLogger = logging.getLogger('')
 657 rootLogger.setLevel(logging.DEBUG)
 658 socketHandler = logging.handlers.SocketHandler('localhost',
 659                     logging.handlers.DEFAULT_TCP_LOGGING_PORT)
 660 # don't bother with a formatter, since a socket handler sends the event as
 661 # an unformatted pickle
 662 rootLogger.addHandler(socketHandler)
 663
 664 # Now, we can log to the root logger, or any other logger. First the root...
 665 logging.info('Jackdaws love my big sphinx of quartz.')
 666
 667 # Now, define a couple of other loggers which might represent areas in your
 668 # application:
 669
 670 logger1 = logging.getLogger('myapp.area1')
 671 logger2 = logging.getLogger('myapp.area2')
 672
 673 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
 674 logger1.info('How quickly daft jumping zebras vex.')
 675 logger2.warning('Jail zesty vixen who grabbed pay from quack.')
 676 logger2.error('The five boxing wizards jump quickly.')
 677 \end{verbatim}
 678
 679 At the receiving end, you can set up a receiver using the
 680 \module{SocketServer} module. Here is a basic working example:
 681
 682 \begin{verbatim}
 683 import cPickle
 684 import logging
 685 import logging.handlers
 686 import SocketServer
 687 import struct
 688
 689
 690 class LogRecordStreamHandler(SocketServer.StreamRequestHandler):
 691     """Handler for a streaming logging request.
 692
 693     This basically logs the record using whatever logging policy is
 694     configured locally.
 695     """
 696
 697     def handle(self):
 698         """
 699         Handle multiple requests - each expected to be a 4-byte length,
 700         followed by the LogRecord in pickle format. Logs the record
 701         according to whatever policy is configured locally.
 702         """
 703         while 1:
 704             chunk = self.connection.recv(4)
 705             if len(chunk) < 4:
 706                 break
 707             slen = struct.unpack(">L", chunk)[0]
 708             chunk = self.connection.recv(slen)
 709             while len(chunk) < slen:
 710                 chunk = chunk + self.connection.recv(slen - len(chunk))
 711             obj = self.unPickle(chunk)
 712             record = logging.makeLogRecord(obj)
 713             self.handleLogRecord(record)
 714
 715     def unPickle(self, data):
 716         return cPickle.loads(data)
 717
 718     def handleLogRecord(self, record):
 719         # if a name is specified, we use the named logger rather than the one
 720         # implied by the record.
 721         if self.server.logname is not None:
 722             name = self.server.logname
 723         else:
 724             name = record.name
 725         logger = logging.getLogger(name)
 726         # N.B. EVERY record gets logged. This is because Logger.handle
 727         # is normally called AFTER logger-level filtering. If you want
 728         # to do filtering, do it at the client end to save wasting
 729         # cycles and network bandwidth!
 730         logger.handle(record)
 731
 732 class LogRecordSocketReceiver(SocketServer.ThreadingTCPServer):
 733     """simple TCP socket-based logging receiver suitable for testing.
 734     """
 735
 736     allow_reuse_address = 1
 737
 738     def __init__(self, host='localhost',
 739                  port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
 740                  handler=LogRecordStreamHandler):
 741         SocketServer.ThreadingTCPServer.__init__(self, (host, port), handler)
 742         self.abort = 0
 743         self.timeout = 1
 744         self.logname = None
 745
 746     def serve_until_stopped(self):
 747         import select
 748         abort = 0
 749         while not abort:
 750             rd, wr, ex = select.select([self.socket.fileno()],
 751                                        [], [],
 752                                        self.timeout)
 753             if rd:
 754                 self.handle_request()
 755             abort = self.abort
 756
 757 def main():
 758     logging.basicConfig(
 759         format="%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s")
 760     tcpserver = LogRecordSocketReceiver()
 761     print "About to start TCP server..."
 762     tcpserver.serve_until_stopped()
 763
 764 if __name__ == "__main__":
 765     main()
 766 \end{verbatim}
 767
 768 First run the server, and then the client. On the client side, nothing is
 769 printed on the console; on the server side, you should see something like:
 770
 771 \begin{verbatim}
 772 About to start TCP server...
 773    59 root            INFO     Jackdaws love my big sphinx of quartz.
 774    59 myapp.area1     DEBUG    Quick zephyrs blow, vexing daft Jim.
 775    69 myapp.area1     INFO     How quickly daft jumping zebras vex.
 776    69 myapp.area2     WARNING  Jail zesty vixen who grabbed pay from quack.
 777    69 myapp.area2     ERROR    The five boxing wizards jump quickly.
 778 \end{verbatim}
 779
 780 \subsection{Handler Objects}
 781
 782 Handlers have the following attributes and methods. Note that
 783 \class{Handler} is never instantiated directly; this class acts as a
 784 base for more useful subclasses. However, the \method{__init__()}
 785 method in subclasses needs to call \method{Handler.__init__()}.
 786
 787 \begin{methoddesc}{__init__}{level=\constant{NOTSET}}
 788 Initializes the \class{Handler} instance by setting its level, setting
 789 the list of filters to the empty list and creating a lock (using
 790 \method{createLock()}) for serializing access to an I/O mechanism.
 791 \end{methoddesc}
 792
 793 \begin{methoddesc}{createLock}{}
 794 Initializes a thread lock which can be used to serialize access to
 795 underlying I/O functionality which may not be threadsafe.
 796 \end{methoddesc}
 797
 798 \begin{methoddesc}{acquire}{}
 799 Acquires the thread lock created with \method{createLock()}.
 800 \end{methoddesc}
 801
 802 \begin{methoddesc}{release}{}
 803 Releases the thread lock acquired with \method{acquire()}.
 804 \end{methoddesc}
 805
 806 \begin{methoddesc}{setLevel}{lvl}
 807 Sets the threshold for this handler to \var{lvl}. Logging messages which are
 808 less severe than \var{lvl} will be ignored. When a handler is created, the
 809 level is set to \constant{NOTSET} (which causes all messages to be processed).
 810 \end{methoddesc}
 811
 812 \begin{methoddesc}{setFormatter}{form}
 813 Sets the \class{Formatter} for this handler to \var{form}.
 814 \end{methoddesc}
 815
 816 \begin{methoddesc}{addFilter}{filt}
 817 Adds the specified filter \var{filt} to this handler.
 818 \end{methoddesc}
 819
 820 \begin{methoddesc}{removeFilter}{filt}
 821 Removes the specified filter \var{filt} from this handler.
 822 \end{methoddesc}
 823
 824 \begin{methoddesc}{filter}{record}
 825 Applies this handler's filters to the record and returns a true value if
 826 the record is to be processed.
 827 \end{methoddesc}
 828
 829 \begin{methoddesc}{flush}{}
 830 Ensure all logging output has been flushed. This version does
 831 nothing and is intended to be implemented by subclasses.
 832 \end{methoddesc}
 833
 834 \begin{methoddesc}{close}{}
 835 Tidy up any resources used by the handler. This version does
 836 nothing and is intended to be implemented by subclasses.
 837 \end{methoddesc}
 838
 839 \begin{methoddesc}{handle}{record}
 840 Conditionally emits the specified logging record, depending on
 841 filters which may have been added to the handler. Wraps the actual
 842 emission of the record with acquisition/release of the I/O thread
 843 lock.
 844 \end{methoddesc}
 845
 846 \begin{methoddesc}{handleError}{record}
 847 This method should be called from handlers when an exception is
 848 encountered during an \method{emit()} call. By default it does nothing,
 849 which means that exceptions get silently ignored. This is what is
 850 mostly wanted for a logging system - most users will not care
 851 about errors in the logging system, they are more interested in
 852 application errors. You could, however, replace this with a custom
 853 handler if you wish. The specified record is the one which was being
 854 processed when the exception occurred.
 855 \end{methoddesc}
 856
 857 \begin{methoddesc}{format}{record}
 858 Do formatting for a record - if a formatter is set, use it.
 859 Otherwise, use the default formatter for the module.
 860 \end{methoddesc}
 861
 862 \begin{methoddesc}{emit}{record}
 863 Do whatever it takes to actually log the specified logging record.
 864 This version is intended to be implemented by subclasses and so
 865 raises a \exception{NotImplementedError}.
 866 \end{methoddesc}
 867
 868 \subsubsection{StreamHandler}
 869
 870 The \class{StreamHandler} class sends logging output to streams such as
 871 \var{sys.stdout}, \var{sys.stderr} or any file-like object (or, more
 872 precisely, any object which supports \method{write()} and \method{flush()}
 873 methods).
 874
 875 \begin{classdesc}{StreamHandler}{\optional{strm}}
 876 Returns a new instance of the \class{StreamHandler} class. If \var{strm} is
 877 specified, the instance will use it for logging output; otherwise,
 878 \var{sys.stderr} will be used.
 879 \end{classdesc}
 880
 881 \begin{methoddesc}{emit}{record}
 882 If a formatter is specified, it is used to format the record.
 883 The record is then written to the stream with a trailing newline.
 884 If exception information is present, it is formatted using
 885 \function{traceback.print_exception()} and appended to the stream.
 886 \end{methoddesc}
 887
 888 \begin{methoddesc}{flush}{}
 889 Flushes the stream by calling its \method{flush()} method. Note that
 890 the \method{close()} method is inherited from \class{Handler} and
 891 so does nothing, so an explicit \method{flush()} call may be needed
 892 at times.
 893 \end{methoddesc}
 894
 895 \subsubsection{FileHandler}
 896
 897 The \class{FileHandler} class sends logging output to a disk file.
 898 It inherits the output functionality from \class{StreamHandler}.
 899
 900 \begin{classdesc}{FileHandler}{filename\optional{, mode}}
 901 Returns a new instance of the \class{FileHandler} class. The specified
 902 file is opened and used as the stream for logging. If \var{mode} is
 903 not specified, \constant{'a'} is used. By default, the file grows
 904 indefinitely.
 905 \end{classdesc}
 906
 907 \begin{methoddesc}{close}{}
 908 Closes the file.
 909 \end{methoddesc}
 910
 911 \begin{methoddesc}{emit}{record}
 912 Outputs the record to the file.
 913 \end{methoddesc}
 914
 915 \subsubsection{RotatingFileHandler}
 916
 917 The \class{RotatingFileHandler} class supports rotation of disk log files.
 918
 919 \begin{classdesc}{RotatingFileHandler}{filename\optional{, mode\optional{,
 920                                        maxBytes\optional{, backupCount}}}}
 921 Returns a new instance of the \class{RotatingFileHandler} class. The
 922 specified file is opened and used as the stream for logging. If
 923 \var{mode} is not specified, \code{'a'} is used. By default, the
 924 file grows indefinitely.
 925
 926 You can use the \var{maxBytes} and
 927 \var{backupCount} values to allow the file to \dfn{rollover} at a
 928 predetermined size. When the size is about to be exceeded, the file is
 929 closed and a new file is silently opened for output. Rollover occurs
 930 whenever the current log file is nearly \var{maxBytes} in length; if
 931 \var{maxBytes} is zero, rollover never occurs.  If \var{backupCount}
 932 is non-zero, the system will save old log files by appending the
 933 extensions ".1", ".2" etc., to the filename. For example, with
 934 a \var{backupCount} of 5 and a base file name of
 935 \file{app.log}, you would get \file{app.log},
 936 \file{app.log.1}, \file{app.log.2}, up to \file{app.log.5}. The file being
 937 written to is always \file{app.log}.  When this file is filled, it is
 938 closed and renamed to \file{app.log.1}, and if files \file{app.log.1},
 939 \file{app.log.2}, etc.  exist, then they are renamed to \file{app.log.2},
 940 \file{app.log.3} etc.  respectively.
 941 \end{classdesc}
 942
 943 \begin{methoddesc}{doRollover}{}
 944 Does a rollover, as described above.
 945 \end{methoddesc}
 946
 947 \begin{methoddesc}{emit}{record}
 948 Outputs the record to the file, catering for rollover as described previously.
 949 \end{methoddesc}
 950
 951 \subsubsection{TimedRotatingFileHandler}
 952
 953 The \class{TimedRotatingFileHandler} class supports rotation of disk log files
 954 at certain timed intervals.
 955
 956 \begin{classdesc}{TimedRotatingFileHandler}{filename
 957                                             \optional{,when
 958                                             \optional{,interval
 959                                             \optional{,backupCount}}}}
 960
 961 Returns a new instance of the \class{TimedRotatingFileHandler} class. The
 962 specified file is opened and used as the stream for logging. On rotating
 963 it also sets the filename suffix. Rotating happens based on the product
 964 of \var{when} and \var{interval}.
 965
 966 You can use the \var{when} to specify the type of \var{interval}. The
 967 list of possible values is, note that they are not case sensitive:
 968
 969 \begin{tableii}{l|l}{}{Value}{Type of interval}
 970   \lineii{S}{Seconds}
 971   \lineii{M}{Minutes}
 972   \lineii{H}{Hours}
 973   \lineii{D}{Days}
 974   \lineii{W}{Week day (0=Monday)}
 975   \lineii{midnight}{Roll over at midnight}
 976 \end{tableii}
 977
 978 If \var{backupCount} is non-zero, the system will save old log files by
 979 appending the extensions ".1", ".2" etc., to the filename. For example,
 980 with a \var{backupCount} of 5 and a base file name of \file{app.log},
 981 you would get \file{app.log}, \file{app.log.1}, \file{app.log.2}, up to
 982 \file{app.log.5}. The file being written to is always \file{app.log}.
 983 When this file is filled, it is closed and renamed to \file{app.log.1},
 984 and if files \file{app.log.1}, \file{app.log.2}, etc. exist, then they
 985 are renamed to \file{app.log.2}, \file{app.log.3} etc. respectively.
 986 \end{classdesc}
 987
 988 \begin{methoddesc}{doRollover}{}
 989 Does a rollover, as described above.
 990 \end{methoddesc}
 991
 992 \begin{methoddesc}{emit}{record}
 993 Outputs the record to the file, catering for rollover as described
 994 above.
 995 \end{methoddesc}
 996
 997 \subsubsection{SocketHandler}
 998
 999 The \class{SocketHandler} class sends logging output to a network
1000 socket. The base class uses a TCP socket.
1001
1002 \begin{classdesc}{SocketHandler}{host, port}
1003 Returns a new instance of the \class{SocketHandler} class intended to
1004 communicate with a remote machine whose address is given by \var{host}
1005 and \var{port}.
1006 \end{classdesc}
1007
1008 \begin{methoddesc}{close}{}
1009 Closes the socket.
1010 \end{methoddesc}
1011
1012 \begin{methoddesc}{handleError}{}
1013 \end{methoddesc}
1014
1015 \begin{methoddesc}{emit}{}
1016 Pickles the record's attribute dictionary and writes it to the socket in
1017 binary format. If there is an error with the socket, silently drops the
1018 packet. If the connection was previously lost, re-establishes the connection.
1019 To unpickle the record at the receiving end into a \class{LogRecord}, use the
1020 \function{makeLogRecord()} function.
1021 \end{methoddesc}
1022
1023 \begin{methoddesc}{handleError}{}
1024 Handles an error which has occurred during \method{emit()}. The
1025 most likely cause is a lost connection. Closes the socket so that
1026 we can retry on the next event.
1027 \end{methoddesc}
1028
1029 \begin{methoddesc}{makeSocket}{}
1030 This is a factory method which allows subclasses to define the precise
1031 type of socket they want. The default implementation creates a TCP
1032 socket (\constant{socket.SOCK_STREAM}).
1033 \end{methoddesc}
1034
1035 \begin{methoddesc}{makePickle}{record}
1036 Pickles the record's attribute dictionary in binary format with a length
1037 prefix, and returns it ready for transmission across the socket.
1038 \end{methoddesc}
1039
1040 \begin{methoddesc}{send}{packet}
1041 Send a pickled string \var{packet} to the socket. This function allows
1042 for partial sends which can happen when the network is busy.
1043 \end{methoddesc}
1044
1045 \subsubsection{DatagramHandler}
1046
1047 The \class{DatagramHandler} class inherits from \class{SocketHandler}
1048 to support sending logging messages over UDP sockets.
1049
1050 \begin{classdesc}{DatagramHandler}{host, port}
1051 Returns a new instance of the \class{DatagramHandler} class intended to
1052 communicate with a remote machine whose address is given by \var{host}
1053 and \var{port}.
1054 \end{classdesc}
1055
1056 \begin{methoddesc}{emit}{}
1057 Pickles the record's attribute dictionary and writes it to the socket in
1058 binary format. If there is an error with the socket, silently drops the
1059 packet.
1060 To unpickle the record at the receiving end into a \class{LogRecord}, use the
1061 \function{makeLogRecord()} function.
1062 \end{methoddesc}
1063
1064 \begin{methoddesc}{makeSocket}{}
1065 The factory method of \class{SocketHandler} is here overridden to create
1066 a UDP socket (\constant{socket.SOCK_DGRAM}).
1067 \end{methoddesc}
1068
1069 \begin{methoddesc}{send}{s}
1070 Send a pickled string to a socket.
1071 \end{methoddesc}
1072
1073 \subsubsection{SysLogHandler}
1074
1075 The \class{SysLogHandler} class supports sending logging messages to a
1076 remote or local \UNIX{} syslog.
1077
1078 \begin{classdesc}{SysLogHandler}{\optional{address\optional{, facility}}}
1079 Returns a new instance of the \class{SysLogHandler} class intended to
1080 communicate with a remote \UNIX{} machine whose address is given by
1081 \var{address} in the form of a \code{(\var{host}, \var{port})}
1082 tuple.  If \var{address} is not specified, \code{('localhost', 514)} is
1083 used.  The address is used to open a UDP socket.  If \var{facility} is
1084 not specified, \constant{LOG_USER} is used.
1085 \end{classdesc}
1086
1087 \begin{methoddesc}{close}{}
1088 Closes the socket to the remote host.
1089 \end{methoddesc}
1090
1091 \begin{methoddesc}{emit}{record}
1092 The record is formatted, and then sent to the syslog server. If
1093 exception information is present, it is \emph{not} sent to the server.
1094 \end{methoddesc}
1095
1096 \begin{methoddesc}{encodePriority}{facility, priority}
1097 Encodes the facility and priority into an integer. You can pass in strings
1098 or integers - if strings are passed, internal mapping dictionaries are used
1099 to convert them to integers.
1100 \end{methoddesc}
1101
1102 \subsubsection{NTEventLogHandler}
1103
1104 The \class{NTEventLogHandler} class supports sending logging messages
1105 to a local Windows NT, Windows 2000 or Windows XP event log. Before
1106 you can use it, you need Mark Hammond's Win32 extensions for Python
1107 installed.
1108
1109 \begin{classdesc}{NTEventLogHandler}{appname\optional{,
1110                                      dllname\optional{, logtype}}}
1111 Returns a new instance of the \class{NTEventLogHandler} class. The
1112 \var{appname} is used to define the application name as it appears in the
1113 event log. An appropriate registry entry is created using this name.
1114 The \var{dllname} should give the fully qualified pathname of a .dll or .exe
1115 which contains message definitions to hold in the log (if not specified,
1116 \code{'win32service.pyd'} is used - this is installed with the Win32
1117 extensions and contains some basic placeholder message definitions.
1118 Note that use of these placeholders will make your event logs big, as the
1119 entire message source is held in the log. If you want slimmer logs, you have
1120 to pass in the name of your own .dll or .exe which contains the message
1121 definitions you want to use in the event log). The \var{logtype} is one of
1122 \code{'Application'}, \code{'System'} or \code{'Security'}, and
1123 defaults to \code{'Application'}.
1124 \end{classdesc}
1125
1126 \begin{methoddesc}{close}{}
1127 At this point, you can remove the application name from the registry as a
1128 source of event log entries. However, if you do this, you will not be able
1129 to see the events as you intended in the Event Log Viewer - it needs to be
1130 able to access the registry to get the .dll name. The current version does
1131 not do this (in fact it doesn't do anything).
1132 \end{methoddesc}
1133
1134 \begin{methoddesc}{emit}{record}
1135 Determines the message ID, event category and event type, and then logs the
1136 message in the NT event log.
1137 \end{methoddesc}
1138
1139 \begin{methoddesc}{getEventCategory}{record}
1140 Returns the event category for the record. Override this if you
1141 want to specify your own categories. This version returns 0.
1142 \end{methoddesc}
1143
1144 \begin{methoddesc}{getEventType}{record}
1145 Returns the event type for the record. Override this if you want
1146 to specify your own types. This version does a mapping using the
1147 handler's typemap attribute, which is set up in \method{__init__()}
1148 to a dictionary which contains mappings for \constant{DEBUG},
1149 \constant{INFO}, \constant{WARNING}, \constant{ERROR} and
1150 \constant{CRITICAL}. If you are using your own levels, you will either need
1151 to override this method or place a suitable dictionary in the
1152 handler's \var{typemap} attribute.
1153 \end{methoddesc}
1154
1155 \begin{methoddesc}{getMessageID}{record}
1156 Returns the message ID for the record. If you are using your
1157 own messages, you could do this by having the \var{msg} passed to the
1158 logger being an ID rather than a format string. Then, in here,
1159 you could use a dictionary lookup to get the message ID. This
1160 version returns 1, which is the base message ID in
1161 \file{win32service.pyd}.
1162 \end{methoddesc}
1163
1164 \subsubsection{SMTPHandler}
1165
1166 The \class{SMTPHandler} class supports sending logging messages to an email
1167 address via SMTP.
1168
1169 \begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject}
1170 Returns a new instance of the \class{SMTPHandler} class. The
1171 instance is initialized with the from and to addresses and subject
1172 line of the email. The \var{toaddrs} should be a list of strings. To specify a
1173 non-standard SMTP port, use the (host, port) tuple format for the
1174 \var{mailhost} argument. If you use a string, the standard SMTP port
1175 is used.
1176 \end{classdesc}
1177
1178 \begin{methoddesc}{emit}{record}
1179 Formats the record and sends it to the specified addressees.
1180 \end{methoddesc}
1181
1182 \begin{methoddesc}{getSubject}{record}
1183 If you want to specify a subject line which is record-dependent,
1184 override this method.
1185 \end{methoddesc}
1186
1187 \subsubsection{MemoryHandler}
1188
1189 The \class{MemoryHandler} supports buffering of logging records in memory,
1190 periodically flushing them to a \dfn{target} handler. Flushing occurs
1191 whenever the buffer is full, or when an event of a certain severity or
1192 greater is seen.
1193
1194 \class{MemoryHandler} is a subclass of the more general
1195 \class{BufferingHandler}, which is an abstract class. This buffers logging
1196 records in memory. Whenever each record is added to the buffer, a
1197 check is made by calling \method{shouldFlush()} to see if the buffer
1198 should be flushed.  If it should, then \method{flush()} is expected to
1199 do the needful.
1200
1201 \begin{classdesc}{BufferingHandler}{capacity}
1202 Initializes the handler with a buffer of the specified capacity.
1203 \end{classdesc}
1204
1205 \begin{methoddesc}{emit}{record}
1206 Appends the record to the buffer. If \method{shouldFlush()} returns true,
1207 calls \method{flush()} to process the buffer.
1208 \end{methoddesc}
1209
1210 \begin{methoddesc}{flush}{}
1211 You can override this to implement custom flushing behavior. This version
1212 just zaps the buffer to empty.
1213 \end{methoddesc}
1214
1215 \begin{methoddesc}{shouldFlush}{record}
1216 Returns true if the buffer is up to capacity. This method can be
1217 overridden to implement custom flushing strategies.
1218 \end{methoddesc}
1219
1220 \begin{classdesc}{MemoryHandler}{capacity\optional{, flushLevel
1221 \optional{, target}}}
1222 Returns a new instance of the \class{MemoryHandler} class. The
1223 instance is initialized with a buffer size of \var{capacity}. If
1224 \var{flushLevel} is not specified, \constant{ERROR} is used. If no
1225 \var{target} is specified, the target will need to be set using
1226 \method{setTarget()} before this handler does anything useful.
1227 \end{classdesc}
1228
1229 \begin{methoddesc}{close}{}
1230 Calls \method{flush()}, sets the target to \constant{None} and
1231 clears the buffer.
1232 \end{methoddesc}
1233
1234 \begin{methoddesc}{flush}{}
1235 For a \class{MemoryHandler}, flushing means just sending the buffered
1236 records to the target, if there is one. Override if you want
1237 different behavior.
1238 \end{methoddesc}
1239
1240 \begin{methoddesc}{setTarget}{target}
1241 Sets the target handler for this handler.
1242 \end{methoddesc}
1243
1244 \begin{methoddesc}{shouldFlush}{record}
1245 Checks for buffer full or a record at the \var{flushLevel} or higher.
1246 \end{methoddesc}
1247
1248 \subsubsection{HTTPHandler}
1249
1250 The \class{HTTPHandler} class supports sending logging messages to a
1251 Web server, using either \samp{GET} or \samp{POST} semantics.
1252
1253 \begin{classdesc}{HTTPHandler}{host, url\optional{, method}}
1254 Returns a new instance of the \class{HTTPHandler} class. The
1255 instance is initialized with a host address, url and HTTP method.
1256 The \var{host} can be of the form \code{host:port}, should you need to
1257 use a specific port number. If no \var{method} is specified, \samp{GET}
1258 is used.
1259 \end{classdesc}
1260
1261 \begin{methoddesc}{emit}{record}
1262 Sends the record to the Web server as an URL-encoded dictionary.
1263 \end{methoddesc}
1264
1265 \subsection{Formatter Objects}
1266
1267 \class{Formatter}s have the following attributes and methods. They are
1268 responsible for converting a \class{LogRecord} to (usually) a string
1269 which can be interpreted by either a human or an external system. The
1270 base
1271 \class{Formatter} allows a formatting string to be specified. If none is
1272 supplied, the default value of \code{'\%(message)s'} is used.
1273
1274 A Formatter can be initialized with a format string which makes use of
1275 knowledge of the \class{LogRecord} attributes - such as the default value
1276 mentioned above making use of the fact that the user's message and
1277 arguments are pre-formatted into a \class{LogRecord}'s \var{message}
1278 attribute.  This format string contains standard python \%-style
1279 mapping keys. See section \ref{typesseq-strings}, ``String Formatting
1280 Operations,'' for more information on string formatting.
1281
1282 Currently, the useful mapping keys in a \class{LogRecord} are:
1283
1284 \begin{tableii}{l|l}{code}{Format}{Description}
1285 \lineii{\%(name)s}     {Name of the logger (logging channel).}
1286 \lineii{\%(levelno)s}  {Numeric logging level for the message
1287                         (\constant{DEBUG}, \constant{INFO},
1288                         \constant{WARNING}, \constant{ERROR},
1289                         \constant{CRITICAL}).}
1290 \lineii{\%(levelname)s}{Text logging level for the message
1291                         (\code{'DEBUG'}, \code{'INFO'},
1292                         \code{'WARNING'}, \code{'ERROR'},
1293                         \code{'CRITICAL'}).}
1294 \lineii{\%(pathname)s} {Full pathname of the source file where the logging
1295                         call was issued (if available).}
1296 \lineii{\%(filename)s} {Filename portion of pathname.}
1297 \lineii{\%(module)s}   {Module (name portion of filename).}
1298 \lineii{\%(lineno)d}   {Source line number where the logging call was issued
1299                         (if available).}
1300 \lineii{\%(created)f}  {Time when the \class{LogRecord} was created (as
1301                         returned by \function{time.time()}).}
1302 \lineii{\%(asctime)s}  {Human-readable time when the \class{LogRecord}
1303                         was created.  By default this is of the form
1304                         ``2003-07-08 16:49:45,896'' (the numbers after the
1305                         comma are millisecond portion of the time).}
1306 \lineii{\%(msecs)d}    {Millisecond portion of the time when the
1307                         \class{LogRecord} was created.}
1308 \lineii{\%(thread)d}   {Thread ID (if available).}
1309 \lineii{\%(threadName)s}   {Thread name (if available).}
1310 \lineii{\%(process)d}  {Process ID (if available).}
1311 \lineii{\%(message)s}  {The logged message, computed as \code{msg \% args}.}
1312 \end{tableii}
1313
1314 \begin{classdesc}{Formatter}{\optional{fmt\optional{, datefmt}}}
1315 Returns a new instance of the \class{Formatter} class. The
1316 instance is initialized with a format string for the message as a whole,
1317 as well as a format string for the date/time portion of a message. If
1318 no \var{fmt} is specified, \code{'\%(message)s'} is used. If no \var{datefmt}
1319 is specified, the ISO8601 date format is used.
1320 \end{classdesc}
1321
1322 \begin{methoddesc}{format}{record}
1323 The record's attribute dictionary is used as the operand to a
1324 string formatting operation. Returns the resulting string.
1325 Before formatting the dictionary, a couple of preparatory steps
1326 are carried out. The \var{message} attribute of the record is computed
1327 using \var{msg} \% \var{args}. If the formatting string contains
1328 \code{'(asctime)'}, \method{formatTime()} is called to format the
1329 event time. If there is exception information, it is formatted using
1330 \method{formatException()} and appended to the message.
1331 \end{methoddesc}
1332
1333 \begin{methoddesc}{formatTime}{record\optional{, datefmt}}
1334 This method should be called from \method{format()} by a formatter which
1335 wants to make use of a formatted time. This method can be overridden
1336 in formatters to provide for any specific requirement, but the
1337 basic behavior is as follows: if \var{datefmt} (a string) is specified,
1338 it is used with \function{time.strftime()} to format the creation time of the
1339 record. Otherwise, the ISO8601 format is used. The resulting
1340 string is returned.
1341 \end{methoddesc}
1342
1343 \begin{methoddesc}{formatException}{exc_info}
1344 Formats the specified exception information (a standard exception tuple
1345 as returned by \function{sys.exc_info()}) as a string. This default
1346 implementation just uses \function{traceback.print_exception()}.
1347 The resulting string is returned.
1348 \end{methoddesc}
1349
1350 \subsection{Filter Objects}
1351
1352 \class{Filter}s can be used by \class{Handler}s and \class{Logger}s for
1353 more sophisticated filtering than is provided by levels. The base filter
1354 class only allows events which are below a certain point in the logger
1355 hierarchy. For example, a filter initialized with "A.B" will allow events
1356 logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB",
1357 "B.A.B" etc. If initialized with the empty string, all events are passed.
1358
1359 \begin{classdesc}{Filter}{\optional{name}}
1360 Returns an instance of the \class{Filter} class. If \var{name} is specified,
1361 it names a logger which, together with its children, will have its events
1362 allowed through the filter. If no name is specified, allows every event.
1363 \end{classdesc}
1364
1365 \begin{methoddesc}{filter}{record}
1366 Is the specified record to be logged? Returns zero for no, nonzero for
1367 yes. If deemed appropriate, the record may be modified in-place by this
1368 method.
1369 \end{methoddesc}
1370
1371 \subsection{LogRecord Objects}
1372
1373 \class{LogRecord} instances are created every time something is logged. They
1374 contain all the information pertinent to the event being logged. The
1375 main information passed in is in msg and args, which are combined
1376 using msg \% args to create the message field of the record. The record
1377 also includes information such as when the record was created, the
1378 source line where the logging call was made, and any exception
1379 information to be logged.
1380
1381 \begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args,
1382                              exc_info}
1383 Returns an instance of \class{LogRecord} initialized with interesting
1384 information. The \var{name} is the logger name; \var{lvl} is the
1385 numeric level; \var{pathname} is the absolute pathname of the source
1386 file in which the logging call was made; \var{lineno} is the line
1387 number in that file where the logging call is found; \var{msg} is the
1388 user-supplied message (a format string); \var{args} is the tuple
1389 which, together with \var{msg}, makes up the user message; and
1390 \var{exc_info} is the exception tuple obtained by calling
1391 \function{sys.exc_info() }(or \constant{None}, if no exception information
1392 is available).
1393 \end{classdesc}
1394
1395 \begin{methoddesc}{getMessage}{}
1396 Returns the message for this \class{LogRecord} instance after merging any
1397 user-supplied arguments with the message.
1398 \end{methoddesc}
1399
1400 \subsection{Thread Safety}
1401
1402 The logging module is intended to be thread-safe without any special work
1403 needing to be done by its clients. It achieves this though using threading
1404 locks; there is one lock to serialize access to the module's shared data,
1405 and each handler also creates a lock to serialize access to its underlying
1406 I/O.
1407
1408 \subsection{Configuration}
1409
1410
1411 \subsubsection{Configuration functions%
1412                \label{logging-config-api}}
1413
1414 The following functions allow the logging module to be
1415 configured. Before they can be used, you must import
1416 \module{logging.config}.  Their use is optional --- you can configure
1417 the logging module entirely by making calls to the main API (defined
1418 in \module{logging} itself) and defining handlers which are declared
1419 either in \module{logging} or \module{logging.handlers}.
1420
1421 \begin{funcdesc}{fileConfig}{fname\optional{, defaults}}
1422 Reads the logging configuration from a ConfigParser-format file named
1423 \var{fname}. This function can be called several times from an application,
1424 allowing an end user the ability to select from various pre-canned
1425 configurations (if the developer provides a mechanism to present the
1426 choices and load the chosen configuration). Defaults to be passed to
1427 ConfigParser can be specified in the \var{defaults} argument.
1428 \end{funcdesc}
1429
1430 \begin{funcdesc}{listen}{\optional{port}}
1431 Starts up a socket server on the specified port, and listens for new
1432 configurations. If no port is specified, the module's default
1433 \constant{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations
1434 will be sent as a file suitable for processing by \function{fileConfig()}.
1435 Returns a \class{Thread} instance on which you can call \method{start()}
1436 to start the server, and which you can \method{join()} when appropriate.
1437 To stop the server, call \function{stopListening()}. To send a configuration
1438 to the socket, read in the configuration file and send it to the socket
1439 as a string of bytes preceded by a four-byte length packed in binary using
1440 struct.\code{pack(">L", n)}.
1441 \end{funcdesc}
1442
1443 \begin{funcdesc}{stopListening}{}
1444 Stops the listening server which was created with a call to
1445 \function{listen()}. This is typically called before calling \method{join()}
1446 on the return value from \function{listen()}.
1447 \end{funcdesc}
1448
1449 \subsubsection{Configuration file format%
1450                \label{logging-config-fileformat}}
1451
1452 The configuration file format understood by \function{fileConfig()} is
1453 based on ConfigParser functionality. The file must contain sections
1454 called \code{[loggers]}, \code{[handlers]} and \code{[formatters]}
1455 which identify by name the entities of each type which are defined in
1456 the file. For each such entity, there is a separate section which
1457 identified how that entity is configured. Thus, for a logger named
1458 \code{log01} in the \code{[loggers]} section, the relevant
1459 configuration details are held in a section
1460 \code{[logger_log01]}. Similarly, a handler called \code{hand01} in
1461 the \code{[handlers]} section will have its configuration held in a
1462 section called \code{[handler_hand01]}, while a formatter called
1463 \code{form01} in the \code{[formatters]} section will have its
1464 configuration specified in a section called
1465 \code{[formatter_form01]}. The root logger configuration must be
1466 specified in a section called \code{[logger_root]}.
1467
1468 Examples of these sections in the file are given below.
1469
1470 \begin{verbatim}
1471 [loggers]
1472 keys=root,log02,log03,log04,log05,log06,log07
1473
1474 [handlers]
1475 keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
1476
1477 [formatters]
1478 keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
1479 \end{verbatim}
1480
1481 The root logger must specify a level and a list of handlers. An
1482 example of a root logger section is given below.
1483
1484 \begin{verbatim}
1485 [logger_root]
1486 level=NOTSET
1487 handlers=hand01
1488 \end{verbatim}
1489
1490 The \code{level} entry can be one of \code{DEBUG, INFO, WARNING,
1491 ERROR, CRITICAL} or \code{NOTSET}. For the root logger only,
1492 \code{NOTSET} means that all messages will be logged. Level values are
1493 \function{eval()}uated in the context of the \code{logging} package's
1494 namespace.
1495
1496 The \code{handlers} entry is a comma-separated list of handler names,
1497 which must appear in the \code{[handlers]} section. These names must
1498 appear in the \code{[handlers]} section and have corresponding
1499 sections in the configuration file.
1500
1501 For loggers other than the root logger, some additional information is
1502 required. This is illustrated by the following example.
1503
1504 \begin{verbatim}
1505 [logger_parser]
1506 level=DEBUG
1507 handlers=hand01
1508 propagate=1
1509 qualname=compiler.parser
1510 \end{verbatim}
1511
1512 The \code{level} and \code{handlers} entries are interpreted as for
1513 the root logger, except that if a non-root logger's level is specified
1514 as \code{NOTSET}, the system consults loggers higher up the hierarchy
1515 to determine the effective level of the logger. The \code{propagate}
1516 entry is set to 1 to indicate that messages must propagate to handlers
1517 higher up the logger hierarchy from this logger, or 0 to indicate that
1518 messages are \strong{not} propagated to handlers up the hierarchy. The
1519 \code{qualname} entry is the hierarchical channel name of the logger,
1520 that is to say the name used by the application to get the logger.
1521
1522 Sections which specify handler configuration are exemplified by the
1523 following.
1524
1525 \begin{verbatim}
1526 [handler_hand01]
1527 class=StreamHandler
1528 level=NOTSET
1529 formatter=form01
1530 args=(sys.stdout,)
1531 \end{verbatim}
1532
1533 The \code{class} entry indicates the handler's class (as determined by
1534 \function{eval()} in the \code{logging} package's namespace). The
1535 \code{level} is interpreted as for loggers, and \code{NOTSET} is taken
1536 to mean "log everything".
1537
1538 The \code{formatter} entry indicates the key name of the formatter for
1539 this handler. If blank, a default formatter
1540 (\code{logging._defaultFormatter}) is used. If a name is specified, it
1541 must appear in the \code{[formatters]} section and have a
1542 corresponding section in the configuration file.
1543
1544 The \code{args} entry, when \function{eval()}uated in the context of
1545 the \code{logging} package's namespace, is the list of arguments to
1546 the constructor for the handler class. Refer to the constructors for
1547 the relevant handlers, or to the examples below, to see how typical
1548 entries are constructed.
1549
1550 \begin{verbatim}
1551 [handler_hand02]
1552 class=FileHandler
1553 level=DEBUG
1554 formatter=form02
1555 args=('python.log', 'w')
1556
1557 [handler_hand03]
1558 class=handlers.SocketHandler
1559 level=INFO
1560 formatter=form03
1561 args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
1562
1563 [handler_hand04]
1564 class=handlers.DatagramHandler
1565 level=WARN
1566 formatter=form04
1567 args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
1568
1569 [handler_hand05]
1570 class=handlers.SysLogHandler
1571 level=ERROR
1572 formatter=form05
1573 args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
1574
1575 [handler_hand06]
1576 class=handlers.NTEventLogHandler
1577 level=CRITICAL
1578 formatter=form06
1579 args=('Python Application', '', 'Application')
1580
1581 [handler_hand07]
1582 class=handlers.SMTPHandler
1583 level=WARN
1584 formatter=form07
1585 args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
1586
1587 [handler_hand08]
1588 class=handlers.MemoryHandler
1589 level=NOTSET
1590 formatter=form08
1591 target=
1592 args=(10, ERROR)
1593
1594 [handler_hand09]
1595 class=handlers.HTTPHandler
1596 level=NOTSET
1597 formatter=form09
1598 args=('localhost:9022', '/log', 'GET')
1599 \end{verbatim}
1600
1601 Sections which specify formatter configuration are typified by the following.
1602
1603 \begin{verbatim}
1604 [formatter_form01]
1605 format=F1 %(asctime)s %(levelname)s %(message)s
1606 datefmt=
1607 \end{verbatim}
1608
1609 The \code{format} entry is the overall format string, and the
1610 \code{datefmt} entry is the \function{strftime()}-compatible date/time format
1611 string. If empty, the package substitutes ISO8601 format date/times, which
1612 is almost equivalent to specifying the date format string "%Y-%m-%d %H:%M:%S".
1613 The ISO8601 format also specifies milliseconds, which are appended to the
1614 result of using the above format string, with a comma separator. An example
1615 time in ISO8601 format is \code{2003-01-23 00:29:50,411}.