blob: 2e857d9518f7b557c44d36e9dfbcaf4695166ccf [file] [log] [blame]
Skip Montanaro649698f2002-11-14 03:57:19 +00001\section{\module{logging} ---
2 Logging facility for Python}
3
Fred Drake9a5b6a62003-07-08 15:38:40 +00004\declaremodule{standard}{logging}
Skip Montanaro649698f2002-11-14 03:57:19 +00005
6% These apply to all modules, and may be given more than once:
7
8\moduleauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00009\sectionauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
Skip Montanaro649698f2002-11-14 03:57:19 +000010
Fred Drake68e6d572003-01-28 22:02:35 +000011\modulesynopsis{Logging module for Python based on \pep{282}.}
Skip Montanaro649698f2002-11-14 03:57:19 +000012
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000013\indexii{Errors}{logging}
Skip Montanaro649698f2002-11-14 03:57:19 +000014
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000015\versionadded{2.3}
16This module defines functions and classes which implement a flexible
17error logging system for applications.
Skip Montanaro649698f2002-11-14 03:57:19 +000018
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000019Logging is performed by calling methods on instances of the
20\class{Logger} class (hereafter called \dfn{loggers}). Each instance has a
21name, and they are conceptually arranged in a name space hierarchy
22using dots (periods) as separators. For example, a logger named
23"scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf".
24Logger names can be anything you want, and indicate the area of an
25application in which a logged message originates.
Skip Montanaro649698f2002-11-14 03:57:19 +000026
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000027Logged messages also have levels of importance associated with them.
28The default levels provided are \constant{DEBUG}, \constant{INFO},
29\constant{WARNING}, \constant{ERROR} and \constant{CRITICAL}. As a
30convenience, you indicate the importance of a logged message by calling
31an appropriate method of \class{Logger}. The methods are
Fred Drakec23e0192003-01-28 22:09:16 +000032\method{debug()}, \method{info()}, \method{warning()}, \method{error()} and
33\method{critical()}, which mirror the default levels. You are not
34constrained to use these levels: you can specify your own and use a
35more general \class{Logger} method, \method{log()}, which takes an
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000036explicit level argument.
Skip Montanaro649698f2002-11-14 03:57:19 +000037
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000038Levels can also be associated with loggers, being set either by the
39developer or through loading a saved logging configuration. When a
40logging method is called on a logger, the logger compares its own
41level with the level associated with the method call. If the logger's
42level is higher than the method call's, no logging message is actually
43generated. This is the basic mechanism controlling the verbosity of
44logging output.
Skip Montanaro649698f2002-11-14 03:57:19 +000045
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000046Logging messages are encoded as instances of the \class{LogRecord} class.
47When a logger decides to actually log an event, an \class{LogRecord}
48instance is created from the logging message.
Skip Montanaro649698f2002-11-14 03:57:19 +000049
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000050Logging messages are subjected to a dispatch mechanism through the
51use of \dfn{handlers}, which are instances of subclasses of the
52\class{Handler} class. Handlers are responsible for ensuring that a logged
53message (in the form of a \class{LogRecord}) ends up in a particular
54location (or set of locations) which is useful for the target audience for
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +000055that message (such as end users, support desk staff, system administrators,
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000056developers). Handlers are passed \class{LogRecord} instances intended for
57particular destinations. Each logger can have zero, one or more handlers
Fred Drake6b3b0462004-04-09 18:26:40 +000058associated with it (via the \method{addHandler()} method of \class{Logger}).
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000059In addition to any handlers directly associated with a logger,
Fred Drakec23e0192003-01-28 22:09:16 +000060\emph{all handlers associated with all ancestors of the logger} are
61called to dispatch the message.
Skip Montanaro649698f2002-11-14 03:57:19 +000062
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000063Just as for loggers, handlers can have levels associated with them.
64A handler's level acts as a filter in the same way as a logger's level does.
Fred Drakec23e0192003-01-28 22:09:16 +000065If a handler decides to actually dispatch an event, the \method{emit()} method
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000066is used to send the message to its destination. Most user-defined subclasses
Fred Drakec23e0192003-01-28 22:09:16 +000067of \class{Handler} will need to override this \method{emit()}.
Skip Montanaro649698f2002-11-14 03:57:19 +000068
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000069In addition to the base \class{Handler} class, many useful subclasses
70are provided:
Skip Montanaro649698f2002-11-14 03:57:19 +000071
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000072\begin{enumerate}
Skip Montanaro649698f2002-11-14 03:57:19 +000073
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000074\item \class{StreamHandler} instances send error messages to
75streams (file-like objects).
Skip Montanaro649698f2002-11-14 03:57:19 +000076
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000077\item \class{FileHandler} instances send error messages to disk
78files.
79
80\item \class{RotatingFileHandler} instances send error messages to disk
81files, with support for maximum log file sizes and log file rotation.
82
83\item \class{SocketHandler} instances send error messages to
84TCP/IP sockets.
85
86\item \class{DatagramHandler} instances send error messages to UDP
87sockets.
88
89\item \class{SMTPHandler} instances send error messages to a
90designated email address.
91
92\item \class{SysLogHandler} instances send error messages to a
Fred Drake68e6d572003-01-28 22:02:35 +000093\UNIX{} syslog daemon, possibly on a remote machine.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +000094
95\item \class{NTEventLogHandler} instances send error messages to a
96Windows NT/2000/XP event log.
97
98\item \class{MemoryHandler} instances send error messages to a
99buffer in memory, which is flushed whenever specific criteria are
100met.
101
102\item \class{HTTPHandler} instances send error messages to an
Fred Drake68e6d572003-01-28 22:02:35 +0000103HTTP server using either \samp{GET} or \samp{POST} semantics.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000104
105\end{enumerate}
106
107The \class{StreamHandler} and \class{FileHandler} classes are defined
108in the core logging package. The other handlers are defined in a sub-
109module, \module{logging.handlers}. (There is also another sub-module,
110\module{logging.config}, for configuration functionality.)
111
112Logged messages are formatted for presentation through instances of the
113\class{Formatter} class. They are initialized with a format string
114suitable for use with the \% operator and a dictionary.
115
116For formatting multiple messages in a batch, instances of
117\class{BufferingFormatter} can be used. In addition to the format string
118(which is applied to each message in the batch), there is provision for
119header and trailer format strings.
120
121When filtering based on logger level and/or handler level is not enough,
122instances of \class{Filter} can be added to both \class{Logger} and
Fred Drakec23e0192003-01-28 22:09:16 +0000123\class{Handler} instances (through their \method{addFilter()} method).
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000124Before deciding to process a message further, both loggers and handlers
125consult all their filters for permission. If any filter returns a false
126value, the message is not processed further.
127
128The basic \class{Filter} functionality allows filtering by specific logger
129name. If this feature is used, messages sent to the named logger and its
130children are allowed through the filter, and all others dropped.
131
132In addition to the classes described above, there are a number of module-
133level functions.
134
135\begin{funcdesc}{getLogger}{\optional{name}}
136Return a logger with the specified name or, if no name is specified, return
Vinay Sajip17952b72004-08-31 10:21:51 +0000137a logger which is the root logger of the hierarchy. If specified, the name
138is typically a dot-separated hierarchical name like \var{"a"}, \var{"a.b"}
139or \var{"a.b.c.d"}. Choice of these names is entirely up to the developer
140who is using logging.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000141
142All calls to this function with a given name return the same logger instance.
143This means that logger instances never need to be passed between different
144parts of an application.
Skip Montanaro649698f2002-11-14 03:57:19 +0000145\end{funcdesc}
146
Vinay Sajipc6646c02004-09-22 12:55:16 +0000147\begin{funcdesc}{getLoggerClass}{}
148Return either the standard \class{Logger} class, or the last class passed to
149\function{setLoggerClass()}. This function may be called from within a new
150class definition, to ensure that installing a customised \class{Logger} class
151will not undo customisations already applied by other code. For example:
152
153\begin{verbatim}
154 class MyLogger(logging.getLoggerClass()):
155 # ... override behaviour here
156\end{verbatim}
157
158\end{funcdesc}
159
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000160\begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
161Logs a message with level \constant{DEBUG} on the root logger.
162The \var{msg} is the message format string, and the \var{args} are the
163arguments which are merged into \var{msg}. The only keyword argument in
164\var{kwargs} which is inspected is \var{exc_info} which, if it does not
Vinay Sajip1dc5b1e2004-10-03 19:10:05 +0000165evaluate as false, causes exception information to be added to the logging
166message. If an exception tuple (in the format returned by
167\function{sys.exc_info()}) is provided, it is used; otherwise,
168\function{sys.exc_info()} is called to get the exception information.
Skip Montanaro649698f2002-11-14 03:57:19 +0000169\end{funcdesc}
170
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000171\begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
172Logs a message with level \constant{INFO} on the root logger.
173The arguments are interpreted as for \function{debug()}.
Skip Montanaro649698f2002-11-14 03:57:19 +0000174\end{funcdesc}
175
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000176\begin{funcdesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
177Logs a message with level \constant{WARNING} on the root logger.
178The arguments are interpreted as for \function{debug()}.
179\end{funcdesc}
180
181\begin{funcdesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
182Logs a message with level \constant{ERROR} on the root logger.
183The arguments are interpreted as for \function{debug()}.
184\end{funcdesc}
185
186\begin{funcdesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
187Logs a message with level \constant{CRITICAL} on the root logger.
188The arguments are interpreted as for \function{debug()}.
189\end{funcdesc}
190
191\begin{funcdesc}{exception}{msg\optional{, *args}}
192Logs a message with level \constant{ERROR} on the root logger.
193The arguments are interpreted as for \function{debug()}. Exception info
194is added to the logging message. This function should only be called
195from an exception handler.
196\end{funcdesc}
197
Vinay Sajip739d49e2004-09-24 11:46:44 +0000198\begin{funcdesc}{log}{level, msg\optional{, *args\optional{, **kwargs}}}
199Logs a message with level \var{level} on the root logger.
200The other arguments are interpreted as for \function{debug()}.
201\end{funcdesc}
202
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000203\begin{funcdesc}{disable}{lvl}
204Provides an overriding level \var{lvl} for all loggers which takes
205precedence over the logger's own level. When the need arises to
206temporarily throttle logging output down across the whole application,
207this function can be useful.
208\end{funcdesc}
209
210\begin{funcdesc}{addLevelName}{lvl, levelName}
211Associates level \var{lvl} with text \var{levelName} in an internal
212dictionary, which is used to map numeric levels to a textual
213representation, for example when a \class{Formatter} formats a message.
214This function can also be used to define your own levels. The only
215constraints are that all levels used must be registered using this
216function, levels should be positive integers and they should increase
217in increasing order of severity.
218\end{funcdesc}
219
220\begin{funcdesc}{getLevelName}{lvl}
221Returns the textual representation of logging level \var{lvl}. If the
222level is one of the predefined levels \constant{CRITICAL},
223\constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG}
224then you get the corresponding string. If you have associated levels
225with names using \function{addLevelName()} then the name you have associated
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000226with \var{lvl} is returned. If a numeric value corresponding to one of the
227defined levels is passed in, the corresponding string representation is
228returned. Otherwise, the string "Level \%s" \% lvl is returned.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000229\end{funcdesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000230
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +0000231\begin{funcdesc}{makeLogRecord}{attrdict}
232Creates and returns a new \class{LogRecord} instance whose attributes are
233defined by \var{attrdict}. This function is useful for taking a pickled
234\class{LogRecord} attribute dictionary, sent over a socket, and reconstituting
235it as a \class{LogRecord} instance at the receiving end.
236\end{funcdesc}
237
Skip Montanaro649698f2002-11-14 03:57:19 +0000238\begin{funcdesc}{basicConfig}{}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000239Does basic configuration for the logging system by creating a
240\class{StreamHandler} with a default \class{Formatter} and adding it to
241the root logger. The functions \function{debug()}, \function{info()},
242\function{warning()}, \function{error()} and \function{critical()} will call
243\function{basicConfig()} automatically if no handlers are defined for the
244root logger.
Skip Montanaro649698f2002-11-14 03:57:19 +0000245\end{funcdesc}
246
Skip Montanaro649698f2002-11-14 03:57:19 +0000247\begin{funcdesc}{shutdown}{}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000248Informs the logging system to perform an orderly shutdown by flushing and
249closing all handlers.
Skip Montanaro649698f2002-11-14 03:57:19 +0000250\end{funcdesc}
251
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000252\begin{funcdesc}{setLoggerClass}{klass}
253Tells the logging system to use the class \var{klass} when instantiating a
254logger. The class should define \method{__init__()} such that only a name
255argument is required, and the \method{__init__()} should call
256\method{Logger.__init__()}. This function is typically called before any
257loggers are instantiated by applications which need to use custom logger
258behavior.
259\end{funcdesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000260
Fred Drake68e6d572003-01-28 22:02:35 +0000261
262\begin{seealso}
263 \seepep{282}{A Logging System}
264 {The proposal which described this feature for inclusion in
265 the Python standard library.}
Fred Drake11514792004-01-08 14:59:02 +0000266 \seelink{http://www.red-dove.com/python_logging.html}
267 {Original Python \module{logging} package}
268 {This is the original source for the \module{logging}
269 package. The version of the package available from this
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000270 site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x,
271 which do not include the \module{logging} package in the standard
Fred Drake11514792004-01-08 14:59:02 +0000272 library.}
Fred Drake68e6d572003-01-28 22:02:35 +0000273\end{seealso}
274
275
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000276\subsection{Logger Objects}
Skip Montanaro649698f2002-11-14 03:57:19 +0000277
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000278Loggers have the following attributes and methods. Note that Loggers are
279never instantiated directly, but always through the module-level function
280\function{logging.getLogger(name)}.
Skip Montanaro649698f2002-11-14 03:57:19 +0000281
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000282\begin{datadesc}{propagate}
283If this evaluates to false, logging messages are not passed by this
284logger or by child loggers to higher level (ancestor) loggers. The
285constructor sets this attribute to 1.
Skip Montanaro649698f2002-11-14 03:57:19 +0000286\end{datadesc}
287
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000288\begin{methoddesc}{setLevel}{lvl}
289Sets the threshold for this logger to \var{lvl}. Logging messages
290which are less severe than \var{lvl} will be ignored. When a logger is
Neal Norwitz6fa635d2003-02-18 14:20:07 +0000291created, the level is set to \constant{NOTSET} (which causes all messages
292to be processed in the root logger, or delegation to the parent in non-root
293loggers).
Skip Montanaro649698f2002-11-14 03:57:19 +0000294\end{methoddesc}
295
296\begin{methoddesc}{isEnabledFor}{lvl}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000297Indicates if a message of severity \var{lvl} would be processed by
298this logger. This method checks first the module-level level set by
299\function{logging.disable(lvl)} and then the logger's effective level as
300determined by \method{getEffectiveLevel()}.
Skip Montanaro649698f2002-11-14 03:57:19 +0000301\end{methoddesc}
302
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000303\begin{methoddesc}{getEffectiveLevel}{}
304Indicates the effective level for this logger. If a value other than
Neal Norwitz6fa635d2003-02-18 14:20:07 +0000305\constant{NOTSET} has been set using \method{setLevel()}, it is returned.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000306Otherwise, the hierarchy is traversed towards the root until a value
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +0000307other than \constant{NOTSET} is found, and that value is returned.
Skip Montanaro649698f2002-11-14 03:57:19 +0000308\end{methoddesc}
309
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000310\begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
311Logs a message with level \constant{DEBUG} on this logger.
312The \var{msg} is the message format string, and the \var{args} are the
313arguments which are merged into \var{msg}. The only keyword argument in
314\var{kwargs} which is inspected is \var{exc_info} which, if it does not
Vinay Sajip1dc5b1e2004-10-03 19:10:05 +0000315evaluate as false, causes exception information to be added to the logging
316message. If an exception tuple (as provided by \function{sys.exc_info()})
317is provided, it is used; otherwise, \function{sys.exc_info()} is called
318to get the exception information.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000319\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000320
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000321\begin{methoddesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
322Logs a message with level \constant{INFO} on this logger.
323The arguments are interpreted as for \method{debug()}.
324\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000325
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000326\begin{methoddesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
327Logs a message with level \constant{WARNING} on this logger.
328The arguments are interpreted as for \method{debug()}.
329\end{methoddesc}
330
331\begin{methoddesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
332Logs a message with level \constant{ERROR} on this logger.
333The arguments are interpreted as for \method{debug()}.
334\end{methoddesc}
335
336\begin{methoddesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
337Logs a message with level \constant{CRITICAL} on this logger.
338The arguments are interpreted as for \method{debug()}.
339\end{methoddesc}
340
341\begin{methoddesc}{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
Vinay Sajip1cf56d02004-08-04 08:36:44 +0000342Logs a message with integer level \var{lvl} on this logger.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000343The other arguments are interpreted as for \method{debug()}.
344\end{methoddesc}
345
346\begin{methoddesc}{exception}{msg\optional{, *args}}
347Logs a message with level \constant{ERROR} on this logger.
348The arguments are interpreted as for \method{debug()}. Exception info
349is added to the logging message. This method should only be called
350from an exception handler.
351\end{methoddesc}
352
353\begin{methoddesc}{addFilter}{filt}
354Adds the specified filter \var{filt} to this logger.
355\end{methoddesc}
356
357\begin{methoddesc}{removeFilter}{filt}
358Removes the specified filter \var{filt} from this logger.
359\end{methoddesc}
360
361\begin{methoddesc}{filter}{record}
362Applies this logger's filters to the record and returns a true value if
363the record is to be processed.
364\end{methoddesc}
365
366\begin{methoddesc}{addHandler}{hdlr}
367Adds the specified handler \var{hdlr} to this logger.
Skip Montanaro649698f2002-11-14 03:57:19 +0000368\end{methoddesc}
369
370\begin{methoddesc}{removeHandler}{hdlr}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000371Removes the specified handler \var{hdlr} from this logger.
Skip Montanaro649698f2002-11-14 03:57:19 +0000372\end{methoddesc}
373
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000374\begin{methoddesc}{findCaller}{}
375Finds the caller's source filename and line number. Returns the filename
376and line number as a 2-element tuple.
Skip Montanaro649698f2002-11-14 03:57:19 +0000377\end{methoddesc}
378
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000379\begin{methoddesc}{handle}{record}
380Handles a record by passing it to all handlers associated with this logger
381and its ancestors (until a false value of \var{propagate} is found).
382This method is used for unpickled records received from a socket, as well
383as those created locally. Logger-level filtering is applied using
384\method{filter()}.
Skip Montanaro649698f2002-11-14 03:57:19 +0000385\end{methoddesc}
386
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000387\begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info}
388This is a factory method which can be overridden in subclasses to create
389specialized \class{LogRecord} instances.
Skip Montanaro649698f2002-11-14 03:57:19 +0000390\end{methoddesc}
391
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000392\subsection{Basic example \label{minimal-example}}
393
394The \module{logging} package provides a lot of flexibility, and its
395configuration can appear daunting. This section demonstrates that simple
396use of the logging package is possible.
397
398The simplest example shows logging to the console:
399
400\begin{verbatim}
401import logging
402
403logging.debug('A debug message')
404logging.info('Some information')
405logging.warning('A shot across the bows')
406\end{verbatim}
407
408If you run the above script, you'll see this:
409\begin{verbatim}
410WARNING:root:A shot across the bows
411\end{verbatim}
412
413Because no particular logger was specified, the system used the root logger.
414The debug and info messages didn't appear because by default, the root
415logger is configured to only handle messages with a severity of WARNING
416or above. The message format is also a configuration default, as is the output
417destination of the messages - \code{sys.stderr}. The severity level,
418the message format and destination can be easily changed, as shown in
419the example below:
420
421\begin{verbatim}
422import logging
423
424logging.basicConfig(level=logging.DEBUG,
Vinay Sajipe3c330b2004-07-07 15:59:49 +0000425 format='%(asctime)s %(levelname)s %(message)s',
426 filename='/tmp/myapp.log',
427 filemode='w')
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000428logging.debug('A debug message')
429logging.info('Some information')
430logging.warning('A shot across the bows')
431\end{verbatim}
432
433The \method{basicConfig()} method is used to change the configuration
434defaults, which results in output (written to \code{/tmp/myapp.log})
435which should look something like the following:
436
437\begin{verbatim}
4382004-07-02 13:00:08,743 DEBUG A debug message
4392004-07-02 13:00:08,743 INFO Some information
4402004-07-02 13:00:08,743 WARNING A shot across the bows
441\end{verbatim}
442
443This time, all messages with a severity of DEBUG or above were handled,
444and the format of the messages was also changed, and output went to the
445specified file rather than the console.
446
447Formatting uses standard Python string formatting - see section
448\ref{typesseq-strings}. The format string takes the following
449common specifiers. For a complete list of specifiers, consult the
450\class{Formatter} documentation.
451
452\begin{tableii}{l|l}{code}{Format}{Description}
453\lineii{\%(name)s} {Name of the logger (logging channel).}
454\lineii{\%(levelname)s}{Text logging level for the message
455 (\code{'DEBUG'}, \code{'INFO'},
456 \code{'WARNING'}, \code{'ERROR'},
457 \code{'CRITICAL'}).}
458\lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord}
459 was created. By default this is of the form
460 ``2003-07-08 16:49:45,896'' (the numbers after the
461 comma are millisecond portion of the time).}
462\lineii{\%(message)s} {The logged message.}
463\end{tableii}
464
465To change the date/time format, you can pass an additional keyword parameter,
466\var{datefmt}, as in the following:
467
468\begin{verbatim}
469import logging
470
471logging.basicConfig(level=logging.DEBUG,
Vinay Sajipe3c330b2004-07-07 15:59:49 +0000472 format='%(asctime)s %(levelname)-8s %(message)s',
473 datefmt='%a, %d %b %Y %H:%M:%S',
474 filename='/temp/myapp.log',
475 filemode='w')
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000476logging.debug('A debug message')
477logging.info('Some information')
478logging.warning('A shot across the bows')
479\end{verbatim}
480
481which would result in output like
482
483\begin{verbatim}
484Fri, 02 Jul 2004 13:06:18 DEBUG A debug message
485Fri, 02 Jul 2004 13:06:18 INFO Some information
486Fri, 02 Jul 2004 13:06:18 WARNING A shot across the bows
487\end{verbatim}
488
489The date format string follows the requirements of \function{strftime()} -
490see the documentation for the \refmodule{time} module.
491
492If, instead of sending logging output to the console or a file, you'd rather
493use a file-like object which you have created separately, you can pass it
494to \function{basicConfig()} using the \var{stream} keyword argument. Note
495that if both \var{stream} and \var{filename} keyword arguments are passed,
496the \var{stream} argument is ignored.
497
Vinay Sajipb4bf62f2004-07-21 14:40:11 +0000498Of course, you can put variable information in your output. To do this,
499simply have the message be a format string and pass in additional arguments
500containing the variable information, as in the following example:
501
502\begin{verbatim}
503import logging
504
505logging.basicConfig(level=logging.DEBUG,
506 format='%(asctime)s %(levelname)-8s %(message)s',
507 datefmt='%a, %d %b %Y %H:%M:%S',
508 filename='/temp/myapp.log',
509 filemode='w')
510logging.error('Pack my box with %d dozen %s', 12, 'liquor jugs')
511\end{verbatim}
512
513which would result in
514
515\begin{verbatim}
516Wed, 21 Jul 2004 15:35:16 ERROR Pack my box with 12 dozen liquor jugs
517\end{verbatim}
518
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000519\subsection{Handler Objects}
Skip Montanaro649698f2002-11-14 03:57:19 +0000520
Fred Drake68e6d572003-01-28 22:02:35 +0000521Handlers have the following attributes and methods. Note that
522\class{Handler} is never instantiated directly; this class acts as a
523base for more useful subclasses. However, the \method{__init__()}
524method in subclasses needs to call \method{Handler.__init__()}.
Skip Montanaro649698f2002-11-14 03:57:19 +0000525
Neal Norwitz6fa635d2003-02-18 14:20:07 +0000526\begin{methoddesc}{__init__}{level=\constant{NOTSET}}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000527Initializes the \class{Handler} instance by setting its level, setting
528the list of filters to the empty list and creating a lock (using
Raymond Hettingerc75c3e02003-09-01 22:50:52 +0000529\method{createLock()}) for serializing access to an I/O mechanism.
Skip Montanaro649698f2002-11-14 03:57:19 +0000530\end{methoddesc}
531
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000532\begin{methoddesc}{createLock}{}
533Initializes a thread lock which can be used to serialize access to
534underlying I/O functionality which may not be threadsafe.
Skip Montanaro649698f2002-11-14 03:57:19 +0000535\end{methoddesc}
536
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000537\begin{methoddesc}{acquire}{}
538Acquires the thread lock created with \method{createLock()}.
539\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000540
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000541\begin{methoddesc}{release}{}
542Releases the thread lock acquired with \method{acquire()}.
543\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000544
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000545\begin{methoddesc}{setLevel}{lvl}
546Sets the threshold for this handler to \var{lvl}. Logging messages which are
547less severe than \var{lvl} will be ignored. When a handler is created, the
Neal Norwitz6fa635d2003-02-18 14:20:07 +0000548level is set to \constant{NOTSET} (which causes all messages to be processed).
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000549\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000550
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000551\begin{methoddesc}{setFormatter}{form}
552Sets the \class{Formatter} for this handler to \var{form}.
553\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000554
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000555\begin{methoddesc}{addFilter}{filt}
556Adds the specified filter \var{filt} to this handler.
557\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000558
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000559\begin{methoddesc}{removeFilter}{filt}
560Removes the specified filter \var{filt} from this handler.
561\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000562
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000563\begin{methoddesc}{filter}{record}
564Applies this handler's filters to the record and returns a true value if
565the record is to be processed.
Skip Montanaro649698f2002-11-14 03:57:19 +0000566\end{methoddesc}
567
568\begin{methoddesc}{flush}{}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000569Ensure all logging output has been flushed. This version does
570nothing and is intended to be implemented by subclasses.
Skip Montanaro649698f2002-11-14 03:57:19 +0000571\end{methoddesc}
572
Skip Montanaro649698f2002-11-14 03:57:19 +0000573\begin{methoddesc}{close}{}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000574Tidy up any resources used by the handler. This version does
575nothing and is intended to be implemented by subclasses.
Skip Montanaro649698f2002-11-14 03:57:19 +0000576\end{methoddesc}
577
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000578\begin{methoddesc}{handle}{record}
579Conditionally emits the specified logging record, depending on
580filters which may have been added to the handler. Wraps the actual
581emission of the record with acquisition/release of the I/O thread
582lock.
Skip Montanaro649698f2002-11-14 03:57:19 +0000583\end{methoddesc}
584
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000585\begin{methoddesc}{handleError}{record}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000586This method should be called from handlers when an exception is
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000587encountered during an \method{emit()} call. By default it does nothing,
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000588which means that exceptions get silently ignored. This is what is
589mostly wanted for a logging system - most users will not care
590about errors in the logging system, they are more interested in
591application errors. You could, however, replace this with a custom
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000592handler if you wish. The specified record is the one which was being
593processed when the exception occurred.
Skip Montanaro649698f2002-11-14 03:57:19 +0000594\end{methoddesc}
595
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000596\begin{methoddesc}{format}{record}
597Do formatting for a record - if a formatter is set, use it.
598Otherwise, use the default formatter for the module.
Skip Montanaro649698f2002-11-14 03:57:19 +0000599\end{methoddesc}
600
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000601\begin{methoddesc}{emit}{record}
602Do whatever it takes to actually log the specified logging record.
603This version is intended to be implemented by subclasses and so
604raises a \exception{NotImplementedError}.
Skip Montanaro649698f2002-11-14 03:57:19 +0000605\end{methoddesc}
606
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000607\subsubsection{StreamHandler}
Skip Montanaro649698f2002-11-14 03:57:19 +0000608
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000609The \class{StreamHandler} class sends logging output to streams such as
610\var{sys.stdout}, \var{sys.stderr} or any file-like object (or, more
611precisely, any object which supports \method{write()} and \method{flush()}
Raymond Hettinger2ef85a72003-01-25 21:46:53 +0000612methods).
Skip Montanaro649698f2002-11-14 03:57:19 +0000613
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000614\begin{classdesc}{StreamHandler}{\optional{strm}}
615Returns a new instance of the \class{StreamHandler} class. If \var{strm} is
616specified, the instance will use it for logging output; otherwise,
617\var{sys.stderr} will be used.
Skip Montanaro649698f2002-11-14 03:57:19 +0000618\end{classdesc}
619
620\begin{methoddesc}{emit}{record}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000621If a formatter is specified, it is used to format the record.
622The record is then written to the stream with a trailing newline.
623If exception information is present, it is formatted using
624\function{traceback.print_exception()} and appended to the stream.
Skip Montanaro649698f2002-11-14 03:57:19 +0000625\end{methoddesc}
626
627\begin{methoddesc}{flush}{}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000628Flushes the stream by calling its \method{flush()} method. Note that
629the \method{close()} method is inherited from \class{Handler} and
630so does nothing, so an explicit \method{flush()} call may be needed
631at times.
Skip Montanaro649698f2002-11-14 03:57:19 +0000632\end{methoddesc}
633
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000634\subsubsection{FileHandler}
Skip Montanaro649698f2002-11-14 03:57:19 +0000635
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000636The \class{FileHandler} class sends logging output to a disk file.
Fred Drake68e6d572003-01-28 22:02:35 +0000637It inherits the output functionality from \class{StreamHandler}.
Skip Montanaro649698f2002-11-14 03:57:19 +0000638
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000639\begin{classdesc}{FileHandler}{filename\optional{, mode}}
640Returns a new instance of the \class{FileHandler} class. The specified
641file is opened and used as the stream for logging. If \var{mode} is
Fred Drake9a5b6a62003-07-08 15:38:40 +0000642not specified, \constant{'a'} is used. By default, the file grows
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000643indefinitely.
Skip Montanaro649698f2002-11-14 03:57:19 +0000644\end{classdesc}
645
646\begin{methoddesc}{close}{}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000647Closes the file.
Skip Montanaro649698f2002-11-14 03:57:19 +0000648\end{methoddesc}
649
650\begin{methoddesc}{emit}{record}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000651Outputs the record to the file.
652\end{methoddesc}
Skip Montanaro649698f2002-11-14 03:57:19 +0000653
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000654\subsubsection{RotatingFileHandler}
Skip Montanaro649698f2002-11-14 03:57:19 +0000655
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000656The \class{RotatingFileHandler} class supports rotation of disk log files.
657
Fred Drake9a5b6a62003-07-08 15:38:40 +0000658\begin{classdesc}{RotatingFileHandler}{filename\optional{, mode\optional{,
659 maxBytes\optional{, backupCount}}}}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000660Returns a new instance of the \class{RotatingFileHandler} class. The
661specified file is opened and used as the stream for logging. If
Fred Drake68e6d572003-01-28 22:02:35 +0000662\var{mode} is not specified, \code{'a'} is used. By default, the
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000663file grows indefinitely.
Andrew M. Kuchling7cf4d9b2003-09-26 13:45:18 +0000664
665You can use the \var{maxBytes} and
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000666\var{backupCount} values to allow the file to \dfn{rollover} at a
667predetermined size. When the size is about to be exceeded, the file is
Andrew M. Kuchling7cf4d9b2003-09-26 13:45:18 +0000668closed and a new file is silently opened for output. Rollover occurs
669whenever the current log file is nearly \var{maxBytes} in length; if
670\var{maxBytes} is zero, rollover never occurs. If \var{backupCount}
671is non-zero, the system will save old log files by appending the
672extensions ".1", ".2" etc., to the filename. For example, with
673a \var{backupCount} of 5 and a base file name of
674\file{app.log}, you would get \file{app.log},
675\file{app.log.1}, \file{app.log.2}, up to \file{app.log.5}. The file being
676written to is always \file{app.log}. When this file is filled, it is
677closed and renamed to \file{app.log.1}, and if files \file{app.log.1},
678\file{app.log.2}, etc. exist, then they are renamed to \file{app.log.2},
Vinay Sajipa13c60b2004-07-03 11:45:53 +0000679\file{app.log.3} etc. respectively.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000680\end{classdesc}
681
682\begin{methoddesc}{doRollover}{}
683Does a rollover, as described above.
684\end{methoddesc}
685
686\begin{methoddesc}{emit}{record}
687Outputs the record to the file, catering for rollover as described
688in \method{setRollover()}.
689\end{methoddesc}
690
691\subsubsection{SocketHandler}
692
693The \class{SocketHandler} class sends logging output to a network
694socket. The base class uses a TCP socket.
695
696\begin{classdesc}{SocketHandler}{host, port}
697Returns a new instance of the \class{SocketHandler} class intended to
698communicate with a remote machine whose address is given by \var{host}
699and \var{port}.
700\end{classdesc}
701
702\begin{methoddesc}{close}{}
703Closes the socket.
704\end{methoddesc}
705
706\begin{methoddesc}{handleError}{}
707\end{methoddesc}
708
709\begin{methoddesc}{emit}{}
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +0000710Pickles the record's attribute dictionary and writes it to the socket in
711binary format. If there is an error with the socket, silently drops the
712packet. If the connection was previously lost, re-establishes the connection.
Fred Drake6b3b0462004-04-09 18:26:40 +0000713To unpickle the record at the receiving end into a \class{LogRecord}, use the
714\function{makeLogRecord()} function.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000715\end{methoddesc}
716
717\begin{methoddesc}{handleError}{}
718Handles an error which has occurred during \method{emit()}. The
719most likely cause is a lost connection. Closes the socket so that
720we can retry on the next event.
721\end{methoddesc}
722
723\begin{methoddesc}{makeSocket}{}
724This is a factory method which allows subclasses to define the precise
725type of socket they want. The default implementation creates a TCP
726socket (\constant{socket.SOCK_STREAM}).
727\end{methoddesc}
728
729\begin{methoddesc}{makePickle}{record}
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +0000730Pickles the record's attribute dictionary in binary format with a length
731prefix, and returns it ready for transmission across the socket.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000732\end{methoddesc}
733
734\begin{methoddesc}{send}{packet}
Raymond Hettinger2ef85a72003-01-25 21:46:53 +0000735Send a pickled string \var{packet} to the socket. This function allows
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000736for partial sends which can happen when the network is busy.
737\end{methoddesc}
738
739\subsubsection{DatagramHandler}
740
741The \class{DatagramHandler} class inherits from \class{SocketHandler}
742to support sending logging messages over UDP sockets.
743
744\begin{classdesc}{DatagramHandler}{host, port}
745Returns a new instance of the \class{DatagramHandler} class intended to
746communicate with a remote machine whose address is given by \var{host}
747and \var{port}.
748\end{classdesc}
749
750\begin{methoddesc}{emit}{}
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +0000751Pickles the record's attribute dictionary and writes it to the socket in
752binary format. If there is an error with the socket, silently drops the
753packet.
Fred Drake6b3b0462004-04-09 18:26:40 +0000754To unpickle the record at the receiving end into a \class{LogRecord}, use the
755\function{makeLogRecord()} function.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000756\end{methoddesc}
757
758\begin{methoddesc}{makeSocket}{}
759The factory method of \class{SocketHandler} is here overridden to create
760a UDP socket (\constant{socket.SOCK_DGRAM}).
761\end{methoddesc}
762
763\begin{methoddesc}{send}{s}
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +0000764Send a pickled string to a socket.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000765\end{methoddesc}
766
767\subsubsection{SysLogHandler}
768
769The \class{SysLogHandler} class supports sending logging messages to a
Fred Drake68e6d572003-01-28 22:02:35 +0000770remote or local \UNIX{} syslog.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000771
772\begin{classdesc}{SysLogHandler}{\optional{address\optional{, facility}}}
773Returns a new instance of the \class{SysLogHandler} class intended to
Fred Drake68e6d572003-01-28 22:02:35 +0000774communicate with a remote \UNIX{} machine whose address is given by
775\var{address} in the form of a \code{(\var{host}, \var{port})}
776tuple. If \var{address} is not specified, \code{('localhost', 514)} is
777used. The address is used to open a UDP socket. If \var{facility} is
778not specified, \constant{LOG_USER} is used.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000779\end{classdesc}
780
781\begin{methoddesc}{close}{}
782Closes the socket to the remote host.
783\end{methoddesc}
784
785\begin{methoddesc}{emit}{record}
786The record is formatted, and then sent to the syslog server. If
787exception information is present, it is \emph{not} sent to the server.
Skip Montanaro649698f2002-11-14 03:57:19 +0000788\end{methoddesc}
789
790\begin{methoddesc}{encodePriority}{facility, priority}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000791Encodes the facility and priority into an integer. You can pass in strings
792or integers - if strings are passed, internal mapping dictionaries are used
793to convert them to integers.
Skip Montanaro649698f2002-11-14 03:57:19 +0000794\end{methoddesc}
795
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000796\subsubsection{NTEventLogHandler}
Skip Montanaro649698f2002-11-14 03:57:19 +0000797
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000798The \class{NTEventLogHandler} class supports sending logging messages
799to a local Windows NT, Windows 2000 or Windows XP event log. Before
800you can use it, you need Mark Hammond's Win32 extensions for Python
801installed.
Skip Montanaro649698f2002-11-14 03:57:19 +0000802
Fred Drake9a5b6a62003-07-08 15:38:40 +0000803\begin{classdesc}{NTEventLogHandler}{appname\optional{,
804 dllname\optional{, logtype}}}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000805Returns a new instance of the \class{NTEventLogHandler} class. The
806\var{appname} is used to define the application name as it appears in the
807event log. An appropriate registry entry is created using this name.
808The \var{dllname} should give the fully qualified pathname of a .dll or .exe
809which contains message definitions to hold in the log (if not specified,
Fred Drake9a5b6a62003-07-08 15:38:40 +0000810\code{'win32service.pyd'} is used - this is installed with the Win32
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000811extensions and contains some basic placeholder message definitions.
812Note that use of these placeholders will make your event logs big, as the
813entire message source is held in the log. If you want slimmer logs, you have
814to pass in the name of your own .dll or .exe which contains the message
815definitions you want to use in the event log). The \var{logtype} is one of
Fred Drake9a5b6a62003-07-08 15:38:40 +0000816\code{'Application'}, \code{'System'} or \code{'Security'}, and
817defaults to \code{'Application'}.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000818\end{classdesc}
819
820\begin{methoddesc}{close}{}
821At this point, you can remove the application name from the registry as a
822source of event log entries. However, if you do this, you will not be able
823to see the events as you intended in the Event Log Viewer - it needs to be
824able to access the registry to get the .dll name. The current version does
825not do this (in fact it doesn't do anything).
826\end{methoddesc}
827
828\begin{methoddesc}{emit}{record}
829Determines the message ID, event category and event type, and then logs the
830message in the NT event log.
831\end{methoddesc}
832
833\begin{methoddesc}{getEventCategory}{record}
834Returns the event category for the record. Override this if you
835want to specify your own categories. This version returns 0.
836\end{methoddesc}
837
838\begin{methoddesc}{getEventType}{record}
839Returns the event type for the record. Override this if you want
840to specify your own types. This version does a mapping using the
841handler's typemap attribute, which is set up in \method{__init__()}
842to a dictionary which contains mappings for \constant{DEBUG},
843\constant{INFO}, \constant{WARNING}, \constant{ERROR} and
844\constant{CRITICAL}. If you are using your own levels, you will either need
845to override this method or place a suitable dictionary in the
846handler's \var{typemap} attribute.
847\end{methoddesc}
848
849\begin{methoddesc}{getMessageID}{record}
850Returns the message ID for the record. If you are using your
851own messages, you could do this by having the \var{msg} passed to the
852logger being an ID rather than a format string. Then, in here,
853you could use a dictionary lookup to get the message ID. This
854version returns 1, which is the base message ID in
Fred Drake9a5b6a62003-07-08 15:38:40 +0000855\file{win32service.pyd}.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000856\end{methoddesc}
857
858\subsubsection{SMTPHandler}
859
860The \class{SMTPHandler} class supports sending logging messages to an email
861address via SMTP.
862
863\begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject}
864Returns a new instance of the \class{SMTPHandler} class. The
865instance is initialized with the from and to addresses and subject
866line of the email. The \var{toaddrs} should be a list of strings without
867domain names (That's what the \var{mailhost} is for). To specify a
868non-standard SMTP port, use the (host, port) tuple format for the
869\var{mailhost} argument. If you use a string, the standard SMTP port
870is used.
871\end{classdesc}
872
873\begin{methoddesc}{emit}{record}
874Formats the record and sends it to the specified addressees.
875\end{methoddesc}
876
877\begin{methoddesc}{getSubject}{record}
878If you want to specify a subject line which is record-dependent,
879override this method.
880\end{methoddesc}
881
882\subsubsection{MemoryHandler}
883
884The \class{MemoryHandler} supports buffering of logging records in memory,
885periodically flushing them to a \dfn{target} handler. Flushing occurs
886whenever the buffer is full, or when an event of a certain severity or
887greater is seen.
888
889\class{MemoryHandler} is a subclass of the more general
890\class{BufferingHandler}, which is an abstract class. This buffers logging
891records in memory. Whenever each record is added to the buffer, a
892check is made by calling \method{shouldFlush()} to see if the buffer
893should be flushed. If it should, then \method{flush()} is expected to
894do the needful.
895
896\begin{classdesc}{BufferingHandler}{capacity}
897Initializes the handler with a buffer of the specified capacity.
898\end{classdesc}
899
900\begin{methoddesc}{emit}{record}
901Appends the record to the buffer. If \method{shouldFlush()} returns true,
902calls \method{flush()} to process the buffer.
903\end{methoddesc}
904
905\begin{methoddesc}{flush}{}
Raymond Hettinger2ef85a72003-01-25 21:46:53 +0000906You can override this to implement custom flushing behavior. This version
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000907just zaps the buffer to empty.
908\end{methoddesc}
909
910\begin{methoddesc}{shouldFlush}{record}
911Returns true if the buffer is up to capacity. This method can be
912overridden to implement custom flushing strategies.
913\end{methoddesc}
914
915\begin{classdesc}{MemoryHandler}{capacity\optional{, flushLevel
Neal Norwitz6fa635d2003-02-18 14:20:07 +0000916\optional{, target}}}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000917Returns a new instance of the \class{MemoryHandler} class. The
918instance is initialized with a buffer size of \var{capacity}. If
919\var{flushLevel} is not specified, \constant{ERROR} is used. If no
920\var{target} is specified, the target will need to be set using
921\method{setTarget()} before this handler does anything useful.
922\end{classdesc}
923
924\begin{methoddesc}{close}{}
925Calls \method{flush()}, sets the target to \constant{None} and
926clears the buffer.
927\end{methoddesc}
928
929\begin{methoddesc}{flush}{}
930For a \class{MemoryHandler}, flushing means just sending the buffered
931records to the target, if there is one. Override if you want
Raymond Hettinger2ef85a72003-01-25 21:46:53 +0000932different behavior.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000933\end{methoddesc}
934
935\begin{methoddesc}{setTarget}{target}
936Sets the target handler for this handler.
937\end{methoddesc}
938
939\begin{methoddesc}{shouldFlush}{record}
940Checks for buffer full or a record at the \var{flushLevel} or higher.
941\end{methoddesc}
942
943\subsubsection{HTTPHandler}
944
945The \class{HTTPHandler} class supports sending logging messages to a
Fred Drake68e6d572003-01-28 22:02:35 +0000946Web server, using either \samp{GET} or \samp{POST} semantics.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000947
948\begin{classdesc}{HTTPHandler}{host, url\optional{, method}}
949Returns a new instance of the \class{HTTPHandler} class. The
950instance is initialized with a host address, url and HTTP method.
Fred Drake68e6d572003-01-28 22:02:35 +0000951If no \var{method} is specified, \samp{GET} is used.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000952\end{classdesc}
953
954\begin{methoddesc}{emit}{record}
955Sends the record to the Web server as an URL-encoded dictionary.
956\end{methoddesc}
957
958\subsection{Formatter Objects}
959
960\class{Formatter}s have the following attributes and methods. They are
961responsible for converting a \class{LogRecord} to (usually) a string
962which can be interpreted by either a human or an external system. The
963base
964\class{Formatter} allows a formatting string to be specified. If none is
Fred Drake8efc74d2004-04-15 06:18:48 +0000965supplied, the default value of \code{'\%(message)s'} is used.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000966
967A Formatter can be initialized with a format string which makes use of
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +0000968knowledge of the \class{LogRecord} attributes - such as the default value
969mentioned above making use of the fact that the user's message and
Fred Drake6b3b0462004-04-09 18:26:40 +0000970arguments are pre-formatted into a \class{LogRecord}'s \var{message}
Anthony Baxtera6b7d342003-07-08 08:40:20 +0000971attribute. This format string contains standard python \%-style
972mapping keys. See section \ref{typesseq-strings}, ``String Formatting
973Operations,'' for more information on string formatting.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +0000974
Fred Drake6b3b0462004-04-09 18:26:40 +0000975Currently, the useful mapping keys in a \class{LogRecord} are:
Anthony Baxtera6b7d342003-07-08 08:40:20 +0000976
Fred Drake9a5b6a62003-07-08 15:38:40 +0000977\begin{tableii}{l|l}{code}{Format}{Description}
978\lineii{\%(name)s} {Name of the logger (logging channel).}
979\lineii{\%(levelno)s} {Numeric logging level for the message
980 (\constant{DEBUG}, \constant{INFO},
981 \constant{WARNING}, \constant{ERROR},
982 \constant{CRITICAL}).}
983\lineii{\%(levelname)s}{Text logging level for the message
984 (\code{'DEBUG'}, \code{'INFO'},
985 \code{'WARNING'}, \code{'ERROR'},
986 \code{'CRITICAL'}).}
987\lineii{\%(pathname)s} {Full pathname of the source file where the logging
988 call was issued (if available).}
989\lineii{\%(filename)s} {Filename portion of pathname.}
990\lineii{\%(module)s} {Module (name portion of filename).}
991\lineii{\%(lineno)d} {Source line number where the logging call was issued
992 (if available).}
Fred Drake6b3b0462004-04-09 18:26:40 +0000993\lineii{\%(created)f} {Time when the \class{LogRecord} was created (as
Fred Drake9a5b6a62003-07-08 15:38:40 +0000994 returned by \function{time.time()}).}
Fred Drake6b3b0462004-04-09 18:26:40 +0000995\lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord}
996 was created. By default this is of the form
Fred Drake9a5b6a62003-07-08 15:38:40 +0000997 ``2003-07-08 16:49:45,896'' (the numbers after the
998 comma are millisecond portion of the time).}
999\lineii{\%(msecs)d} {Millisecond portion of the time when the
1000 \class{LogRecord} was created.}
1001\lineii{\%(thread)d} {Thread ID (if available).}
1002\lineii{\%(process)d} {Process ID (if available).}
1003\lineii{\%(message)s} {The logged message, computed as \code{msg \% args}.}
Anthony Baxtera6b7d342003-07-08 08:40:20 +00001004\end{tableii}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001005
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001006\begin{classdesc}{Formatter}{\optional{fmt\optional{, datefmt}}}
1007Returns a new instance of the \class{Formatter} class. The
1008instance is initialized with a format string for the message as a whole,
1009as well as a format string for the date/time portion of a message. If
Neal Norwitzdd3afa72003-07-08 16:26:34 +00001010no \var{fmt} is specified, \code{'\%(message)s'} is used. If no \var{datefmt}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001011is specified, the ISO8601 date format is used.
1012\end{classdesc}
1013
1014\begin{methoddesc}{format}{record}
1015The record's attribute dictionary is used as the operand to a
1016string formatting operation. Returns the resulting string.
1017Before formatting the dictionary, a couple of preparatory steps
1018are carried out. The \var{message} attribute of the record is computed
1019using \var{msg} \% \var{args}. If the formatting string contains
Fred Drake9a5b6a62003-07-08 15:38:40 +00001020\code{'(asctime)'}, \method{formatTime()} is called to format the
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001021event time. If there is exception information, it is formatted using
1022\method{formatException()} and appended to the message.
1023\end{methoddesc}
1024
1025\begin{methoddesc}{formatTime}{record\optional{, datefmt}}
1026This method should be called from \method{format()} by a formatter which
1027wants to make use of a formatted time. This method can be overridden
1028in formatters to provide for any specific requirement, but the
Raymond Hettinger2ef85a72003-01-25 21:46:53 +00001029basic behavior is as follows: if \var{datefmt} (a string) is specified,
Fred Drakec23e0192003-01-28 22:09:16 +00001030it is used with \function{time.strftime()} to format the creation time of the
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001031record. Otherwise, the ISO8601 format is used. The resulting
1032string is returned.
1033\end{methoddesc}
1034
1035\begin{methoddesc}{formatException}{exc_info}
1036Formats the specified exception information (a standard exception tuple
Fred Drakec23e0192003-01-28 22:09:16 +00001037as returned by \function{sys.exc_info()}) as a string. This default
1038implementation just uses \function{traceback.print_exception()}.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001039The resulting string is returned.
1040\end{methoddesc}
1041
1042\subsection{Filter Objects}
1043
1044\class{Filter}s can be used by \class{Handler}s and \class{Logger}s for
1045more sophisticated filtering than is provided by levels. The base filter
1046class only allows events which are below a certain point in the logger
1047hierarchy. For example, a filter initialized with "A.B" will allow events
1048logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB",
1049"B.A.B" etc. If initialized with the empty string, all events are passed.
1050
1051\begin{classdesc}{Filter}{\optional{name}}
1052Returns an instance of the \class{Filter} class. If \var{name} is specified,
1053it names a logger which, together with its children, will have its events
1054allowed through the filter. If no name is specified, allows every event.
1055\end{classdesc}
1056
1057\begin{methoddesc}{filter}{record}
1058Is the specified record to be logged? Returns zero for no, nonzero for
1059yes. If deemed appropriate, the record may be modified in-place by this
1060method.
1061\end{methoddesc}
1062
1063\subsection{LogRecord Objects}
1064
Fred Drake6b3b0462004-04-09 18:26:40 +00001065\class{LogRecord} instances are created every time something is logged. They
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001066contain all the information pertinent to the event being logged. The
1067main information passed in is in msg and args, which are combined
1068using msg \% args to create the message field of the record. The record
1069also includes information such as when the record was created, the
1070source line where the logging call was made, and any exception
1071information to be logged.
1072
Fred Drake6b3b0462004-04-09 18:26:40 +00001073\class{LogRecord} has no methods; it's just a repository for
1074information about the logging event. The only reason it's a class
1075rather than a dictionary is to facilitate extension.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001076
1077\begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args,
Fred Drake9a5b6a62003-07-08 15:38:40 +00001078 exc_info}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001079Returns an instance of \class{LogRecord} initialized with interesting
1080information. The \var{name} is the logger name; \var{lvl} is the
1081numeric level; \var{pathname} is the absolute pathname of the source
1082file in which the logging call was made; \var{lineno} is the line
1083number in that file where the logging call is found; \var{msg} is the
1084user-supplied message (a format string); \var{args} is the tuple
1085which, together with \var{msg}, makes up the user message; and
1086\var{exc_info} is the exception tuple obtained by calling
1087\function{sys.exc_info() }(or \constant{None}, if no exception information
1088is available).
1089\end{classdesc}
1090
1091\subsection{Thread Safety}
1092
1093The logging module is intended to be thread-safe without any special work
1094needing to be done by its clients. It achieves this though using threading
1095locks; there is one lock to serialize access to the module's shared data,
1096and each handler also creates a lock to serialize access to its underlying
1097I/O.
1098
1099\subsection{Configuration}
1100
1101
Fred Drake94ffbb72004-04-08 19:44:31 +00001102\subsubsection{Configuration functions%
1103 \label{logging-config-api}}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001104
Fred Drake9a5b6a62003-07-08 15:38:40 +00001105The following functions allow the logging module to be
1106configured. Before they can be used, you must import
1107\module{logging.config}. Their use is optional --- you can configure
1108the logging module entirely by making calls to the main API (defined
1109in \module{logging} itself) and defining handlers which are declared
Raymond Hettinger6f3eaa62003-06-27 21:43:39 +00001110either in \module{logging} or \module{logging.handlers}.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001111
1112\begin{funcdesc}{fileConfig}{fname\optional{, defaults}}
1113Reads the logging configuration from a ConfigParser-format file named
1114\var{fname}. This function can be called several times from an application,
1115allowing an end user the ability to select from various pre-canned
1116configurations (if the developer provides a mechanism to present the
1117choices and load the chosen configuration). Defaults to be passed to
1118ConfigParser can be specified in the \var{defaults} argument.
1119\end{funcdesc}
1120
1121\begin{funcdesc}{listen}{\optional{port}}
1122Starts up a socket server on the specified port, and listens for new
1123configurations. If no port is specified, the module's default
1124\constant{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations
1125will be sent as a file suitable for processing by \function{fileConfig()}.
1126Returns a \class{Thread} instance on which you can call \method{start()}
1127to start the server, and which you can \method{join()} when appropriate.
1128To stop the server, call \function{stopListening()}.
1129\end{funcdesc}
1130
1131\begin{funcdesc}{stopListening}{}
1132Stops the listening server which was created with a call to
1133\function{listen()}. This is typically called before calling \method{join()}
1134on the return value from \function{listen()}.
1135\end{funcdesc}
1136
Fred Drake94ffbb72004-04-08 19:44:31 +00001137\subsubsection{Configuration file format%
1138 \label{logging-config-fileformat}}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001139
Fred Drake6b3b0462004-04-09 18:26:40 +00001140The configuration file format understood by \function{fileConfig()} is
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001141based on ConfigParser functionality. The file must contain sections
1142called \code{[loggers]}, \code{[handlers]} and \code{[formatters]}
1143which identify by name the entities of each type which are defined in
1144the file. For each such entity, there is a separate section which
1145identified how that entity is configured. Thus, for a logger named
1146\code{log01} in the \code{[loggers]} section, the relevant
1147configuration details are held in a section
1148\code{[logger_log01]}. Similarly, a handler called \code{hand01} in
1149the \code{[handlers]} section will have its configuration held in a
1150section called \code{[handler_hand01]}, while a formatter called
1151\code{form01} in the \code{[formatters]} section will have its
1152configuration specified in a section called
1153\code{[formatter_form01]}. The root logger configuration must be
1154specified in a section called \code{[logger_root]}.
1155
1156Examples of these sections in the file are given below.
Skip Montanaro649698f2002-11-14 03:57:19 +00001157
1158\begin{verbatim}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001159[loggers]
1160keys=root,log02,log03,log04,log05,log06,log07
Skip Montanaro649698f2002-11-14 03:57:19 +00001161
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001162[handlers]
1163keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
1164
1165[formatters]
1166keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
Skip Montanaro649698f2002-11-14 03:57:19 +00001167\end{verbatim}
1168
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001169The root logger must specify a level and a list of handlers. An
1170example of a root logger section is given below.
Skip Montanaro649698f2002-11-14 03:57:19 +00001171
1172\begin{verbatim}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001173[logger_root]
1174level=NOTSET
1175handlers=hand01
Skip Montanaro649698f2002-11-14 03:57:19 +00001176\end{verbatim}
1177
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001178The \code{level} entry can be one of \code{DEBUG, INFO, WARNING,
1179ERROR, CRITICAL} or \code{NOTSET}. For the root logger only,
1180\code{NOTSET} means that all messages will be logged. Level values are
1181\function{eval()}uated in the context of the \code{logging} package's
1182namespace.
Skip Montanaro649698f2002-11-14 03:57:19 +00001183
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001184The \code{handlers} entry is a comma-separated list of handler names,
1185which must appear in the \code{[handlers]} section. These names must
1186appear in the \code{[handlers]} section and have corresponding
1187sections in the configuration file.
Skip Montanaro649698f2002-11-14 03:57:19 +00001188
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001189For loggers other than the root logger, some additional information is
1190required. This is illustrated by the following example.
Skip Montanaro649698f2002-11-14 03:57:19 +00001191
1192\begin{verbatim}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001193[logger_parser]
1194level=DEBUG
1195handlers=hand01
1196propagate=1
1197qualname=compiler.parser
Skip Montanaro649698f2002-11-14 03:57:19 +00001198\end{verbatim}
1199
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001200The \code{level} and \code{handlers} entries are interpreted as for
1201the root logger, except that if a non-root logger's level is specified
1202as \code{NOTSET}, the system consults loggers higher up the hierarchy
1203to determine the effective level of the logger. The \code{propagate}
1204entry is set to 1 to indicate that messages must propagate to handlers
1205higher up the logger hierarchy from this logger, or 0 to indicate that
1206messages are \strong{not} propagated to handlers up the hierarchy. The
1207\code{qualname} entry is the hierarchical channel name of the logger,
Vinay Sajipa13c60b2004-07-03 11:45:53 +00001208that is to say the name used by the application to get the logger.
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001209
1210Sections which specify handler configuration are exemplified by the
1211following.
1212
Skip Montanaro649698f2002-11-14 03:57:19 +00001213\begin{verbatim}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001214[handler_hand01]
1215class=StreamHandler
1216level=NOTSET
1217formatter=form01
1218args=(sys.stdout,)
Skip Montanaro649698f2002-11-14 03:57:19 +00001219\end{verbatim}
1220
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001221The \code{class} entry indicates the handler's class (as determined by
1222\function{eval()} in the \code{logging} package's namespace). The
1223\code{level} is interpreted as for loggers, and \code{NOTSET} is taken
1224to mean "log everything".
1225
1226The \code{formatter} entry indicates the key name of the formatter for
1227this handler. If blank, a default formatter
1228(\code{logging._defaultFormatter}) is used. If a name is specified, it
1229must appear in the \code{[formatters]} section and have a
1230corresponding section in the configuration file.
1231
1232The \code{args} entry, when \function{eval()}uated in the context of
1233the \code{logging} package's namespace, is the list of arguments to
1234the constructor for the handler class. Refer to the constructors for
1235the relevant handlers, or to the examples below, to see how typical
1236entries are constructed.
Skip Montanaro649698f2002-11-14 03:57:19 +00001237
1238\begin{verbatim}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001239[handler_hand02]
1240class=FileHandler
1241level=DEBUG
1242formatter=form02
1243args=('python.log', 'w')
1244
1245[handler_hand03]
1246class=handlers.SocketHandler
1247level=INFO
1248formatter=form03
1249args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
1250
1251[handler_hand04]
1252class=handlers.DatagramHandler
1253level=WARN
1254formatter=form04
1255args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
1256
1257[handler_hand05]
1258class=handlers.SysLogHandler
1259level=ERROR
1260formatter=form05
1261args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
1262
1263[handler_hand06]
Vinay Sajip20f42c42004-07-12 15:48:04 +00001264class=handlers.NTEventLogHandler
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001265level=CRITICAL
1266formatter=form06
1267args=('Python Application', '', 'Application')
1268
1269[handler_hand07]
Vinay Sajip20f42c42004-07-12 15:48:04 +00001270class=handlers.SMTPHandler
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001271level=WARN
1272formatter=form07
1273args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
1274
1275[handler_hand08]
Vinay Sajip20f42c42004-07-12 15:48:04 +00001276class=handlers.MemoryHandler
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001277level=NOTSET
1278formatter=form08
1279target=
1280args=(10, ERROR)
1281
1282[handler_hand09]
Vinay Sajip20f42c42004-07-12 15:48:04 +00001283class=handlers.HTTPHandler
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001284level=NOTSET
1285formatter=form09
1286args=('localhost:9022', '/log', 'GET')
Skip Montanaro649698f2002-11-14 03:57:19 +00001287\end{verbatim}
Neal Norwitzcd5c8c22003-01-25 21:29:41 +00001288
1289Sections which specify formatter configuration are typified by the following.
1290
1291\begin{verbatim}
1292[formatter_form01]
1293format=F1 %(asctime)s %(levelname)s %(message)s
1294datefmt=
1295\end{verbatim}
1296
1297The \code{format} entry is the overall format string, and the
1298\code{datefmt} entry is the \function{strftime()}-compatible date/time format
1299string. If empty, the package substitutes ISO8601 format date/times, which
1300is almost equivalent to specifying the date format string "%Y-%m-%d %H:%M:%S".
1301The ISO8601 format also specifies milliseconds, which are appended to the
1302result of using the above format string, with a comma separator. An example
1303time in ISO8601 format is \code{2003-01-23 00:29:50,411}.