1 \section{\module{logging
} ---
2 Logging facility for Python
}
4 \declaremodule{standard
}{logging
}
6 % These apply to all modules, and may be given more than once:
8 \moduleauthor{Vinay Sajip
}{vinay_sajip@red-dove.com
}
9 \sectionauthor{Vinay Sajip
}{vinay_sajip@red-dove.com
}
11 \modulesynopsis{Logging module for Python based on
\pep{282}.
}
13 \indexii{Errors
}{logging
}
16 This module defines functions and classes which implement a flexible
17 error logging system for applications.
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.
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.
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.
44 \begin{tableii
}{l|l
}{code
}{Level
}{Numeric value
}
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
61 Logging messages are encoded as instances of the
\class{LogRecord
} class.
62 When a logger decides to actually log an event, a
\class{LogRecord
}
63 instance is created from the logging message.
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.
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()
}.
84 In addition to the base
\class{Handler
} class, many useful subclasses
89 \item \class{StreamHandler
} instances send error messages to
90 streams (file-like objects).
92 \item \class{FileHandler
} instances send error messages to disk
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
}.
100 \item \class{RotatingFileHandler
} instances send error messages to disk
101 files, with support for maximum log file sizes and log file rotation.
103 \item \class{TimedRotatingFileHandler
} instances send error messages to
104 disk files rotating the log file at certain timed intervals.
106 \item \class{SocketHandler
} instances send error messages to
109 \item \class{DatagramHandler
} instances send error messages to UDP
112 \item \class{SMTPHandler
} instances send error messages to a
113 designated email address.
115 \item \class{SysLogHandler
} instances send error messages to a
116 \UNIX{} syslog daemon, possibly on a remote machine.
118 \item \class{NTEventLogHandler
} instances send error messages to a
119 Windows NT/
2000/XP event log.
121 \item \class{MemoryHandler
} instances send error messages to a
122 buffer in memory, which is flushed whenever specific criteria are
125 \item \class{HTTPHandler
} instances send error messages to an
126 HTTP server using either
\samp{GET
} or
\samp{POST
} semantics.
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.)
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.
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.
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.
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.
155 In addition to the classes described above, there are a number of module-
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.
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.
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:
177 class MyLogger(logging.getLoggerClass()):
178 # ... override behaviour here
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
} using the string formatting
187 operator. (Note that this means that you can use keywords in the
188 format string, together with a single dictionary argument.)
190 There are two keyword arguments in
\var{kwargs
} which are inspected:
191 \var{exc_info
} which, if it does not evaluate as false, causes exception
192 information to be added to the logging message. If an exception tuple (in the
193 format returned by
\function{sys.exc_info()
}) is provided, it is used;
194 otherwise,
\function{sys.exc_info()
} is called to get the exception
197 The other optional keyword argument is
\var{extra
} which can be used to pass
198 a dictionary which is used to populate the __dict__ of the LogRecord created
199 for the logging event with user-defined attributes. These custom attributes
200 can then be used as you like. For example, they could be incorporated into
201 logged messages. For example:
204 FORMAT = "
%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
205 logging.basicConfig(format=FORMAT)
206 dict =
{ 'clientip' : '
192.168.0.1', 'user' : 'fbloggs'
}
207 logging.warning("Protocol problem:
%s", "connection reset", extra=d)
210 would print something like
212 2006-
02-
08 22:
20:
02,
165 192.168.0.1 fbloggs Protocol problem: connection reset
215 The keys in the dictionary passed in
\var{extra
} should not clash with the keys
216 used by the logging system. (See the
\class{Formatter
} documentation for more
217 information on which keys are used by the logging system.)
219 If you choose to use these attributes in logged messages, you need to exercise
220 some care. In the above example, for instance, the
\class{Formatter
} has been
221 set up with a format string which expects 'clientip' and 'user' in the
222 attribute dictionary of the LogRecord. If these are missing, the message will
223 not be logged because a string formatting exception will occur. So in this
224 case, you always need to pass the
\var{extra
} dictionary with these keys.
226 While this might be annoying, this feature is intended for use in specialized
227 circumstances, such as multi-threaded servers where the same code executes
228 in many contexts, and interesting conditions which arise are dependent on this
229 context (such as remote client IP address and authenticated user name, in the
230 above example). In such circumstances, it is likely that specialized
231 \class{Formatter
}s would be used with particular
\class{Handler
}s.
233 \versionchanged[\var{extra
} was added
]{2.5}
237 \begin{funcdesc
}{info
}{msg
\optional{, *args
\optional{, **kwargs
}}}
238 Logs a message with level
\constant{INFO
} on the root logger.
239 The arguments are interpreted as for
\function{debug()
}.
242 \begin{funcdesc
}{warning
}{msg
\optional{, *args
\optional{, **kwargs
}}}
243 Logs a message with level
\constant{WARNING
} on the root logger.
244 The arguments are interpreted as for
\function{debug()
}.
247 \begin{funcdesc
}{error
}{msg
\optional{, *args
\optional{, **kwargs
}}}
248 Logs a message with level
\constant{ERROR
} on the root logger.
249 The arguments are interpreted as for
\function{debug()
}.
252 \begin{funcdesc
}{critical
}{msg
\optional{, *args
\optional{, **kwargs
}}}
253 Logs a message with level
\constant{CRITICAL
} on the root logger.
254 The arguments are interpreted as for
\function{debug()
}.
257 \begin{funcdesc
}{exception
}{msg
\optional{, *args
}}
258 Logs a message with level
\constant{ERROR
} on the root logger.
259 The arguments are interpreted as for
\function{debug()
}. Exception info
260 is added to the logging message. This function should only be called
261 from an exception handler.
264 \begin{funcdesc
}{log
}{level, msg
\optional{, *args
\optional{, **kwargs
}}}
265 Logs a message with level
\var{level
} on the root logger.
266 The other arguments are interpreted as for
\function{debug()
}.
269 \begin{funcdesc
}{disable
}{lvl
}
270 Provides an overriding level
\var{lvl
} for all loggers which takes
271 precedence over the logger's own level. When the need arises to
272 temporarily throttle logging output down across the whole application,
273 this function can be useful.
276 \begin{funcdesc
}{addLevelName
}{lvl, levelName
}
277 Associates level
\var{lvl
} with text
\var{levelName
} in an internal
278 dictionary, which is used to map numeric levels to a textual
279 representation, for example when a
\class{Formatter
} formats a message.
280 This function can also be used to define your own levels. The only
281 constraints are that all levels used must be registered using this
282 function, levels should be positive integers and they should increase
283 in increasing order of severity.
286 \begin{funcdesc
}{getLevelName
}{lvl
}
287 Returns the textual representation of logging level
\var{lvl
}. If the
288 level is one of the predefined levels
\constant{CRITICAL
},
289 \constant{ERROR
},
\constant{WARNING
},
\constant{INFO
} or
\constant{DEBUG
}
290 then you get the corresponding string. If you have associated levels
291 with names using
\function{addLevelName()
} then the name you have associated
292 with
\var{lvl
} is returned. If a numeric value corresponding to one of the
293 defined levels is passed in, the corresponding string representation is
294 returned. Otherwise, the string "Level \%s" \% lvl is returned.
297 \begin{funcdesc
}{makeLogRecord
}{attrdict
}
298 Creates and returns a new
\class{LogRecord
} instance whose attributes are
299 defined by
\var{attrdict
}. This function is useful for taking a pickled
300 \class{LogRecord
} attribute dictionary, sent over a socket, and reconstituting
301 it as a
\class{LogRecord
} instance at the receiving end.
304 \begin{funcdesc
}{basicConfig
}{\optional{**kwargs
}}
305 Does basic configuration for the logging system by creating a
306 \class{StreamHandler
} with a default
\class{Formatter
} and adding it to
307 the root logger. The functions
\function{debug()
},
\function{info()
},
308 \function{warning()
},
\function{error()
} and
\function{critical()
} will call
309 \function{basicConfig()
} automatically if no handlers are defined for the
312 \versionchanged[Formerly,
\function{basicConfig
} did not take any keyword
315 The following keyword arguments are supported.
317 \begin{tableii
}{l|l
}{code
}{Format
}{Description
}
318 \lineii{filename
}{Specifies that a FileHandler be created, using the
319 specified filename, rather than a StreamHandler.
}
320 \lineii{filemode
}{Specifies the mode to open the file, if filename is
321 specified (if filemode is unspecified, it defaults to 'a').
}
322 \lineii{format
}{Use the specified format string for the handler.
}
323 \lineii{datefmt
}{Use the specified date/time format.
}
324 \lineii{level
}{Set the root logger level to the specified level.
}
325 \lineii{stream
}{Use the specified stream to initialize the StreamHandler.
326 Note that this argument is incompatible with 'filename' - if both
327 are present, 'stream' is ignored.
}
332 \begin{funcdesc
}{shutdown
}{}
333 Informs the logging system to perform an orderly shutdown by flushing and
334 closing all handlers.
337 \begin{funcdesc
}{setLoggerClass
}{klass
}
338 Tells the logging system to use the class
\var{klass
} when instantiating a
339 logger. The class should define
\method{__init__()
} such that only a name
340 argument is required, and the
\method{__init__()
} should call
341 \method{Logger.__init__()
}. This function is typically called before any
342 loggers are instantiated by applications which need to use custom logger
348 \seepep{282}{A Logging System
}
349 {The proposal which described this feature for inclusion in
350 the Python standard library.
}
351 \seelink{http://www.red-dove.com/python_logging.html
}
352 {Original Python
\module{logging
} package
}
353 {This is the original source for the
\module{logging
}
354 package. The version of the package available from this
355 site is suitable for use with Python
1.5.2,
2.1.x and
2.2.x,
356 which do not include the
\module{logging
} package in the standard
361 \subsection{Logger Objects
}
363 Loggers have the following attributes and methods. Note that Loggers are
364 never instantiated directly, but always through the module-level function
365 \function{logging.getLogger(name)
}.
367 \begin{datadesc
}{propagate
}
368 If this evaluates to false, logging messages are not passed by this
369 logger or by child loggers to higher level (ancestor) loggers. The
370 constructor sets this attribute to
1.
373 \begin{methoddesc
}{setLevel
}{lvl
}
374 Sets the threshold for this logger to
\var{lvl
}. Logging messages
375 which are less severe than
\var{lvl
} will be ignored. When a logger is
376 created, the level is set to
\constant{NOTSET
} (which causes all messages
377 to be processed when the logger is the root logger, or delegation to the
378 parent when the logger is a non-root logger). Note that the root logger
379 is created with level
\constant{WARNING
}.
381 The term "delegation to the parent" means that if a logger has a level
382 of NOTSET, its chain of ancestor loggers is traversed until either an
383 ancestor with a level other than NOTSET is found, or the root is
386 If an ancestor is found with a level other than NOTSET, then that
387 ancestor's level is treated as the effective level of the logger where
388 the ancestor search began, and is used to determine how a logging
391 If the root is reached, and it has a level of NOTSET, then all
392 messages will be processed. Otherwise, the root's level will be used
393 as the effective level.
396 \begin{methoddesc
}{isEnabledFor
}{lvl
}
397 Indicates if a message of severity
\var{lvl
} would be processed by
398 this logger. This method checks first the module-level level set by
399 \function{logging.disable(lvl)
} and then the logger's effective level as
400 determined by
\method{getEffectiveLevel()
}.
403 \begin{methoddesc
}{getEffectiveLevel
}{}
404 Indicates the effective level for this logger. If a value other than
405 \constant{NOTSET
} has been set using
\method{setLevel()
}, it is returned.
406 Otherwise, the hierarchy is traversed towards the root until a value
407 other than
\constant{NOTSET
} is found, and that value is returned.
410 \begin{methoddesc
}{debug
}{msg
\optional{, *args
\optional{, **kwargs
}}}
411 Logs a message with level
\constant{DEBUG
} on this logger.
412 The
\var{msg
} is the message format string, and the
\var{args
} are the
413 arguments which are merged into
\var{msg
} using the string formatting
414 operator. (Note that this means that you can use keywords in the
415 format string, together with a single dictionary argument.)
417 There are two keyword arguments in
\var{kwargs
} which are inspected:
418 \var{exc_info
} which, if it does not evaluate as false, causes exception
419 information to be added to the logging message. If an exception tuple (in the
420 format returned by
\function{sys.exc_info()
}) is provided, it is used;
421 otherwise,
\function{sys.exc_info()
} is called to get the exception
424 The other optional keyword argument is
\var{extra
} which can be used to pass
425 a dictionary which is used to populate the __dict__ of the LogRecord created
426 for the logging event with user-defined attributes. These custom attributes
427 can then be used as you like. For example, they could be incorporated into
428 logged messages. For example:
431 FORMAT = "
%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
432 logging.basicConfig(format=FORMAT)
433 dict =
{ 'clientip' : '
192.168.0.1', 'user' : 'fbloggs'
}
434 logger = logging.getLogger("tcpserver")
435 logger.warning("Protocol problem:
%s", "connection reset", extra=d)
438 would print something like
440 2006-
02-
08 22:
20:
02,
165 192.168.0.1 fbloggs Protocol problem: connection reset
443 The keys in the dictionary passed in
\var{extra
} should not clash with the keys
444 used by the logging system. (See the
\class{Formatter
} documentation for more
445 information on which keys are used by the logging system.)
447 If you choose to use these attributes in logged messages, you need to exercise
448 some care. In the above example, for instance, the
\class{Formatter
} has been
449 set up with a format string which expects 'clientip' and 'user' in the
450 attribute dictionary of the LogRecord. If these are missing, the message will
451 not be logged because a string formatting exception will occur. So in this
452 case, you always need to pass the
\var{extra
} dictionary with these keys.
454 While this might be annoying, this feature is intended for use in specialized
455 circumstances, such as multi-threaded servers where the same code executes
456 in many contexts, and interesting conditions which arise are dependent on this
457 context (such as remote client IP address and authenticated user name, in the
458 above example). In such circumstances, it is likely that specialized
459 \class{Formatter
}s would be used with particular
\class{Handler
}s.
461 \versionchanged[\var{extra
} was added
]{2.5}
465 \begin{methoddesc
}{info
}{msg
\optional{, *args
\optional{, **kwargs
}}}
466 Logs a message with level
\constant{INFO
} on this logger.
467 The arguments are interpreted as for
\method{debug()
}.
470 \begin{methoddesc
}{warning
}{msg
\optional{, *args
\optional{, **kwargs
}}}
471 Logs a message with level
\constant{WARNING
} on this logger.
472 The arguments are interpreted as for
\method{debug()
}.
475 \begin{methoddesc
}{error
}{msg
\optional{, *args
\optional{, **kwargs
}}}
476 Logs a message with level
\constant{ERROR
} on this logger.
477 The arguments are interpreted as for
\method{debug()
}.
480 \begin{methoddesc
}{critical
}{msg
\optional{, *args
\optional{, **kwargs
}}}
481 Logs a message with level
\constant{CRITICAL
} on this logger.
482 The arguments are interpreted as for
\method{debug()
}.
485 \begin{methoddesc
}{log
}{lvl, msg
\optional{, *args
\optional{, **kwargs
}}}
486 Logs a message with integer level
\var{lvl
} on this logger.
487 The other arguments are interpreted as for
\method{debug()
}.
490 \begin{methoddesc
}{exception
}{msg
\optional{, *args
}}
491 Logs a message with level
\constant{ERROR
} on this logger.
492 The arguments are interpreted as for
\method{debug()
}. Exception info
493 is added to the logging message. This method should only be called
494 from an exception handler.
497 \begin{methoddesc
}{addFilter
}{filt
}
498 Adds the specified filter
\var{filt
} to this logger.
501 \begin{methoddesc
}{removeFilter
}{filt
}
502 Removes the specified filter
\var{filt
} from this logger.
505 \begin{methoddesc
}{filter
}{record
}
506 Applies this logger's filters to the record and returns a true value if
507 the record is to be processed.
510 \begin{methoddesc
}{addHandler
}{hdlr
}
511 Adds the specified handler
\var{hdlr
} to this logger.
514 \begin{methoddesc
}{removeHandler
}{hdlr
}
515 Removes the specified handler
\var{hdlr
} from this logger.
518 \begin{methoddesc
}{findCaller
}{}
519 Finds the caller's source filename and line number. Returns the filename,
520 line number and function name as a
3-element tuple.
521 \versionchanged[The function name was added. In earlier versions, the
522 filename and line number were returned as a
2-element tuple.
]{2.5}
525 \begin{methoddesc
}{handle
}{record
}
526 Handles a record by passing it to all handlers associated with this logger
527 and its ancestors (until a false value of
\var{propagate
} is found).
528 This method is used for unpickled records received from a socket, as well
529 as those created locally. Logger-level filtering is applied using
533 \begin{methoddesc
}{makeRecord
}{name, lvl, fn, lno, msg, args, exc_info
534 \optional{, func, extra
}}
535 This is a factory method which can be overridden in subclasses to create
536 specialized
\class{LogRecord
} instances.
537 \versionchanged[\var{func
} and
\var{extra
} were added
]{2.5}
540 \subsection{Basic example
\label{minimal-example
}}
542 \versionchanged[formerly
\function{basicConfig
} did not take any keyword
545 The
\module{logging
} package provides a lot of flexibility, and its
546 configuration can appear daunting. This section demonstrates that simple
547 use of the logging package is possible.
549 The simplest example shows logging to the console:
554 logging.debug('A debug message')
555 logging.info('Some information')
556 logging.warning('A shot across the bows')
559 If you run the above script, you'll see this:
561 WARNING:root:A shot across the bows
564 Because no particular logger was specified, the system used the root logger.
565 The debug and info messages didn't appear because by default, the root
566 logger is configured to only handle messages with a severity of WARNING
567 or above. The message format is also a configuration default, as is the output
568 destination of the messages -
\code{sys.stderr
}. The severity level,
569 the message format and destination can be easily changed, as shown in
575 logging.basicConfig(level=logging.DEBUG,
576 format='
%(asctime)s %(levelname)s %(message)s',
577 filename='/tmp/myapp.log',
579 logging.debug('A debug message')
580 logging.info('Some information')
581 logging.warning('A shot across the bows')
584 The
\method{basicConfig()
} method is used to change the configuration
585 defaults, which results in output (written to
\code{/tmp/myapp.log
})
586 which should look something like the following:
589 2004-
07-
02 13:
00:
08,
743 DEBUG A debug message
590 2004-
07-
02 13:
00:
08,
743 INFO Some information
591 2004-
07-
02 13:
00:
08,
743 WARNING A shot across the bows
594 This time, all messages with a severity of DEBUG or above were handled,
595 and the format of the messages was also changed, and output went to the
596 specified file rather than the console.
598 Formatting uses standard Python string formatting - see section
599 \ref{typesseq-strings
}. The format string takes the following
600 common specifiers. For a complete list of specifiers, consult the
601 \class{Formatter
} documentation.
603 \begin{tableii
}{l|l
}{code
}{Format
}{Description
}
604 \lineii{\%(name)s
} {Name of the logger (logging channel).
}
605 \lineii{\%(levelname)s
}{Text logging level for the message
606 (
\code{'DEBUG'
},
\code{'INFO'
},
607 \code{'WARNING'
},
\code{'ERROR'
},
609 \lineii{\%(asctime)s
} {Human-readable time when the
\class{LogRecord
}
610 was created. By default this is of the form
611 ``
2003-
07-
08 16:
49:
45,
896'' (the numbers after the
612 comma are millisecond portion of the time).
}
613 \lineii{\%(message)s
} {The logged message.
}
616 To change the date/time format, you can pass an additional keyword parameter,
617 \var{datefmt
}, as in the following:
622 logging.basicConfig(level=logging.DEBUG,
623 format='
%(asctime)s %(levelname)-8s %(message)s',
624 datefmt='
%a, %d %b %Y %H:%M:%S',
625 filename='/temp/myapp.log',
627 logging.debug('A debug message')
628 logging.info('Some information')
629 logging.warning('A shot across the bows')
632 which would result in output like
635 Fri,
02 Jul
2004 13:
06:
18 DEBUG A debug message
636 Fri,
02 Jul
2004 13:
06:
18 INFO Some information
637 Fri,
02 Jul
2004 13:
06:
18 WARNING A shot across the bows
640 The date format string follows the requirements of
\function{strftime()
} -
641 see the documentation for the
\refmodule{time
} module.
643 If, instead of sending logging output to the console or a file, you'd rather
644 use a file-like object which you have created separately, you can pass it
645 to
\function{basicConfig()
} using the
\var{stream
} keyword argument. Note
646 that if both
\var{stream
} and
\var{filename
} keyword arguments are passed,
647 the
\var{stream
} argument is ignored.
649 Of course, you can put variable information in your output. To do this,
650 simply have the message be a format string and pass in additional arguments
651 containing the variable information, as in the following example:
656 logging.basicConfig(level=logging.DEBUG,
657 format='
%(asctime)s %(levelname)-8s %(message)s',
658 datefmt='
%a, %d %b %Y %H:%M:%S',
659 filename='/temp/myapp.log',
661 logging.error('Pack my box with
%d dozen %s', 5, 'liquor jugs')
664 which would result in
667 Wed,
21 Jul
2004 15:
35:
16 ERROR Pack my box with
5 dozen liquor jugs
670 \subsection{Logging to multiple destinations
\label{multiple-destinations
}}
672 Let's say you want to log to console and file with different message formats
673 and in differing circumstances. Say you want to log messages with levels
674 of DEBUG and higher to file, and those messages at level INFO and higher to
675 the console. Let's also assume that the file should contain timestamps, but
676 the console messages should not. Here's how you can achieve this:
681 # set up logging to file - see previous section for more details
682 logging.basicConfig(level=logging.DEBUG,
683 format='
%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
684 datefmt='
%m-%d %H:%M',
685 filename='/temp/myapp.log',
687 # define a Handler which writes INFO messages or higher to the sys.stderr
688 console = logging.StreamHandler()
689 console.setLevel(logging.INFO)
690 # set a format which is simpler for console use
691 formatter = logging.Formatter('
%(name)-12s: %(levelname)-8s %(message)s')
692 # tell the handler to use this format
693 console.setFormatter(formatter)
694 # add the handler to the root logger
695 logging.getLogger('').addHandler(console)
697 # Now, we can log to the root logger, or any other logger. First the root...
698 logging.info('Jackdaws love my big sphinx of quartz.')
700 # Now, define a couple of other loggers which might represent areas in your
703 logger1 = logging.getLogger('myapp.area1')
704 logger2 = logging.getLogger('myapp.area2')
706 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
707 logger1.info('How quickly daft jumping zebras vex.')
708 logger2.warning('Jail zesty vixen who grabbed pay from quack.')
709 logger2.error('The five boxing wizards jump quickly.')
712 When you run this, on the console you will see
715 root : INFO Jackdaws love my big sphinx of quartz.
716 myapp.area1 : INFO How quickly daft jumping zebras vex.
717 myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.
718 myapp.area2 : ERROR The five boxing wizards jump quickly.
721 and in the file you will see something like
724 10-
22 22:
19 root INFO Jackdaws love my big sphinx of quartz.
725 10-
22 22:
19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
726 10-
22 22:
19 myapp.area1 INFO How quickly daft jumping zebras vex.
727 10-
22 22:
19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
728 10-
22 22:
19 myapp.area2 ERROR The five boxing wizards jump quickly.
731 As you can see, the DEBUG message only shows up in the file. The other
732 messages are sent to both destinations.
734 This example uses console and file handlers, but you can use any number and
735 combination of handlers you choose.
737 \subsection{Sending and receiving logging events across a network
738 \label{network-logging
}}
740 Let's say you want to send logging events across a network, and handle them
741 at the receiving end. A simple way of doing this is attaching a
742 \class{SocketHandler
} instance to the root logger at the sending end:
745 import logging, logging.handlers
747 rootLogger = logging.getLogger('')
748 rootLogger.setLevel(logging.DEBUG)
749 socketHandler = logging.handlers.SocketHandler('localhost',
750 logging.handlers.DEFAULT_TCP_LOGGING_PORT)
751 # don't bother with a formatter, since a socket handler sends the event as
752 # an unformatted pickle
753 rootLogger.addHandler(socketHandler)
755 # Now, we can log to the root logger, or any other logger. First the root...
756 logging.info('Jackdaws love my big sphinx of quartz.')
758 # Now, define a couple of other loggers which might represent areas in your
761 logger1 = logging.getLogger('myapp.area1')
762 logger2 = logging.getLogger('myapp.area2')
764 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
765 logger1.info('How quickly daft jumping zebras vex.')
766 logger2.warning('Jail zesty vixen who grabbed pay from quack.')
767 logger2.error('The five boxing wizards jump quickly.')
770 At the receiving end, you can set up a receiver using the
771 \module{SocketServer
} module. Here is a basic working example:
776 import logging.handlers
781 class LogRecordStreamHandler(SocketServer.StreamRequestHandler):
782 """Handler for a streaming logging request.
784 This basically logs the record using whatever logging policy is
790 Handle multiple requests - each expected to be a
4-byte length,
791 followed by the LogRecord in pickle format. Logs the record
792 according to whatever policy is configured locally.
795 chunk = self.connection.recv(
4)
798 slen = struct.unpack(">L", chunk)
[0]
799 chunk = self.connection.recv(slen)
800 while len(chunk) < slen:
801 chunk = chunk + self.connection.recv(slen - len(chunk))
802 obj = self.unPickle(chunk)
803 record = logging.makeLogRecord(obj)
804 self.handleLogRecord(record)
806 def unPickle(self, data):
807 return cPickle.loads(data)
809 def handleLogRecord(self, record):
810 # if a name is specified, we use the named logger rather than the one
811 # implied by the record.
812 if self.server.logname is not None:
813 name = self.server.logname
816 logger = logging.getLogger(name)
817 # N.B. EVERY record gets logged. This is because Logger.handle
818 # is normally called AFTER logger-level filtering. If you want
819 # to do filtering, do it at the client end to save wasting
820 # cycles and network bandwidth!
821 logger.handle(record)
823 class LogRecordSocketReceiver(SocketServer.ThreadingTCPServer):
824 """simple TCP socket-based logging receiver suitable for testing.
827 allow_reuse_address =
1
829 def __init__(self, host='localhost',
830 port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
831 handler=LogRecordStreamHandler):
832 SocketServer.ThreadingTCPServer.__init__(self, (host, port), handler)
837 def serve_until_stopped(self):
841 rd, wr, ex = select.select(
[self.socket.fileno()
],
845 self.handle_request()
850 format="
%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s")
851 tcpserver = LogRecordSocketReceiver()
852 print "About to start TCP server..."
853 tcpserver.serve_until_stopped()
855 if __name__ == "__main__":
859 First run the server, and then the client. On the client side, nothing is
860 printed on the console; on the server side, you should see something like:
863 About to start TCP server...
864 59 root INFO Jackdaws love my big sphinx of quartz.
865 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
866 69 myapp.area1 INFO How quickly daft jumping zebras vex.
867 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
868 69 myapp.area2 ERROR The five boxing wizards jump quickly.
871 \subsection{Handler Objects
}
873 Handlers have the following attributes and methods. Note that
874 \class{Handler
} is never instantiated directly; this class acts as a
875 base for more useful subclasses. However, the
\method{__init__()
}
876 method in subclasses needs to call
\method{Handler.__init__()
}.
878 \begin{methoddesc
}{__init__
}{level=
\constant{NOTSET
}}
879 Initializes the
\class{Handler
} instance by setting its level, setting
880 the list of filters to the empty list and creating a lock (using
881 \method{createLock()
}) for serializing access to an I/O mechanism.
884 \begin{methoddesc
}{createLock
}{}
885 Initializes a thread lock which can be used to serialize access to
886 underlying I/O functionality which may not be threadsafe.
889 \begin{methoddesc
}{acquire
}{}
890 Acquires the thread lock created with
\method{createLock()
}.
893 \begin{methoddesc
}{release
}{}
894 Releases the thread lock acquired with
\method{acquire()
}.
897 \begin{methoddesc
}{setLevel
}{lvl
}
898 Sets the threshold for this handler to
\var{lvl
}. Logging messages which are
899 less severe than
\var{lvl
} will be ignored. When a handler is created, the
900 level is set to
\constant{NOTSET
} (which causes all messages to be processed).
903 \begin{methoddesc
}{setFormatter
}{form
}
904 Sets the
\class{Formatter
} for this handler to
\var{form
}.
907 \begin{methoddesc
}{addFilter
}{filt
}
908 Adds the specified filter
\var{filt
} to this handler.
911 \begin{methoddesc
}{removeFilter
}{filt
}
912 Removes the specified filter
\var{filt
} from this handler.
915 \begin{methoddesc
}{filter
}{record
}
916 Applies this handler's filters to the record and returns a true value if
917 the record is to be processed.
920 \begin{methoddesc
}{flush
}{}
921 Ensure all logging output has been flushed. This version does
922 nothing and is intended to be implemented by subclasses.
925 \begin{methoddesc
}{close
}{}
926 Tidy up any resources used by the handler. This version does
927 nothing and is intended to be implemented by subclasses.
930 \begin{methoddesc
}{handle
}{record
}
931 Conditionally emits the specified logging record, depending on
932 filters which may have been added to the handler. Wraps the actual
933 emission of the record with acquisition/release of the I/O thread
937 \begin{methoddesc
}{handleError
}{record
}
938 This method should be called from handlers when an exception is
939 encountered during an
\method{emit()
} call. By default it does nothing,
940 which means that exceptions get silently ignored. This is what is
941 mostly wanted for a logging system - most users will not care
942 about errors in the logging system, they are more interested in
943 application errors. You could, however, replace this with a custom
944 handler if you wish. The specified record is the one which was being
945 processed when the exception occurred.
948 \begin{methoddesc
}{format
}{record
}
949 Do formatting for a record - if a formatter is set, use it.
950 Otherwise, use the default formatter for the module.
953 \begin{methoddesc
}{emit
}{record
}
954 Do whatever it takes to actually log the specified logging record.
955 This version is intended to be implemented by subclasses and so
956 raises a
\exception{NotImplementedError
}.
959 \subsubsection{StreamHandler
}
961 The
\class{StreamHandler
} class, located in the core
\module{logging
}
962 package, sends logging output to streams such as
\var{sys.stdout
},
963 \var{sys.stderr
} or any file-like object (or, more precisely, any
964 object which supports
\method{write()
} and
\method{flush()
} methods).
966 \begin{classdesc
}{StreamHandler
}{\optional{strm
}}
967 Returns a new instance of the
\class{StreamHandler
} class. If
\var{strm
} is
968 specified, the instance will use it for logging output; otherwise,
969 \var{sys.stderr
} will be used.
972 \begin{methoddesc
}{emit
}{record
}
973 If a formatter is specified, it is used to format the record.
974 The record is then written to the stream with a trailing newline.
975 If exception information is present, it is formatted using
976 \function{traceback.print_exception()
} and appended to the stream.
979 \begin{methoddesc
}{flush
}{}
980 Flushes the stream by calling its
\method{flush()
} method. Note that
981 the
\method{close()
} method is inherited from
\class{Handler
} and
982 so does nothing, so an explicit
\method{flush()
} call may be needed
986 \subsubsection{FileHandler
}
988 The
\class{FileHandler
} class, located in the core
\module{logging
}
989 package, sends logging output to a disk file. It inherits the output
990 functionality from
\class{StreamHandler
}.
992 \begin{classdesc
}{FileHandler
}{filename
\optional{, mode
\optional{, encoding
}}}
993 Returns a new instance of the
\class{FileHandler
} class. The specified
994 file is opened and used as the stream for logging. If
\var{mode
} is
995 not specified,
\constant{'a'
} is used. If
\var{encoding
} is not
\var{None
},
996 it is used to open the file with that encoding. By default, the file grows
1000 \begin{methoddesc
}{close
}{}
1004 \begin{methoddesc
}{emit
}{record
}
1005 Outputs the record to the file.
1008 \subsubsection{WatchedFileHandler
}
1011 The
\class{WatchedFileHandler
} class, located in the
\module{logging.handlers
}
1012 module, is a
\class{FileHandler
} which watches the file it is logging to.
1013 If the file changes, it is closed and reopened using the file name.
1015 A file change can happen because of usage of programs such as
\var{newsyslog
}
1016 and
\var{logrotate
} which perform log file rotation. This handler, intended
1017 for use under Unix/Linux, watches the file to see if it has changed since the
1018 last emit. (A file is deemed to have changed if its device or inode have
1019 changed.) If the file has changed, the old file stream is closed, and the file
1020 opened to get a new stream.
1022 This handler is not appropriate for use under Windows, because under Windows
1023 open log files cannot be moved or renamed - logging opens the files with
1024 exclusive locks - and so there is no need for such a handler. Furthermore,
1025 \var{ST_INO
} is not supported under Windows;
\function{stat()
} always returns
1026 zero for this value.
1028 \begin{classdesc
}{WatchedFileHandler
}{filename
\optional{,mode
\optional{,
1030 Returns a new instance of the
\class{WatchedFileHandler
} class. The specified
1031 file is opened and used as the stream for logging. If
\var{mode
} is
1032 not specified,
\constant{'a'
} is used. If
\var{encoding
} is not
\var{None
},
1033 it is used to open the file with that encoding. By default, the file grows
1037 \begin{methoddesc
}{emit
}{record
}
1038 Outputs the record to the file, but first checks to see if the file has
1039 changed. If it has, the existing stream is flushed and closed and the file
1040 opened again, before outputting the record to the file.
1043 \subsubsection{RotatingFileHandler
}
1045 The
\class{RotatingFileHandler
} class, located in the
\module{logging.handlers
}
1046 module, supports rotation of disk log files.
1048 \begin{classdesc
}{RotatingFileHandler
}{filename
\optional{, mode
\optional{,
1049 maxBytes
\optional{, backupCount
}}}}
1050 Returns a new instance of the
\class{RotatingFileHandler
} class. The
1051 specified file is opened and used as the stream for logging. If
1052 \var{mode
} is not specified,
\code{'a'
} is used. By default, the
1053 file grows indefinitely.
1055 You can use the
\var{maxBytes
} and
1056 \var{backupCount
} values to allow the file to
\dfn{rollover
} at a
1057 predetermined size. When the size is about to be exceeded, the file is
1058 closed and a new file is silently opened for output. Rollover occurs
1059 whenever the current log file is nearly
\var{maxBytes
} in length; if
1060 \var{maxBytes
} is zero, rollover never occurs. If
\var{backupCount
}
1061 is non-zero, the system will save old log files by appending the
1062 extensions "
.1", "
.2" etc., to the filename. For example, with
1063 a
\var{backupCount
} of
5 and a base file name of
1064 \file{app.log
}, you would get
\file{app.log
},
1065 \file{app.log
.1},
\file{app.log
.2}, up to
\file{app.log
.5}. The file being
1066 written to is always
\file{app.log
}. When this file is filled, it is
1067 closed and renamed to
\file{app.log
.1}, and if files
\file{app.log
.1},
1068 \file{app.log
.2}, etc. exist, then they are renamed to
\file{app.log
.2},
1069 \file{app.log
.3} etc. respectively.
1072 \begin{methoddesc
}{doRollover
}{}
1073 Does a rollover, as described above.
1076 \begin{methoddesc
}{emit
}{record
}
1077 Outputs the record to the file, catering for rollover as described previously.
1080 \subsubsection{TimedRotatingFileHandler
}
1082 The
\class{TimedRotatingFileHandler
} class, located in the
1083 \module{logging.handlers
} module, supports rotation of disk log files
1084 at certain timed intervals.
1086 \begin{classdesc
}{TimedRotatingFileHandler
}{filename
1089 \optional{,backupCount
}}}}
1091 Returns a new instance of the
\class{TimedRotatingFileHandler
} class. The
1092 specified file is opened and used as the stream for logging. On rotating
1093 it also sets the filename suffix. Rotating happens based on the product
1094 of
\var{when
} and
\var{interval
}.
1096 You can use the
\var{when
} to specify the type of
\var{interval
}. The
1097 list of possible values is, note that they are not case sensitive:
1099 \begin{tableii
}{l|l
}{}{Value
}{Type of interval
}
1104 \lineii{W
}{Week day (
0=Monday)
}
1105 \lineii{midnight
}{Roll over at midnight
}
1108 If
\var{backupCount
} is non-zero, the system will save old log files by
1109 appending extensions to the filename. The extensions are date-and-time
1110 based, using the strftime format
\code{\%Y-\%m-\%d_\%H-\%M-\%S
} or a leading
1111 portion thereof, depending on the rollover interval. At most
\var{backupCount
}
1112 files will be kept, and if more would be created when rollover occurs, the
1113 oldest one is deleted.
1116 \begin{methoddesc
}{doRollover
}{}
1117 Does a rollover, as described above.
1120 \begin{methoddesc
}{emit
}{record
}
1121 Outputs the record to the file, catering for rollover as described
1125 \subsubsection{SocketHandler
}
1127 The
\class{SocketHandler
} class, located in the
1128 \module{logging.handlers
} module, sends logging output to a network
1129 socket. The base class uses a TCP socket.
1131 \begin{classdesc
}{SocketHandler
}{host, port
}
1132 Returns a new instance of the
\class{SocketHandler
} class intended to
1133 communicate with a remote machine whose address is given by
\var{host
}
1137 \begin{methoddesc
}{close
}{}
1141 \begin{methoddesc
}{handleError
}{}
1144 \begin{methoddesc
}{emit
}{}
1145 Pickles the record's attribute dictionary and writes it to the socket in
1146 binary format. If there is an error with the socket, silently drops the
1147 packet. If the connection was previously lost, re-establishes the connection.
1148 To unpickle the record at the receiving end into a
\class{LogRecord
}, use the
1149 \function{makeLogRecord()
} function.
1152 \begin{methoddesc
}{handleError
}{}
1153 Handles an error which has occurred during
\method{emit()
}. The
1154 most likely cause is a lost connection. Closes the socket so that
1155 we can retry on the next event.
1158 \begin{methoddesc
}{makeSocket
}{}
1159 This is a factory method which allows subclasses to define the precise
1160 type of socket they want. The default implementation creates a TCP
1161 socket (
\constant{socket.SOCK_STREAM
}).
1164 \begin{methoddesc
}{makePickle
}{record
}
1165 Pickles the record's attribute dictionary in binary format with a length
1166 prefix, and returns it ready for transmission across the socket.
1169 \begin{methoddesc
}{send
}{packet
}
1170 Send a pickled string
\var{packet
} to the socket. This function allows
1171 for partial sends which can happen when the network is busy.
1174 \subsubsection{DatagramHandler
}
1176 The
\class{DatagramHandler
} class, located in the
1177 \module{logging.handlers
} module, inherits from
\class{SocketHandler
}
1178 to support sending logging messages over UDP sockets.
1180 \begin{classdesc
}{DatagramHandler
}{host, port
}
1181 Returns a new instance of the
\class{DatagramHandler
} class intended to
1182 communicate with a remote machine whose address is given by
\var{host
}
1186 \begin{methoddesc
}{emit
}{}
1187 Pickles the record's attribute dictionary and writes it to the socket in
1188 binary format. If there is an error with the socket, silently drops the
1190 To unpickle the record at the receiving end into a
\class{LogRecord
}, use the
1191 \function{makeLogRecord()
} function.
1194 \begin{methoddesc
}{makeSocket
}{}
1195 The factory method of
\class{SocketHandler
} is here overridden to create
1196 a UDP socket (
\constant{socket.SOCK_DGRAM
}).
1199 \begin{methoddesc
}{send
}{s
}
1200 Send a pickled string to a socket.
1203 \subsubsection{SysLogHandler
}
1205 The
\class{SysLogHandler
} class, located in the
1206 \module{logging.handlers
} module, supports sending logging messages to
1207 a remote or local
\UNIX{} syslog.
1209 \begin{classdesc
}{SysLogHandler
}{\optional{address
\optional{, facility
}}}
1210 Returns a new instance of the
\class{SysLogHandler
} class intended to
1211 communicate with a remote
\UNIX{} machine whose address is given by
1212 \var{address
} in the form of a
\code{(
\var{host
},
\var{port
})
}
1213 tuple. If
\var{address
} is not specified,
\code{('localhost',
514)
} is
1214 used. The address is used to open a UDP socket. If
\var{facility
} is
1215 not specified,
\constant{LOG_USER
} is used.
1218 \begin{methoddesc
}{close
}{}
1219 Closes the socket to the remote host.
1222 \begin{methoddesc
}{emit
}{record
}
1223 The record is formatted, and then sent to the syslog server. If
1224 exception information is present, it is
\emph{not
} sent to the server.
1227 \begin{methoddesc
}{encodePriority
}{facility, priority
}
1228 Encodes the facility and priority into an integer. You can pass in strings
1229 or integers - if strings are passed, internal mapping dictionaries are used
1230 to convert them to integers.
1233 \subsubsection{NTEventLogHandler
}
1235 The
\class{NTEventLogHandler
} class, located in the
1236 \module{logging.handlers
} module, supports sending logging messages to
1237 a local Windows NT, Windows
2000 or Windows XP event log. Before you
1238 can use it, you need Mark Hammond's Win32 extensions for Python
1241 \begin{classdesc
}{NTEventLogHandler
}{appname
\optional{,
1242 dllname
\optional{, logtype
}}}
1243 Returns a new instance of the
\class{NTEventLogHandler
} class. The
1244 \var{appname
} is used to define the application name as it appears in the
1245 event log. An appropriate registry entry is created using this name.
1246 The
\var{dllname
} should give the fully qualified pathname of a .dll or .exe
1247 which contains message definitions to hold in the log (if not specified,
1248 \code{'win32service.pyd'
} is used - this is installed with the Win32
1249 extensions and contains some basic placeholder message definitions.
1250 Note that use of these placeholders will make your event logs big, as the
1251 entire message source is held in the log. If you want slimmer logs, you have
1252 to pass in the name of your own .dll or .exe which contains the message
1253 definitions you want to use in the event log). The
\var{logtype
} is one of
1254 \code{'Application'
},
\code{'System'
} or
\code{'Security'
}, and
1255 defaults to
\code{'Application'
}.
1258 \begin{methoddesc
}{close
}{}
1259 At this point, you can remove the application name from the registry as a
1260 source of event log entries. However, if you do this, you will not be able
1261 to see the events as you intended in the Event Log Viewer - it needs to be
1262 able to access the registry to get the .dll name. The current version does
1263 not do this (in fact it doesn't do anything).
1266 \begin{methoddesc
}{emit
}{record
}
1267 Determines the message ID, event category and event type, and then logs the
1268 message in the NT event log.
1271 \begin{methoddesc
}{getEventCategory
}{record
}
1272 Returns the event category for the record. Override this if you
1273 want to specify your own categories. This version returns
0.
1276 \begin{methoddesc
}{getEventType
}{record
}
1277 Returns the event type for the record. Override this if you want
1278 to specify your own types. This version does a mapping using the
1279 handler's typemap attribute, which is set up in
\method{__init__()
}
1280 to a dictionary which contains mappings for
\constant{DEBUG
},
1281 \constant{INFO
},
\constant{WARNING
},
\constant{ERROR
} and
1282 \constant{CRITICAL
}. If you are using your own levels, you will either need
1283 to override this method or place a suitable dictionary in the
1284 handler's
\var{typemap
} attribute.
1287 \begin{methoddesc
}{getMessageID
}{record
}
1288 Returns the message ID for the record. If you are using your
1289 own messages, you could do this by having the
\var{msg
} passed to the
1290 logger being an ID rather than a format string. Then, in here,
1291 you could use a dictionary lookup to get the message ID. This
1292 version returns
1, which is the base message ID in
1293 \file{win32service.pyd
}.
1296 \subsubsection{SMTPHandler
}
1298 The
\class{SMTPHandler
} class, located in the
1299 \module{logging.handlers
} module, supports sending logging messages to
1300 an email address via SMTP.
1302 \begin{classdesc
}{SMTPHandler
}{mailhost, fromaddr, toaddrs, subject
}
1303 Returns a new instance of the
\class{SMTPHandler
} class. The
1304 instance is initialized with the from and to addresses and subject
1305 line of the email. The
\var{toaddrs
} should be a list of strings. To specify a
1306 non-standard SMTP port, use the (host, port) tuple format for the
1307 \var{mailhost
} argument. If you use a string, the standard SMTP port
1311 \begin{methoddesc
}{emit
}{record
}
1312 Formats the record and sends it to the specified addressees.
1315 \begin{methoddesc
}{getSubject
}{record
}
1316 If you want to specify a subject line which is record-dependent,
1317 override this method.
1320 \subsubsection{MemoryHandler
}
1322 The
\class{MemoryHandler
} class, located in the
1323 \module{logging.handlers
} module, supports buffering of logging
1324 records in memory, periodically flushing them to a
\dfn{target
}
1325 handler. Flushing occurs whenever the buffer is full, or when an event
1326 of a certain severity or greater is seen.
1328 \class{MemoryHandler
} is a subclass of the more general
1329 \class{BufferingHandler
}, which is an abstract class. This buffers logging
1330 records in memory. Whenever each record is added to the buffer, a
1331 check is made by calling
\method{shouldFlush()
} to see if the buffer
1332 should be flushed. If it should, then
\method{flush()
} is expected to
1335 \begin{classdesc
}{BufferingHandler
}{capacity
}
1336 Initializes the handler with a buffer of the specified capacity.
1339 \begin{methoddesc
}{emit
}{record
}
1340 Appends the record to the buffer. If
\method{shouldFlush()
} returns true,
1341 calls
\method{flush()
} to process the buffer.
1344 \begin{methoddesc
}{flush
}{}
1345 You can override this to implement custom flushing behavior. This version
1346 just zaps the buffer to empty.
1349 \begin{methoddesc
}{shouldFlush
}{record
}
1350 Returns true if the buffer is up to capacity. This method can be
1351 overridden to implement custom flushing strategies.
1354 \begin{classdesc
}{MemoryHandler
}{capacity
\optional{, flushLevel
1355 \optional{, target
}}}
1356 Returns a new instance of the
\class{MemoryHandler
} class. The
1357 instance is initialized with a buffer size of
\var{capacity
}. If
1358 \var{flushLevel
} is not specified,
\constant{ERROR
} is used. If no
1359 \var{target
} is specified, the target will need to be set using
1360 \method{setTarget()
} before this handler does anything useful.
1363 \begin{methoddesc
}{close
}{}
1364 Calls
\method{flush()
}, sets the target to
\constant{None
} and
1368 \begin{methoddesc
}{flush
}{}
1369 For a
\class{MemoryHandler
}, flushing means just sending the buffered
1370 records to the target, if there is one. Override if you want
1374 \begin{methoddesc
}{setTarget
}{target
}
1375 Sets the target handler for this handler.
1378 \begin{methoddesc
}{shouldFlush
}{record
}
1379 Checks for buffer full or a record at the
\var{flushLevel
} or higher.
1382 \subsubsection{HTTPHandler
}
1384 The
\class{HTTPHandler
} class, located in the
1385 \module{logging.handlers
} module, supports sending logging messages to
1386 a Web server, using either
\samp{GET
} or
\samp{POST
} semantics.
1388 \begin{classdesc
}{HTTPHandler
}{host, url
\optional{, method
}}
1389 Returns a new instance of the
\class{HTTPHandler
} class. The
1390 instance is initialized with a host address, url and HTTP method.
1391 The
\var{host
} can be of the form
\code{host:port
}, should you need to
1392 use a specific port number. If no
\var{method
} is specified,
\samp{GET
}
1396 \begin{methoddesc
}{emit
}{record
}
1397 Sends the record to the Web server as an URL-encoded dictionary.
1400 \subsection{Formatter Objects
}
1402 \class{Formatter
}s have the following attributes and methods. They are
1403 responsible for converting a
\class{LogRecord
} to (usually) a string
1404 which can be interpreted by either a human or an external system. The
1406 \class{Formatter
} allows a formatting string to be specified. If none is
1407 supplied, the default value of
\code{'\%(message)s'
} is used.
1409 A Formatter can be initialized with a format string which makes use of
1410 knowledge of the
\class{LogRecord
} attributes - such as the default value
1411 mentioned above making use of the fact that the user's message and
1412 arguments are pre-formatted into a
\class{LogRecord
}'s
\var{message
}
1413 attribute. This format string contains standard python \%-style
1414 mapping keys. See section
\ref{typesseq-strings
}, ``String Formatting
1415 Operations,'' for more information on string formatting.
1417 Currently, the useful mapping keys in a
\class{LogRecord
} are:
1419 \begin{tableii
}{l|l
}{code
}{Format
}{Description
}
1420 \lineii{\%(name)s
} {Name of the logger (logging channel).
}
1421 \lineii{\%(levelno)s
} {Numeric logging level for the message
1422 (
\constant{DEBUG
},
\constant{INFO
},
1423 \constant{WARNING
},
\constant{ERROR
},
1424 \constant{CRITICAL
}).
}
1425 \lineii{\%(levelname)s
}{Text logging level for the message
1426 (
\code{'DEBUG'
},
\code{'INFO'
},
1427 \code{'WARNING'
},
\code{'ERROR'
},
1428 \code{'CRITICAL'
}).
}
1429 \lineii{\%(pathname)s
} {Full pathname of the source file where the logging
1430 call was issued (if available).
}
1431 \lineii{\%(filename)s
} {Filename portion of pathname.
}
1432 \lineii{\%(module)s
} {Module (name portion of filename).
}
1433 \lineii{\%(funcName)s
} {Name of function containing the logging call.
}
1434 \lineii{\%(lineno)d
} {Source line number where the logging call was issued
1436 \lineii{\%(created)f
} {Time when the
\class{LogRecord
} was created (as
1437 returned by
\function{time.time()
}).
}
1438 \lineii{\%(relativeCreated)d
} {Time in milliseconds when the LogRecord was
1439 created, relative to the time the logging module was
1441 \lineii{\%(asctime)s
} {Human-readable time when the
\class{LogRecord
}
1442 was created. By default this is of the form
1443 ``
2003-
07-
08 16:
49:
45,
896'' (the numbers after the
1444 comma are millisecond portion of the time).
}
1445 \lineii{\%(msecs)d
} {Millisecond portion of the time when the
1446 \class{LogRecord
} was created.
}
1447 \lineii{\%(thread)d
} {Thread ID (if available).
}
1448 \lineii{\%(threadName)s
} {Thread name (if available).
}
1449 \lineii{\%(process)d
} {Process ID (if available).
}
1450 \lineii{\%(message)s
} {The logged message, computed as
\code{msg \% args
}.
}
1453 \versionchanged[\var{funcName
} was added
]{2.5}
1455 \begin{classdesc
}{Formatter
}{\optional{fmt
\optional{, datefmt
}}}
1456 Returns a new instance of the
\class{Formatter
} class. The
1457 instance is initialized with a format string for the message as a whole,
1458 as well as a format string for the date/time portion of a message. If
1459 no
\var{fmt
} is specified,
\code{'\%(message)s'
} is used. If no
\var{datefmt
}
1460 is specified, the ISO8601 date format is used.
1463 \begin{methoddesc
}{format
}{record
}
1464 The record's attribute dictionary is used as the operand to a
1465 string formatting operation. Returns the resulting string.
1466 Before formatting the dictionary, a couple of preparatory steps
1467 are carried out. The
\var{message
} attribute of the record is computed
1468 using
\var{msg
} \%
\var{args
}. If the formatting string contains
1469 \code{'(asctime)'
},
\method{formatTime()
} is called to format the
1470 event time. If there is exception information, it is formatted using
1471 \method{formatException()
} and appended to the message.
1474 \begin{methoddesc
}{formatTime
}{record
\optional{, datefmt
}}
1475 This method should be called from
\method{format()
} by a formatter which
1476 wants to make use of a formatted time. This method can be overridden
1477 in formatters to provide for any specific requirement, but the
1478 basic behavior is as follows: if
\var{datefmt
} (a string) is specified,
1479 it is used with
\function{time.strftime()
} to format the creation time of the
1480 record. Otherwise, the ISO8601 format is used. The resulting
1484 \begin{methoddesc
}{formatException
}{exc_info
}
1485 Formats the specified exception information (a standard exception tuple
1486 as returned by
\function{sys.exc_info()
}) as a string. This default
1487 implementation just uses
\function{traceback.print_exception()
}.
1488 The resulting string is returned.
1491 \subsection{Filter Objects
}
1493 \class{Filter
}s can be used by
\class{Handler
}s and
\class{Logger
}s for
1494 more sophisticated filtering than is provided by levels. The base filter
1495 class only allows events which are below a certain point in the logger
1496 hierarchy. For example, a filter initialized with "A.B" will allow events
1497 logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB",
1498 "B.A.B" etc. If initialized with the empty string, all events are passed.
1500 \begin{classdesc
}{Filter
}{\optional{name
}}
1501 Returns an instance of the
\class{Filter
} class. If
\var{name
} is specified,
1502 it names a logger which, together with its children, will have its events
1503 allowed through the filter. If no name is specified, allows every event.
1506 \begin{methoddesc
}{filter
}{record
}
1507 Is the specified record to be logged? Returns zero for no, nonzero for
1508 yes. If deemed appropriate, the record may be modified in-place by this
1512 \subsection{LogRecord Objects
}
1514 \class{LogRecord
} instances are created every time something is logged. They
1515 contain all the information pertinent to the event being logged. The
1516 main information passed in is in msg and args, which are combined
1517 using msg \% args to create the message field of the record. The record
1518 also includes information such as when the record was created, the
1519 source line where the logging call was made, and any exception
1520 information to be logged.
1522 \begin{classdesc
}{LogRecord
}{name, lvl, pathname, lineno, msg, args,
1523 exc_info
\optional{, func
}}
1524 Returns an instance of
\class{LogRecord
} initialized with interesting
1525 information. The
\var{name
} is the logger name;
\var{lvl
} is the
1526 numeric level;
\var{pathname
} is the absolute pathname of the source
1527 file in which the logging call was made;
\var{lineno
} is the line
1528 number in that file where the logging call is found;
\var{msg
} is the
1529 user-supplied message (a format string);
\var{args
} is the tuple
1530 which, together with
\var{msg
}, makes up the user message; and
1531 \var{exc_info
} is the exception tuple obtained by calling
1532 \function{sys.exc_info()
}(or
\constant{None
}, if no exception information
1533 is available). The
\var{func
} is the name of the function from which the
1534 logging call was made. If not specified, it defaults to
\var{None
}.
1535 \versionchanged[\var{func
} was added
]{2.5}
1538 \begin{methoddesc
}{getMessage
}{}
1539 Returns the message for this
\class{LogRecord
} instance after merging any
1540 user-supplied arguments with the message.
1543 \subsection{Thread Safety
}
1545 The logging module is intended to be thread-safe without any special work
1546 needing to be done by its clients. It achieves this though using threading
1547 locks; there is one lock to serialize access to the module's shared data,
1548 and each handler also creates a lock to serialize access to its underlying
1551 \subsection{Configuration
}
1554 \subsubsection{Configuration functions
%
1555 \label{logging-config-api
}}
1557 The following functions configure the logging module. They are located in the
1558 \module{logging.config
} module. Their use is optional --- you can configure
1559 the logging module using these functions or by making calls to the
1560 main API (defined in
\module{logging
} itself) and defining handlers
1561 which are declared either in
\module{logging
} or
1562 \module{logging.handlers
}.
1564 \begin{funcdesc
}{fileConfig
}{fname
\optional{, defaults
}}
1565 Reads the logging configuration from a ConfigParser-format file named
1566 \var{fname
}. This function can be called several times from an application,
1567 allowing an end user the ability to select from various pre-canned
1568 configurations (if the developer provides a mechanism to present the
1569 choices and load the chosen configuration). Defaults to be passed to
1570 ConfigParser can be specified in the
\var{defaults
} argument.
1573 \begin{funcdesc
}{listen
}{\optional{port
}}
1574 Starts up a socket server on the specified port, and listens for new
1575 configurations. If no port is specified, the module's default
1576 \constant{DEFAULT_LOGGING_CONFIG_PORT
} is used. Logging configurations
1577 will be sent as a file suitable for processing by
\function{fileConfig()
}.
1578 Returns a
\class{Thread
} instance on which you can call
\method{start()
}
1579 to start the server, and which you can
\method{join()
} when appropriate.
1580 To stop the server, call
\function{stopListening()
}. To send a configuration
1581 to the socket, read in the configuration file and send it to the socket
1582 as a string of bytes preceded by a four-byte length packed in binary using
1583 struct.
\code{pack('>L', n)
}.
1586 \begin{funcdesc
}{stopListening
}{}
1587 Stops the listening server which was created with a call to
1588 \function{listen()
}. This is typically called before calling
\method{join()
}
1589 on the return value from
\function{listen()
}.
1592 \subsubsection{Configuration file format
%
1593 \label{logging-config-fileformat
}}
1595 The configuration file format understood by
\function{fileConfig()
} is
1596 based on ConfigParser functionality. The file must contain sections
1597 called
\code{[loggers
]},
\code{[handlers
]} and
\code{[formatters
]}
1598 which identify by name the entities of each type which are defined in
1599 the file. For each such entity, there is a separate section which
1600 identified how that entity is configured. Thus, for a logger named
1601 \code{log01
} in the
\code{[loggers
]} section, the relevant
1602 configuration details are held in a section
1603 \code{[logger_log01
]}. Similarly, a handler called
\code{hand01
} in
1604 the
\code{[handlers
]} section will have its configuration held in a
1605 section called
\code{[handler_hand01
]}, while a formatter called
1606 \code{form01
} in the
\code{[formatters
]} section will have its
1607 configuration specified in a section called
1608 \code{[formatter_form01
]}. The root logger configuration must be
1609 specified in a section called
\code{[logger_root
]}.
1611 Examples of these sections in the file are given below.
1615 keys=root,log02,log03,log04,log05,log06,log07
1618 keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
1621 keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
1624 The root logger must specify a level and a list of handlers. An
1625 example of a root logger section is given below.
1633 The
\code{level
} entry can be one of
\code{DEBUG, INFO, WARNING,
1634 ERROR, CRITICAL
} or
\code{NOTSET
}. For the root logger only,
1635 \code{NOTSET
} means that all messages will be logged. Level values are
1636 \function{eval()
}uated in the context of the
\code{logging
} package's
1639 The
\code{handlers
} entry is a comma-separated list of handler names,
1640 which must appear in the
\code{[handlers
]} section. These names must
1641 appear in the
\code{[handlers
]} section and have corresponding
1642 sections in the configuration file.
1644 For loggers other than the root logger, some additional information is
1645 required. This is illustrated by the following example.
1652 qualname=compiler.parser
1655 The
\code{level
} and
\code{handlers
} entries are interpreted as for
1656 the root logger, except that if a non-root logger's level is specified
1657 as
\code{NOTSET
}, the system consults loggers higher up the hierarchy
1658 to determine the effective level of the logger. The
\code{propagate
}
1659 entry is set to
1 to indicate that messages must propagate to handlers
1660 higher up the logger hierarchy from this logger, or
0 to indicate that
1661 messages are
\strong{not
} propagated to handlers up the hierarchy. The
1662 \code{qualname
} entry is the hierarchical channel name of the logger,
1663 that is to say the name used by the application to get the logger.
1665 Sections which specify handler configuration are exemplified by the
1676 The
\code{class
} entry indicates the handler's class (as determined by
1677 \function{eval()
} in the
\code{logging
} package's namespace). The
1678 \code{level
} is interpreted as for loggers, and
\code{NOTSET
} is taken
1679 to mean "log everything".
1681 The
\code{formatter
} entry indicates the key name of the formatter for
1682 this handler. If blank, a default formatter
1683 (
\code{logging._defaultFormatter
}) is used. If a name is specified, it
1684 must appear in the
\code{[formatters
]} section and have a
1685 corresponding section in the configuration file.
1687 The
\code{args
} entry, when
\function{eval()
}uated in the context of
1688 the
\code{logging
} package's namespace, is the list of arguments to
1689 the constructor for the handler class. Refer to the constructors for
1690 the relevant handlers, or to the examples below, to see how typical
1691 entries are constructed.
1698 args=('python.log', 'w')
1701 class=handlers.SocketHandler
1704 args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
1707 class=handlers.DatagramHandler
1710 args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
1713 class=handlers.SysLogHandler
1716 args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
1719 class=handlers.NTEventLogHandler
1722 args=('Python Application', '', 'Application')
1725 class=handlers.SMTPHandler
1728 args=('localhost', 'from@abc',
['user1@abc', 'user2@xyz'
], 'Logger Subject')
1731 class=handlers.MemoryHandler
1738 class=handlers.HTTPHandler
1741 args=('localhost:
9022', '/log', 'GET')
1744 Sections which specify formatter configuration are typified by the following.
1748 format=F1
%(asctime)s %(levelname)s %(message)s
1750 class=logging.Formatter
1753 The
\code{format
} entry is the overall format string, and the
1754 \code{datefmt
} entry is the
\function{strftime()
}-compatible date/time format
1755 string. If empty, the package substitutes ISO8601 format date/times, which
1756 is almost equivalent to specifying the date format string "
%Y-%m-%d %H:%M:%S".
1757 The ISO8601 format also specifies milliseconds, which are appended to the
1758 result of using the above format string, with a comma separator. An example
1759 time in ISO8601 format is
\code{2003-
01-
23 00:
29:
50,
411}.
1761 The
\code{class
} entry is optional. It indicates the name of the
1762 formatter's class (as a dotted module and class name.) This option is
1763 useful for instantiating a
\class{Formatter
} subclass. Subclasses of
1764 \class{Formatter
} can present exception tracebacks in an expanded or