blob: b05282b502daf478361655a714764f118b0a0cab [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`logging` --- Logging facility for Python
2==============================================
3
4.. module:: logging
5 :synopsis: Flexible error logging system for applications.
6
7
8.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
9.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
10
11
Georg Brandl116aa622007-08-15 14:28:22 +000012.. index:: pair: Errors; logging
13
Georg Brandl116aa622007-08-15 14:28:22 +000014This module defines functions and classes which implement a flexible error
15logging system for applications.
16
17Logging is performed by calling methods on instances of the :class:`Logger`
18class (hereafter called :dfn:`loggers`). Each instance has a name, and they are
Georg Brandl9afde1c2007-11-01 20:32:30 +000019conceptually arranged in a namespace hierarchy using dots (periods) as
Georg Brandl116aa622007-08-15 14:28:22 +000020separators. For example, a logger named "scan" is the parent of loggers
21"scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want,
22and indicate the area of an application in which a logged message originates.
23
24Logged messages also have levels of importance associated with them. The default
25levels provided are :const:`DEBUG`, :const:`INFO`, :const:`WARNING`,
26:const:`ERROR` and :const:`CRITICAL`. As a convenience, you indicate the
27importance of a logged message by calling an appropriate method of
28:class:`Logger`. The methods are :meth:`debug`, :meth:`info`, :meth:`warning`,
29:meth:`error` and :meth:`critical`, which mirror the default levels. You are not
30constrained to use these levels: you can specify your own and use a more general
31:class:`Logger` method, :meth:`log`, which takes an explicit level argument.
32
Christian Heimes8b0facf2007-12-04 19:30:01 +000033
34Logging tutorial
35----------------
36
37The key benefit of having the logging API provided by a standard library module
38is that all Python modules can participate in logging, so your application log
39can include messages from third-party modules.
40
41It is, of course, possible to log messages with different verbosity levels or to
42different destinations. Support for writing log messages to files, HTTP
43GET/POST locations, email via SMTP, generic sockets, or OS-specific logging
Christian Heimesc3f30c42008-02-22 16:37:40 +000044mechanisms are all supported by the standard module. You can also create your
Christian Heimes8b0facf2007-12-04 19:30:01 +000045own log destination class if you have special requirements not met by any of the
46built-in classes.
47
48Simple examples
49^^^^^^^^^^^^^^^
50
51.. sectionauthor:: Doug Hellmann
52.. (see <http://blog.doughellmann.com/2007/05/pymotw-logging.html>)
53
54Most applications are probably going to want to log to a file, so let's start
55with that case. Using the :func:`basicConfig` function, we can set up the
56default handler so that debug messages are written to a file::
57
58 import logging
59 LOG_FILENAME = '/tmp/logging_example.out'
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +000060 logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG)
Christian Heimes8b0facf2007-12-04 19:30:01 +000061
62 logging.debug('This message should go to the log file')
63
64And now if we open the file and look at what we have, we should find the log
65message::
66
67 DEBUG:root:This message should go to the log file
68
69If you run the script repeatedly, the additional log messages are appended to
Eric Smith5c01a8d2009-06-04 18:20:51 +000070the file. To create a new file each time, you can pass a *filemode* argument to
Christian Heimes8b0facf2007-12-04 19:30:01 +000071:func:`basicConfig` with a value of ``'w'``. Rather than managing the file size
72yourself, though, it is simpler to use a :class:`RotatingFileHandler`::
73
74 import glob
75 import logging
76 import logging.handlers
77
78 LOG_FILENAME = '/tmp/logging_rotatingfile_example.out'
79
80 # Set up a specific logger with our desired output level
81 my_logger = logging.getLogger('MyLogger')
82 my_logger.setLevel(logging.DEBUG)
83
84 # Add the log message handler to the logger
85 handler = logging.handlers.RotatingFileHandler(
86 LOG_FILENAME, maxBytes=20, backupCount=5)
87
88 my_logger.addHandler(handler)
89
90 # Log some messages
91 for i in range(20):
92 my_logger.debug('i = %d' % i)
93
94 # See what files are created
95 logfiles = glob.glob('%s*' % LOG_FILENAME)
96
97 for filename in logfiles:
Georg Brandlf6945182008-02-01 11:56:49 +000098 print(filename)
Christian Heimes8b0facf2007-12-04 19:30:01 +000099
100The result should be 6 separate files, each with part of the log history for the
101application::
102
103 /tmp/logging_rotatingfile_example.out
104 /tmp/logging_rotatingfile_example.out.1
105 /tmp/logging_rotatingfile_example.out.2
106 /tmp/logging_rotatingfile_example.out.3
107 /tmp/logging_rotatingfile_example.out.4
108 /tmp/logging_rotatingfile_example.out.5
109
110The most current file is always :file:`/tmp/logging_rotatingfile_example.out`,
111and each time it reaches the size limit it is renamed with the suffix
112``.1``. Each of the existing backup files is renamed to increment the suffix
Eric Smith5c01a8d2009-06-04 18:20:51 +0000113(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased.
Christian Heimes8b0facf2007-12-04 19:30:01 +0000114
115Obviously this example sets the log length much much too small as an extreme
116example. You would want to set *maxBytes* to an appropriate value.
117
118Another useful feature of the logging API is the ability to produce different
119messages at different log levels. This allows you to instrument your code with
120debug messages, for example, but turning the log level down so that those debug
121messages are not written for your production system. The default levels are
Vinay Sajipb6d065f2009-10-28 23:28:16 +0000122``NOTSET``, ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and ``CRITICAL``.
Christian Heimes8b0facf2007-12-04 19:30:01 +0000123
124The logger, handler, and log message call each specify a level. The log message
125is only emitted if the handler and logger are configured to emit messages of
126that level or lower. For example, if a message is ``CRITICAL``, and the logger
127is set to ``ERROR``, the message is emitted. If a message is a ``WARNING``, and
128the logger is set to produce only ``ERROR``\s, the message is not emitted::
129
130 import logging
131 import sys
132
133 LEVELS = {'debug': logging.DEBUG,
134 'info': logging.INFO,
135 'warning': logging.WARNING,
136 'error': logging.ERROR,
137 'critical': logging.CRITICAL}
138
139 if len(sys.argv) > 1:
140 level_name = sys.argv[1]
141 level = LEVELS.get(level_name, logging.NOTSET)
142 logging.basicConfig(level=level)
143
144 logging.debug('This is a debug message')
145 logging.info('This is an info message')
146 logging.warning('This is a warning message')
147 logging.error('This is an error message')
148 logging.critical('This is a critical error message')
149
150Run the script with an argument like 'debug' or 'warning' to see which messages
151show up at different levels::
152
153 $ python logging_level_example.py debug
154 DEBUG:root:This is a debug message
155 INFO:root:This is an info message
156 WARNING:root:This is a warning message
157 ERROR:root:This is an error message
158 CRITICAL:root:This is a critical error message
159
160 $ python logging_level_example.py info
161 INFO:root:This is an info message
162 WARNING:root:This is a warning message
163 ERROR:root:This is an error message
164 CRITICAL:root:This is a critical error message
165
166You will notice that these log messages all have ``root`` embedded in them. The
167logging module supports a hierarchy of loggers with different names. An easy
168way to tell where a specific log message comes from is to use a separate logger
169object for each of your modules. Each new logger "inherits" the configuration
170of its parent, and log messages sent to a logger include the name of that
171logger. Optionally, each logger can be configured differently, so that messages
172from different modules are handled in different ways. Let's look at a simple
173example of how to log from different modules so it is easy to trace the source
174of the message::
175
176 import logging
177
178 logging.basicConfig(level=logging.WARNING)
179
180 logger1 = logging.getLogger('package1.module1')
181 logger2 = logging.getLogger('package2.module2')
182
183 logger1.warning('This message comes from one module')
184 logger2.warning('And this message comes from another module')
185
186And the output::
187
188 $ python logging_modules_example.py
189 WARNING:package1.module1:This message comes from one module
190 WARNING:package2.module2:And this message comes from another module
191
192There are many more options for configuring logging, including different log
193message formatting options, having messages delivered to multiple destinations,
194and changing the configuration of a long-running application on the fly using a
195socket interface. All of these options are covered in depth in the library
196module documentation.
197
198Loggers
199^^^^^^^
200
201The logging library takes a modular approach and offers the several categories
202of components: loggers, handlers, filters, and formatters. Loggers expose the
203interface that application code directly uses. Handlers send the log records to
204the appropriate destination. Filters provide a finer grained facility for
205determining which log records to send on to a handler. Formatters specify the
206layout of the resultant log record.
207
208:class:`Logger` objects have a threefold job. First, they expose several
209methods to application code so that applications can log messages at runtime.
210Second, logger objects determine which log messages to act upon based upon
211severity (the default filtering facility) or filter objects. Third, logger
212objects pass along relevant log messages to all interested log handlers.
213
214The most widely used methods on logger objects fall into two categories:
215configuration and message sending.
216
217* :meth:`Logger.setLevel` specifies the lowest-severity log message a logger
218 will handle, where debug is the lowest built-in severity level and critical is
219 the highest built-in severity. For example, if the severity level is info,
220 the logger will handle only info, warning, error, and critical messages and
221 will ignore debug messages.
222
223* :meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove filter
224 objects from the logger object. This tutorial does not address filters.
225
226With the logger object configured, the following methods create log messages:
227
228* :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`,
229 :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with
230 a message and a level that corresponds to their respective method names. The
231 message is actually a format string, which may contain the standard string
232 substitution syntax of :const:`%s`, :const:`%d`, :const:`%f`, and so on. The
233 rest of their arguments is a list of objects that correspond with the
234 substitution fields in the message. With regard to :const:`**kwargs`, the
235 logging methods care only about a keyword of :const:`exc_info` and use it to
236 determine whether to log exception information.
237
238* :meth:`Logger.exception` creates a log message similar to
239 :meth:`Logger.error`. The difference is that :meth:`Logger.exception` dumps a
240 stack trace along with it. Call this method only from an exception handler.
241
242* :meth:`Logger.log` takes a log level as an explicit argument. This is a
243 little more verbose for logging messages than using the log level convenience
244 methods listed above, but this is how to log at custom log levels.
245
Christian Heimesdcca98d2008-02-25 13:19:43 +0000246:func:`getLogger` returns a reference to a logger instance with the specified
247if it it is provided, or ``root`` if not. The names are period-separated
Christian Heimes8b0facf2007-12-04 19:30:01 +0000248hierarchical structures. Multiple calls to :func:`getLogger` with the same name
249will return a reference to the same logger object. Loggers that are further
250down in the hierarchical list are children of loggers higher up in the list.
251For example, given a logger with a name of ``foo``, loggers with names of
252``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all children of ``foo``.
253Child loggers propagate messages up to their parent loggers. Because of this,
254it is unnecessary to define and configure all the loggers an application uses.
255It is sufficient to configure a top-level logger and create child loggers as
256needed.
257
258
259Handlers
260^^^^^^^^
261
262:class:`Handler` objects are responsible for dispatching the appropriate log
263messages (based on the log messages' severity) to the handler's specified
264destination. Logger objects can add zero or more handler objects to themselves
265with an :func:`addHandler` method. As an example scenario, an application may
266want to send all log messages to a log file, all log messages of error or higher
267to stdout, and all messages of critical to an email address. This scenario
Christian Heimesc3f30c42008-02-22 16:37:40 +0000268requires three individual handlers where each handler is responsible for sending
Christian Heimes8b0facf2007-12-04 19:30:01 +0000269messages of a specific severity to a specific location.
270
271The standard library includes quite a few handler types; this tutorial uses only
272:class:`StreamHandler` and :class:`FileHandler` in its examples.
273
274There are very few methods in a handler for application developers to concern
275themselves with. The only handler methods that seem relevant for application
276developers who are using the built-in handler objects (that is, not creating
277custom handlers) are the following configuration methods:
278
279* The :meth:`Handler.setLevel` method, just as in logger objects, specifies the
280 lowest severity that will be dispatched to the appropriate destination. Why
281 are there two :func:`setLevel` methods? The level set in the logger
282 determines which severity of messages it will pass to its handlers. The level
283 set in each handler determines which messages that handler will send on.
284 :func:`setFormatter` selects a Formatter object for this handler to use.
285
286* :func:`addFilter` and :func:`removeFilter` respectively configure and
287 deconfigure filter objects on handlers.
288
289Application code should not directly instantiate and use handlers. Instead, the
290:class:`Handler` class is a base class that defines the interface that all
291Handlers should have and establishes some default behavior that child classes
292can use (or override).
293
294
295Formatters
296^^^^^^^^^^
297
298Formatter objects configure the final order, structure, and contents of the log
Christian Heimesdcca98d2008-02-25 13:19:43 +0000299message. Unlike the base :class:`logging.Handler` class, application code may
Christian Heimes8b0facf2007-12-04 19:30:01 +0000300instantiate formatter classes, although you could likely subclass the formatter
301if your application needs special behavior. The constructor takes two optional
302arguments: a message format string and a date format string. If there is no
303message format string, the default is to use the raw message. If there is no
304date format string, the default date format is::
305
306 %Y-%m-%d %H:%M:%S
307
308with the milliseconds tacked on at the end.
309
310The message format string uses ``%(<dictionary key>)s`` styled string
311substitution; the possible keys are documented in :ref:`formatter-objects`.
312
313The following message format string will log the time in a human-readable
314format, the severity of the message, and the contents of the message, in that
315order::
316
317 "%(asctime)s - %(levelname)s - %(message)s"
318
319
320Configuring Logging
321^^^^^^^^^^^^^^^^^^^
322
323Programmers can configure logging either by creating loggers, handlers, and
324formatters explicitly in a main module with the configuration methods listed
325above (using Python code), or by creating a logging config file. The following
326code is an example of configuring a very simple logger, a console handler, and a
327simple formatter in a Python module::
328
329 import logging
330
331 # create logger
332 logger = logging.getLogger("simple_example")
333 logger.setLevel(logging.DEBUG)
334 # create console handler and set level to debug
335 ch = logging.StreamHandler()
336 ch.setLevel(logging.DEBUG)
337 # create formatter
338 formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
339 # add formatter to ch
340 ch.setFormatter(formatter)
341 # add ch to logger
342 logger.addHandler(ch)
343
344 # "application" code
345 logger.debug("debug message")
346 logger.info("info message")
347 logger.warn("warn message")
348 logger.error("error message")
349 logger.critical("critical message")
350
351Running this module from the command line produces the following output::
352
353 $ python simple_logging_module.py
354 2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
355 2005-03-19 15:10:26,620 - simple_example - INFO - info message
356 2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
357 2005-03-19 15:10:26,697 - simple_example - ERROR - error message
358 2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message
359
360The following Python module creates a logger, handler, and formatter nearly
361identical to those in the example listed above, with the only difference being
362the names of the objects::
363
364 import logging
365 import logging.config
366
367 logging.config.fileConfig("logging.conf")
368
369 # create logger
370 logger = logging.getLogger("simpleExample")
371
372 # "application" code
373 logger.debug("debug message")
374 logger.info("info message")
375 logger.warn("warn message")
376 logger.error("error message")
377 logger.critical("critical message")
378
379Here is the logging.conf file::
380
381 [loggers]
382 keys=root,simpleExample
383
384 [handlers]
385 keys=consoleHandler
386
387 [formatters]
388 keys=simpleFormatter
389
390 [logger_root]
391 level=DEBUG
392 handlers=consoleHandler
393
394 [logger_simpleExample]
395 level=DEBUG
396 handlers=consoleHandler
397 qualname=simpleExample
398 propagate=0
399
400 [handler_consoleHandler]
401 class=StreamHandler
402 level=DEBUG
403 formatter=simpleFormatter
404 args=(sys.stdout,)
405
406 [formatter_simpleFormatter]
407 format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
408 datefmt=
409
410The output is nearly identical to that of the non-config-file-based example::
411
412 $ python simple_logging_config.py
413 2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
414 2005-03-19 15:38:55,979 - simpleExample - INFO - info message
415 2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
416 2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
417 2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message
418
419You can see that the config file approach has a few advantages over the Python
420code approach, mainly separation of configuration and code and the ability of
421noncoders to easily modify the logging properties.
422
Vinay Sajip26a2d5e2009-01-10 13:37:26 +0000423.. _library-config:
Vinay Sajip30bf1222009-01-10 19:23:34 +0000424
Benjamin Peterson3e4f0552008-09-02 00:31:15 +0000425Configuring Logging for a Library
426^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
427
428When developing a library which uses logging, some consideration needs to be
429given to its configuration. If the using application does not use logging, and
430library code makes logging calls, then a one-off message "No handlers could be
431found for logger X.Y.Z" is printed to the console. This message is intended
432to catch mistakes in logging configuration, but will confuse an application
433developer who is not aware of logging by the library.
434
435In addition to documenting how a library uses logging, a good way to configure
436library logging so that it does not cause a spurious message is to add a
437handler which does nothing. This avoids the message being printed, since a
438handler will be found: it just doesn't produce any output. If the library user
439configures logging for application use, presumably that configuration will add
440some handlers, and if levels are suitably configured then logging calls made
441in library code will send output to those handlers, as normal.
442
443A do-nothing handler can be simply defined as follows::
444
445 import logging
446
447 class NullHandler(logging.Handler):
448 def emit(self, record):
449 pass
450
451An instance of this handler should be added to the top-level logger of the
452logging namespace used by the library. If all logging by a library *foo* is
453done using loggers with names matching "foo.x.y", then the code::
454
455 import logging
456
457 h = NullHandler()
458 logging.getLogger("foo").addHandler(h)
459
460should have the desired effect. If an organisation produces a number of
461libraries, then the logger name specified can be "orgname.foo" rather than
462just "foo".
463
Georg Brandlf9734072008-12-07 15:30:06 +0000464.. versionadded:: 3.1
465
466The :class:`NullHandler` class was not present in previous versions, but is now
467included, so that it need not be defined in library code.
468
469
Christian Heimes8b0facf2007-12-04 19:30:01 +0000470
471Logging Levels
472--------------
473
Georg Brandl116aa622007-08-15 14:28:22 +0000474The numeric values of logging levels are given in the following table. These are
475primarily of interest if you want to define your own levels, and need them to
476have specific values relative to the predefined levels. If you define a level
477with the same numeric value, it overwrites the predefined value; the predefined
478name is lost.
479
480+--------------+---------------+
481| Level | Numeric value |
482+==============+===============+
483| ``CRITICAL`` | 50 |
484+--------------+---------------+
485| ``ERROR`` | 40 |
486+--------------+---------------+
487| ``WARNING`` | 30 |
488+--------------+---------------+
489| ``INFO`` | 20 |
490+--------------+---------------+
491| ``DEBUG`` | 10 |
492+--------------+---------------+
493| ``NOTSET`` | 0 |
494+--------------+---------------+
495
496Levels can also be associated with loggers, being set either by the developer or
497through loading a saved logging configuration. When a logging method is called
498on a logger, the logger compares its own level with the level associated with
499the method call. If the logger's level is higher than the method call's, no
500logging message is actually generated. This is the basic mechanism controlling
501the verbosity of logging output.
502
503Logging messages are encoded as instances of the :class:`LogRecord` class. When
504a logger decides to actually log an event, a :class:`LogRecord` instance is
505created from the logging message.
506
507Logging messages are subjected to a dispatch mechanism through the use of
508:dfn:`handlers`, which are instances of subclasses of the :class:`Handler`
509class. Handlers are responsible for ensuring that a logged message (in the form
510of a :class:`LogRecord`) ends up in a particular location (or set of locations)
511which is useful for the target audience for that message (such as end users,
512support desk staff, system administrators, developers). Handlers are passed
513:class:`LogRecord` instances intended for particular destinations. Each logger
514can have zero, one or more handlers associated with it (via the
515:meth:`addHandler` method of :class:`Logger`). In addition to any handlers
516directly associated with a logger, *all handlers associated with all ancestors
517of the logger* are called to dispatch the message.
518
519Just as for loggers, handlers can have levels associated with them. A handler's
520level acts as a filter in the same way as a logger's level does. If a handler
521decides to actually dispatch an event, the :meth:`emit` method is used to send
522the message to its destination. Most user-defined subclasses of :class:`Handler`
523will need to override this :meth:`emit`.
524
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000525Useful Handlers
526---------------
527
Georg Brandl116aa622007-08-15 14:28:22 +0000528In addition to the base :class:`Handler` class, many useful subclasses are
529provided:
530
531#. :class:`StreamHandler` instances send error messages to streams (file-like
532 objects).
533
534#. :class:`FileHandler` instances send error messages to disk files.
535
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000536.. module:: logging.handlers
Vinay Sajip30bf1222009-01-10 19:23:34 +0000537
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000538#. :class:`BaseRotatingHandler` is the base class for handlers that
539 rotate log files at a certain point. It is not meant to be instantiated
540 directly. Instead, use :class:`RotatingFileHandler` or
541 :class:`TimedRotatingFileHandler`.
Georg Brandl116aa622007-08-15 14:28:22 +0000542
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000543#. :class:`RotatingFileHandler` instances send error messages to disk
544 files, with support for maximum log file sizes and log file rotation.
Georg Brandl116aa622007-08-15 14:28:22 +0000545
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000546#. :class:`TimedRotatingFileHandler` instances send error messages to
547 disk files, rotating the log file at certain timed intervals.
Georg Brandl116aa622007-08-15 14:28:22 +0000548
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000549#. :class:`SocketHandler` instances send error messages to TCP/IP
550 sockets.
Georg Brandl116aa622007-08-15 14:28:22 +0000551
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000552#. :class:`DatagramHandler` instances send error messages to UDP
553 sockets.
Georg Brandl116aa622007-08-15 14:28:22 +0000554
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000555#. :class:`SMTPHandler` instances send error messages to a designated
556 email address.
Georg Brandl116aa622007-08-15 14:28:22 +0000557
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000558#. :class:`SysLogHandler` instances send error messages to a Unix
559 syslog daemon, possibly on a remote machine.
Georg Brandl116aa622007-08-15 14:28:22 +0000560
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000561#. :class:`NTEventLogHandler` instances send error messages to a
562 Windows NT/2000/XP event log.
Georg Brandl116aa622007-08-15 14:28:22 +0000563
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000564#. :class:`MemoryHandler` instances send error messages to a buffer
565 in memory, which is flushed whenever specific criteria are met.
Georg Brandl116aa622007-08-15 14:28:22 +0000566
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000567#. :class:`HTTPHandler` instances send error messages to an HTTP
568 server using either ``GET`` or ``POST`` semantics.
Georg Brandl116aa622007-08-15 14:28:22 +0000569
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000570#. :class:`WatchedFileHandler` instances watch the file they are
571 logging to. If the file changes, it is closed and reopened using the file
572 name. This handler is only useful on Unix-like systems; Windows does not
573 support the underlying mechanism used.
Vinay Sajip30bf1222009-01-10 19:23:34 +0000574
575.. currentmodule:: logging
576
Georg Brandlf9734072008-12-07 15:30:06 +0000577#. :class:`NullHandler` instances do nothing with error messages. They are used
578 by library developers who want to use logging, but want to avoid the "No
579 handlers could be found for logger XXX" message which can be displayed if
Vinay Sajip26a2d5e2009-01-10 13:37:26 +0000580 the library user has not configured logging. See :ref:`library-config` for
581 more information.
Georg Brandlf9734072008-12-07 15:30:06 +0000582
583.. versionadded:: 3.1
584
585The :class:`NullHandler` class was not present in previous versions.
586
Vinay Sajipa17775f2008-12-30 07:32:59 +0000587The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler`
588classes are defined in the core logging package. The other handlers are
589defined in a sub- module, :mod:`logging.handlers`. (There is also another
590sub-module, :mod:`logging.config`, for configuration functionality.)
Georg Brandl116aa622007-08-15 14:28:22 +0000591
592Logged messages are formatted for presentation through instances of the
593:class:`Formatter` class. They are initialized with a format string suitable for
594use with the % operator and a dictionary.
595
596For formatting multiple messages in a batch, instances of
597:class:`BufferingFormatter` can be used. In addition to the format string (which
598is applied to each message in the batch), there is provision for header and
599trailer format strings.
600
601When filtering based on logger level and/or handler level is not enough,
602instances of :class:`Filter` can be added to both :class:`Logger` and
603:class:`Handler` instances (through their :meth:`addFilter` method). Before
604deciding to process a message further, both loggers and handlers consult all
605their filters for permission. If any filter returns a false value, the message
606is not processed further.
607
608The basic :class:`Filter` functionality allows filtering by specific logger
609name. If this feature is used, messages sent to the named logger and its
610children are allowed through the filter, and all others dropped.
611
Benjamin Peterson058e31e2009-01-16 03:54:08 +0000612Module-Level Functions
613----------------------
614
Georg Brandl116aa622007-08-15 14:28:22 +0000615In addition to the classes described above, there are a number of module- level
616functions.
617
618
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000619.. function:: getLogger(name=None)
Georg Brandl116aa622007-08-15 14:28:22 +0000620
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000621 Return a logger with the specified name or, if name is ``None``, return a
Georg Brandl116aa622007-08-15 14:28:22 +0000622 logger which is the root logger of the hierarchy. If specified, the name is
623 typically a dot-separated hierarchical name like *"a"*, *"a.b"* or *"a.b.c.d"*.
624 Choice of these names is entirely up to the developer who is using logging.
625
626 All calls to this function with a given name return the same logger instance.
627 This means that logger instances never need to be passed between different parts
628 of an application.
629
630
631.. function:: getLoggerClass()
632
633 Return either the standard :class:`Logger` class, or the last class passed to
634 :func:`setLoggerClass`. This function may be called from within a new class
635 definition, to ensure that installing a customised :class:`Logger` class will
636 not undo customisations already applied by other code. For example::
637
638 class MyLogger(logging.getLoggerClass()):
639 # ... override behaviour here
640
641
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000642.. function:: debug(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000643
644 Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the
645 message format string, and the *args* are the arguments which are merged into
646 *msg* using the string formatting operator. (Note that this means that you can
647 use keywords in the format string, together with a single dictionary argument.)
648
649 There are two keyword arguments in *kwargs* which are inspected: *exc_info*
650 which, if it does not evaluate as false, causes exception information to be
651 added to the logging message. If an exception tuple (in the format returned by
652 :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`
653 is called to get the exception information.
654
655 The other optional keyword argument is *extra* which can be used to pass a
656 dictionary which is used to populate the __dict__ of the LogRecord created for
657 the logging event with user-defined attributes. These custom attributes can then
658 be used as you like. For example, they could be incorporated into logged
659 messages. For example::
660
661 FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
662 logging.basicConfig(format=FORMAT)
663 d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
664 logging.warning("Protocol problem: %s", "connection reset", extra=d)
665
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000666 would print something like ::
Georg Brandl116aa622007-08-15 14:28:22 +0000667
668 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
669
670 The keys in the dictionary passed in *extra* should not clash with the keys used
671 by the logging system. (See the :class:`Formatter` documentation for more
672 information on which keys are used by the logging system.)
673
674 If you choose to use these attributes in logged messages, you need to exercise
675 some care. In the above example, for instance, the :class:`Formatter` has been
676 set up with a format string which expects 'clientip' and 'user' in the attribute
677 dictionary of the LogRecord. If these are missing, the message will not be
678 logged because a string formatting exception will occur. So in this case, you
679 always need to pass the *extra* dictionary with these keys.
680
681 While this might be annoying, this feature is intended for use in specialized
682 circumstances, such as multi-threaded servers where the same code executes in
683 many contexts, and interesting conditions which arise are dependent on this
684 context (such as remote client IP address and authenticated user name, in the
685 above example). In such circumstances, it is likely that specialized
686 :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
687
Georg Brandl116aa622007-08-15 14:28:22 +0000688
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000689.. function:: info(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000690
691 Logs a message with level :const:`INFO` on the root logger. The arguments are
692 interpreted as for :func:`debug`.
693
694
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000695.. function:: warning(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000696
697 Logs a message with level :const:`WARNING` on the root logger. The arguments are
698 interpreted as for :func:`debug`.
699
700
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000701.. function:: error(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000702
703 Logs a message with level :const:`ERROR` on the root logger. The arguments are
704 interpreted as for :func:`debug`.
705
706
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000707.. function:: critical(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000708
709 Logs a message with level :const:`CRITICAL` on the root logger. The arguments
710 are interpreted as for :func:`debug`.
711
712
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000713.. function:: exception(msg, *args)
Georg Brandl116aa622007-08-15 14:28:22 +0000714
715 Logs a message with level :const:`ERROR` on the root logger. The arguments are
716 interpreted as for :func:`debug`. Exception info is added to the logging
717 message. This function should only be called from an exception handler.
718
719
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000720.. function:: log(level, msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000721
722 Logs a message with level *level* on the root logger. The other arguments are
723 interpreted as for :func:`debug`.
724
725
726.. function:: disable(lvl)
727
728 Provides an overriding level *lvl* for all loggers which takes precedence over
729 the logger's own level. When the need arises to temporarily throttle logging
730 output down across the whole application, this function can be useful.
731
732
733.. function:: addLevelName(lvl, levelName)
734
735 Associates level *lvl* with text *levelName* in an internal dictionary, which is
736 used to map numeric levels to a textual representation, for example when a
737 :class:`Formatter` formats a message. This function can also be used to define
738 your own levels. The only constraints are that all levels used must be
739 registered using this function, levels should be positive integers and they
740 should increase in increasing order of severity.
741
742
743.. function:: getLevelName(lvl)
744
745 Returns the textual representation of logging level *lvl*. If the level is one
746 of the predefined levels :const:`CRITICAL`, :const:`ERROR`, :const:`WARNING`,
747 :const:`INFO` or :const:`DEBUG` then you get the corresponding string. If you
748 have associated levels with names using :func:`addLevelName` then the name you
749 have associated with *lvl* is returned. If a numeric value corresponding to one
750 of the defined levels is passed in, the corresponding string representation is
751 returned. Otherwise, the string "Level %s" % lvl is returned.
752
753
754.. function:: makeLogRecord(attrdict)
755
756 Creates and returns a new :class:`LogRecord` instance whose attributes are
757 defined by *attrdict*. This function is useful for taking a pickled
758 :class:`LogRecord` attribute dictionary, sent over a socket, and reconstituting
759 it as a :class:`LogRecord` instance at the receiving end.
760
761
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000762.. function:: basicConfig(**kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000763
764 Does basic configuration for the logging system by creating a
765 :class:`StreamHandler` with a default :class:`Formatter` and adding it to the
Vinay Sajipcbabd7e2009-10-10 20:32:36 +0000766 root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,
Georg Brandl116aa622007-08-15 14:28:22 +0000767 :func:`error` and :func:`critical` will call :func:`basicConfig` automatically
768 if no handlers are defined for the root logger.
769
Vinay Sajipcbabd7e2009-10-10 20:32:36 +0000770 This function does nothing if the root logger already has handlers
771 configured for it.
772
Georg Brandl116aa622007-08-15 14:28:22 +0000773 The following keyword arguments are supported.
774
775 +--------------+---------------------------------------------+
776 | Format | Description |
777 +==============+=============================================+
778 | ``filename`` | Specifies that a FileHandler be created, |
779 | | using the specified filename, rather than a |
780 | | StreamHandler. |
781 +--------------+---------------------------------------------+
782 | ``filemode`` | Specifies the mode to open the file, if |
783 | | filename is specified (if filemode is |
784 | | unspecified, it defaults to 'a'). |
785 +--------------+---------------------------------------------+
786 | ``format`` | Use the specified format string for the |
787 | | handler. |
788 +--------------+---------------------------------------------+
789 | ``datefmt`` | Use the specified date/time format. |
790 +--------------+---------------------------------------------+
791 | ``level`` | Set the root logger level to the specified |
792 | | level. |
793 +--------------+---------------------------------------------+
794 | ``stream`` | Use the specified stream to initialize the |
795 | | StreamHandler. Note that this argument is |
796 | | incompatible with 'filename' - if both are |
797 | | present, 'stream' is ignored. |
798 +--------------+---------------------------------------------+
799
800
801.. function:: shutdown()
802
803 Informs the logging system to perform an orderly shutdown by flushing and
Christian Heimesb186d002008-03-18 15:15:01 +0000804 closing all handlers. This should be called at application exit and no
805 further use of the logging system should be made after this call.
Georg Brandl116aa622007-08-15 14:28:22 +0000806
807
808.. function:: setLoggerClass(klass)
809
810 Tells the logging system to use the class *klass* when instantiating a logger.
811 The class should define :meth:`__init__` such that only a name argument is
812 required, and the :meth:`__init__` should call :meth:`Logger.__init__`. This
813 function is typically called before any loggers are instantiated by applications
814 which need to use custom logger behavior.
815
816
817.. seealso::
818
819 :pep:`282` - A Logging System
820 The proposal which described this feature for inclusion in the Python standard
821 library.
822
Christian Heimes255f53b2007-12-08 15:33:56 +0000823 `Original Python logging package <http://www.red-dove.com/python_logging.html>`_
Georg Brandl116aa622007-08-15 14:28:22 +0000824 This is the original source for the :mod:`logging` package. The version of the
825 package available from this site is suitable for use with Python 1.5.2, 2.1.x
826 and 2.2.x, which do not include the :mod:`logging` package in the standard
827 library.
828
829
830Logger Objects
831--------------
832
833Loggers have the following attributes and methods. Note that Loggers are never
834instantiated directly, but always through the module-level function
835``logging.getLogger(name)``.
836
837
838.. attribute:: Logger.propagate
839
840 If this evaluates to false, logging messages are not passed by this logger or by
841 child loggers to higher level (ancestor) loggers. The constructor sets this
842 attribute to 1.
843
844
845.. method:: Logger.setLevel(lvl)
846
847 Sets the threshold for this logger to *lvl*. Logging messages which are less
848 severe than *lvl* will be ignored. When a logger is created, the level is set to
849 :const:`NOTSET` (which causes all messages to be processed when the logger is
850 the root logger, or delegation to the parent when the logger is a non-root
851 logger). Note that the root logger is created with level :const:`WARNING`.
852
853 The term "delegation to the parent" means that if a logger has a level of
854 NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
855 a level other than NOTSET is found, or the root is reached.
856
857 If an ancestor is found with a level other than NOTSET, then that ancestor's
858 level is treated as the effective level of the logger where the ancestor search
859 began, and is used to determine how a logging event is handled.
860
861 If the root is reached, and it has a level of NOTSET, then all messages will be
862 processed. Otherwise, the root's level will be used as the effective level.
863
864
865.. method:: Logger.isEnabledFor(lvl)
866
867 Indicates if a message of severity *lvl* would be processed by this logger.
868 This method checks first the module-level level set by
869 ``logging.disable(lvl)`` and then the logger's effective level as determined
870 by :meth:`getEffectiveLevel`.
871
872
873.. method:: Logger.getEffectiveLevel()
874
875 Indicates the effective level for this logger. If a value other than
876 :const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise,
877 the hierarchy is traversed towards the root until a value other than
878 :const:`NOTSET` is found, and that value is returned.
879
880
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000881.. method:: Logger.debug(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000882
883 Logs a message with level :const:`DEBUG` on this logger. The *msg* is the
884 message format string, and the *args* are the arguments which are merged into
885 *msg* using the string formatting operator. (Note that this means that you can
886 use keywords in the format string, together with a single dictionary argument.)
887
888 There are two keyword arguments in *kwargs* which are inspected: *exc_info*
889 which, if it does not evaluate as false, causes exception information to be
890 added to the logging message. If an exception tuple (in the format returned by
891 :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`
892 is called to get the exception information.
893
894 The other optional keyword argument is *extra* which can be used to pass a
895 dictionary which is used to populate the __dict__ of the LogRecord created for
896 the logging event with user-defined attributes. These custom attributes can then
897 be used as you like. For example, they could be incorporated into logged
898 messages. For example::
899
900 FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
901 logging.basicConfig(format=FORMAT)
Georg Brandl9afde1c2007-11-01 20:32:30 +0000902 d = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' }
Georg Brandl116aa622007-08-15 14:28:22 +0000903 logger = logging.getLogger("tcpserver")
904 logger.warning("Protocol problem: %s", "connection reset", extra=d)
905
906 would print something like ::
907
908 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
909
910 The keys in the dictionary passed in *extra* should not clash with the keys used
911 by the logging system. (See the :class:`Formatter` documentation for more
912 information on which keys are used by the logging system.)
913
914 If you choose to use these attributes in logged messages, you need to exercise
915 some care. In the above example, for instance, the :class:`Formatter` has been
916 set up with a format string which expects 'clientip' and 'user' in the attribute
917 dictionary of the LogRecord. If these are missing, the message will not be
918 logged because a string formatting exception will occur. So in this case, you
919 always need to pass the *extra* dictionary with these keys.
920
921 While this might be annoying, this feature is intended for use in specialized
922 circumstances, such as multi-threaded servers where the same code executes in
923 many contexts, and interesting conditions which arise are dependent on this
924 context (such as remote client IP address and authenticated user name, in the
925 above example). In such circumstances, it is likely that specialized
926 :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
927
Georg Brandl116aa622007-08-15 14:28:22 +0000928
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000929.. method:: Logger.info(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000930
931 Logs a message with level :const:`INFO` on this logger. The arguments are
932 interpreted as for :meth:`debug`.
933
934
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000935.. method:: Logger.warning(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000936
937 Logs a message with level :const:`WARNING` on this logger. The arguments are
938 interpreted as for :meth:`debug`.
939
940
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000941.. method:: Logger.error(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000942
943 Logs a message with level :const:`ERROR` on this logger. The arguments are
944 interpreted as for :meth:`debug`.
945
946
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000947.. method:: Logger.critical(msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000948
949 Logs a message with level :const:`CRITICAL` on this logger. The arguments are
950 interpreted as for :meth:`debug`.
951
952
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000953.. method:: Logger.log(lvl, msg, *args, **kwargs)
Georg Brandl116aa622007-08-15 14:28:22 +0000954
955 Logs a message with integer level *lvl* on this logger. The other arguments are
956 interpreted as for :meth:`debug`.
957
958
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000959.. method:: Logger.exception(msg, *args)
Georg Brandl116aa622007-08-15 14:28:22 +0000960
961 Logs a message with level :const:`ERROR` on this logger. The arguments are
962 interpreted as for :meth:`debug`. Exception info is added to the logging
963 message. This method should only be called from an exception handler.
964
965
966.. method:: Logger.addFilter(filt)
967
968 Adds the specified filter *filt* to this logger.
969
970
971.. method:: Logger.removeFilter(filt)
972
973 Removes the specified filter *filt* from this logger.
974
975
976.. method:: Logger.filter(record)
977
978 Applies this logger's filters to the record and returns a true value if the
979 record is to be processed.
980
981
982.. method:: Logger.addHandler(hdlr)
983
984 Adds the specified handler *hdlr* to this logger.
985
986
987.. method:: Logger.removeHandler(hdlr)
988
989 Removes the specified handler *hdlr* from this logger.
990
991
992.. method:: Logger.findCaller()
993
994 Finds the caller's source filename and line number. Returns the filename, line
995 number and function name as a 3-element tuple.
996
Georg Brandl116aa622007-08-15 14:28:22 +0000997
998.. method:: Logger.handle(record)
999
1000 Handles a record by passing it to all handlers associated with this logger and
1001 its ancestors (until a false value of *propagate* is found). This method is used
1002 for unpickled records received from a socket, as well as those created locally.
Georg Brandl502d9a52009-07-26 15:02:41 +00001003 Logger-level filtering is applied using :meth:`~Logger.filter`.
Georg Brandl116aa622007-08-15 14:28:22 +00001004
1005
Georg Brandlcd7f32b2009-06-08 09:13:45 +00001006.. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001007
1008 This is a factory method which can be overridden in subclasses to create
1009 specialized :class:`LogRecord` instances.
1010
Georg Brandl116aa622007-08-15 14:28:22 +00001011
1012.. _minimal-example:
1013
1014Basic example
1015-------------
1016
Georg Brandl116aa622007-08-15 14:28:22 +00001017The :mod:`logging` package provides a lot of flexibility, and its configuration
1018can appear daunting. This section demonstrates that simple use of the logging
1019package is possible.
1020
1021The simplest example shows logging to the console::
1022
1023 import logging
1024
1025 logging.debug('A debug message')
1026 logging.info('Some information')
1027 logging.warning('A shot across the bows')
1028
1029If you run the above script, you'll see this::
1030
1031 WARNING:root:A shot across the bows
1032
1033Because no particular logger was specified, the system used the root logger. The
1034debug and info messages didn't appear because by default, the root logger is
1035configured to only handle messages with a severity of WARNING or above. The
1036message format is also a configuration default, as is the output destination of
1037the messages - ``sys.stderr``. The severity level, the message format and
1038destination can be easily changed, as shown in the example below::
1039
1040 import logging
1041
1042 logging.basicConfig(level=logging.DEBUG,
1043 format='%(asctime)s %(levelname)s %(message)s',
1044 filename='/tmp/myapp.log',
1045 filemode='w')
1046 logging.debug('A debug message')
1047 logging.info('Some information')
1048 logging.warning('A shot across the bows')
1049
1050The :meth:`basicConfig` method is used to change the configuration defaults,
1051which results in output (written to ``/tmp/myapp.log``) which should look
1052something like the following::
1053
1054 2004-07-02 13:00:08,743 DEBUG A debug message
1055 2004-07-02 13:00:08,743 INFO Some information
1056 2004-07-02 13:00:08,743 WARNING A shot across the bows
1057
1058This time, all messages with a severity of DEBUG or above were handled, and the
1059format of the messages was also changed, and output went to the specified file
1060rather than the console.
1061
Georg Brandl81ac1ce2007-08-31 17:17:17 +00001062.. XXX logging should probably be updated for new string formatting!
Georg Brandl4b491312007-08-31 09:22:56 +00001063
1064Formatting uses the old Python string formatting - see section
1065:ref:`old-string-formatting`. The format string takes the following common
Georg Brandl116aa622007-08-15 14:28:22 +00001066specifiers. For a complete list of specifiers, consult the :class:`Formatter`
1067documentation.
1068
1069+-------------------+-----------------------------------------------+
1070| Format | Description |
1071+===================+===============================================+
1072| ``%(name)s`` | Name of the logger (logging channel). |
1073+-------------------+-----------------------------------------------+
1074| ``%(levelname)s`` | Text logging level for the message |
1075| | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
1076| | ``'ERROR'``, ``'CRITICAL'``). |
1077+-------------------+-----------------------------------------------+
1078| ``%(asctime)s`` | Human-readable time when the |
1079| | :class:`LogRecord` was created. By default |
1080| | this is of the form "2003-07-08 16:49:45,896" |
1081| | (the numbers after the comma are millisecond |
1082| | portion of the time). |
1083+-------------------+-----------------------------------------------+
1084| ``%(message)s`` | The logged message. |
1085+-------------------+-----------------------------------------------+
1086
1087To change the date/time format, you can pass an additional keyword parameter,
1088*datefmt*, as in the following::
1089
1090 import logging
1091
1092 logging.basicConfig(level=logging.DEBUG,
1093 format='%(asctime)s %(levelname)-8s %(message)s',
1094 datefmt='%a, %d %b %Y %H:%M:%S',
1095 filename='/temp/myapp.log',
1096 filemode='w')
1097 logging.debug('A debug message')
1098 logging.info('Some information')
1099 logging.warning('A shot across the bows')
1100
1101which would result in output like ::
1102
1103 Fri, 02 Jul 2004 13:06:18 DEBUG A debug message
1104 Fri, 02 Jul 2004 13:06:18 INFO Some information
1105 Fri, 02 Jul 2004 13:06:18 WARNING A shot across the bows
1106
1107The date format string follows the requirements of :func:`strftime` - see the
1108documentation for the :mod:`time` module.
1109
1110If, instead of sending logging output to the console or a file, you'd rather use
1111a file-like object which you have created separately, you can pass it to
1112:func:`basicConfig` using the *stream* keyword argument. Note that if both
1113*stream* and *filename* keyword arguments are passed, the *stream* argument is
1114ignored.
1115
1116Of course, you can put variable information in your output. To do this, simply
1117have the message be a format string and pass in additional arguments containing
1118the variable information, as in the following example::
1119
1120 import logging
1121
1122 logging.basicConfig(level=logging.DEBUG,
1123 format='%(asctime)s %(levelname)-8s %(message)s',
1124 datefmt='%a, %d %b %Y %H:%M:%S',
1125 filename='/temp/myapp.log',
1126 filemode='w')
1127 logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs')
1128
1129which would result in ::
1130
1131 Wed, 21 Jul 2004 15:35:16 ERROR Pack my box with 5 dozen liquor jugs
1132
1133
1134.. _multiple-destinations:
1135
1136Logging to multiple destinations
1137--------------------------------
1138
1139Let's say you want to log to console and file with different message formats and
1140in differing circumstances. Say you want to log messages with levels of DEBUG
1141and higher to file, and those messages at level INFO and higher to the console.
1142Let's also assume that the file should contain timestamps, but the console
1143messages should not. Here's how you can achieve this::
1144
1145 import logging
1146
1147 # set up logging to file - see previous section for more details
1148 logging.basicConfig(level=logging.DEBUG,
1149 format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
1150 datefmt='%m-%d %H:%M',
1151 filename='/temp/myapp.log',
1152 filemode='w')
1153 # define a Handler which writes INFO messages or higher to the sys.stderr
1154 console = logging.StreamHandler()
1155 console.setLevel(logging.INFO)
1156 # set a format which is simpler for console use
1157 formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
1158 # tell the handler to use this format
1159 console.setFormatter(formatter)
1160 # add the handler to the root logger
1161 logging.getLogger('').addHandler(console)
1162
1163 # Now, we can log to the root logger, or any other logger. First the root...
1164 logging.info('Jackdaws love my big sphinx of quartz.')
1165
1166 # Now, define a couple of other loggers which might represent areas in your
1167 # application:
1168
1169 logger1 = logging.getLogger('myapp.area1')
1170 logger2 = logging.getLogger('myapp.area2')
1171
1172 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
1173 logger1.info('How quickly daft jumping zebras vex.')
1174 logger2.warning('Jail zesty vixen who grabbed pay from quack.')
1175 logger2.error('The five boxing wizards jump quickly.')
1176
1177When you run this, on the console you will see ::
1178
1179 root : INFO Jackdaws love my big sphinx of quartz.
1180 myapp.area1 : INFO How quickly daft jumping zebras vex.
1181 myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.
1182 myapp.area2 : ERROR The five boxing wizards jump quickly.
1183
1184and in the file you will see something like ::
1185
1186 10-22 22:19 root INFO Jackdaws love my big sphinx of quartz.
1187 10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
1188 10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex.
1189 10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
1190 10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly.
1191
1192As you can see, the DEBUG message only shows up in the file. The other messages
1193are sent to both destinations.
1194
1195This example uses console and file handlers, but you can use any number and
1196combination of handlers you choose.
1197
Vinay Sajip3ee22ec2009-08-20 22:05:10 +00001198.. _logging-exceptions:
1199
1200Exceptions raised during logging
1201--------------------------------
1202
1203The logging package is designed to swallow exceptions which occur while logging
1204in production. This is so that errors which occur while handling logging events
1205- such as logging misconfiguration, network or other similar errors - do not
1206cause the application using logging to terminate prematurely.
1207
1208:class:`SystemExit` and :class:`KeyboardInterrupt` exceptions are never
1209swallowed. Other exceptions which occur during the :meth:`emit` method of a
1210:class:`Handler` subclass are passed to its :meth:`handleError` method.
1211
1212The default implementation of :meth:`handleError` in :class:`Handler` checks
1213to see if a module-level variable, `raiseExceptions`, is set. If set, a
1214traceback is printed to `sys.stderr`. If not set, the exception is swallowed.
1215
1216**Note:** The default value of `raiseExceptions` is `True`. This is because
1217during development, you typically want to be notified of any exceptions that
1218occur. It's advised that you set `raiseExceptions` to `False` for production
1219usage.
Georg Brandl116aa622007-08-15 14:28:22 +00001220
Christian Heimes790c8232008-01-07 21:14:23 +00001221.. _context-info:
1222
1223Adding contextual information to your logging output
1224----------------------------------------------------
1225
1226Sometimes you want logging output to contain contextual information in
1227addition to the parameters passed to the logging call. For example, in a
1228networked application, it may be desirable to log client-specific information
1229in the log (e.g. remote client's username, or IP address). Although you could
1230use the *extra* parameter to achieve this, it's not always convenient to pass
1231the information in this way. While it might be tempting to create
1232:class:`Logger` instances on a per-connection basis, this is not a good idea
1233because these instances are not garbage collected. While this is not a problem
1234in practice, when the number of :class:`Logger` instances is dependent on the
1235level of granularity you want to use in logging an application, it could
1236be hard to manage if the number of :class:`Logger` instances becomes
1237effectively unbounded.
1238
Christian Heimes04c420f2008-01-18 18:40:46 +00001239An easy way in which you can pass contextual information to be output along
1240with logging event information is to use the :class:`LoggerAdapter` class.
1241This class is designed to look like a :class:`Logger`, so that you can call
1242:meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`,
1243:meth:`exception`, :meth:`critical` and :meth:`log`. These methods have the
1244same signatures as their counterparts in :class:`Logger`, so you can use the
1245two types of instances interchangeably.
Christian Heimes790c8232008-01-07 21:14:23 +00001246
Christian Heimes04c420f2008-01-18 18:40:46 +00001247When you create an instance of :class:`LoggerAdapter`, you pass it a
1248:class:`Logger` instance and a dict-like object which contains your contextual
1249information. When you call one of the logging methods on an instance of
1250:class:`LoggerAdapter`, it delegates the call to the underlying instance of
1251:class:`Logger` passed to its constructor, and arranges to pass the contextual
1252information in the delegated call. Here's a snippet from the code of
1253:class:`LoggerAdapter`::
Christian Heimes790c8232008-01-07 21:14:23 +00001254
Christian Heimes04c420f2008-01-18 18:40:46 +00001255 def debug(self, msg, *args, **kwargs):
1256 """
1257 Delegate a debug call to the underlying logger, after adding
1258 contextual information from this adapter instance.
1259 """
1260 msg, kwargs = self.process(msg, kwargs)
1261 self.logger.debug(msg, *args, **kwargs)
Christian Heimes790c8232008-01-07 21:14:23 +00001262
Christian Heimes04c420f2008-01-18 18:40:46 +00001263The :meth:`process` method of :class:`LoggerAdapter` is where the contextual
1264information is added to the logging output. It's passed the message and
1265keyword arguments of the logging call, and it passes back (potentially)
1266modified versions of these to use in the call to the underlying logger. The
1267default implementation of this method leaves the message alone, but inserts
1268an "extra" key in the keyword argument whose value is the dict-like object
1269passed to the constructor. Of course, if you had passed an "extra" keyword
1270argument in the call to the adapter, it will be silently overwritten.
Christian Heimes790c8232008-01-07 21:14:23 +00001271
Christian Heimes04c420f2008-01-18 18:40:46 +00001272The advantage of using "extra" is that the values in the dict-like object are
1273merged into the :class:`LogRecord` instance's __dict__, allowing you to use
1274customized strings with your :class:`Formatter` instances which know about
1275the keys of the dict-like object. If you need a different method, e.g. if you
1276want to prepend or append the contextual information to the message string,
1277you just need to subclass :class:`LoggerAdapter` and override :meth:`process`
1278to do what you need. Here's an example script which uses this class, which
1279also illustrates what dict-like behaviour is needed from an arbitrary
1280"dict-like" object for use in the constructor::
1281
Christian Heimes587c2bf2008-01-19 16:21:02 +00001282 import logging
Georg Brandl86def6c2008-01-21 20:36:10 +00001283
Christian Heimes587c2bf2008-01-19 16:21:02 +00001284 class ConnInfo:
1285 """
1286 An example class which shows how an arbitrary class can be used as
1287 the 'extra' context information repository passed to a LoggerAdapter.
1288 """
Georg Brandl86def6c2008-01-21 20:36:10 +00001289
Christian Heimes587c2bf2008-01-19 16:21:02 +00001290 def __getitem__(self, name):
1291 """
1292 To allow this instance to look like a dict.
1293 """
1294 from random import choice
1295 if name == "ip":
1296 result = choice(["127.0.0.1", "192.168.0.1"])
1297 elif name == "user":
1298 result = choice(["jim", "fred", "sheila"])
1299 else:
1300 result = self.__dict__.get(name, "?")
1301 return result
Georg Brandl86def6c2008-01-21 20:36:10 +00001302
Christian Heimes587c2bf2008-01-19 16:21:02 +00001303 def __iter__(self):
1304 """
1305 To allow iteration over keys, which will be merged into
1306 the LogRecord dict before formatting and output.
1307 """
1308 keys = ["ip", "user"]
1309 keys.extend(self.__dict__.keys())
1310 return keys.__iter__()
Georg Brandl86def6c2008-01-21 20:36:10 +00001311
Christian Heimes587c2bf2008-01-19 16:21:02 +00001312 if __name__ == "__main__":
1313 from random import choice
1314 levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
1315 a1 = logging.LoggerAdapter(logging.getLogger("a.b.c"),
1316 { "ip" : "123.231.231.123", "user" : "sheila" })
1317 logging.basicConfig(level=logging.DEBUG,
1318 format="%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s")
1319 a1.debug("A debug message")
1320 a1.info("An info message with %s", "some parameters")
1321 a2 = logging.LoggerAdapter(logging.getLogger("d.e.f"), ConnInfo())
1322 for x in range(10):
1323 lvl = choice(levels)
1324 lvlname = logging.getLevelName(lvl)
1325 a2.log(lvl, "A message at %s level with %d %s", lvlname, 2, "parameters")
Christian Heimes04c420f2008-01-18 18:40:46 +00001326
1327When this script is run, the output should look something like this::
1328
Christian Heimes587c2bf2008-01-19 16:21:02 +00001329 2008-01-18 14:49:54,023 a.b.c DEBUG IP: 123.231.231.123 User: sheila A debug message
1330 2008-01-18 14:49:54,023 a.b.c INFO IP: 123.231.231.123 User: sheila An info message with some parameters
1331 2008-01-18 14:49:54,023 d.e.f CRITICAL IP: 192.168.0.1 User: jim A message at CRITICAL level with 2 parameters
1332 2008-01-18 14:49:54,033 d.e.f INFO IP: 192.168.0.1 User: jim A message at INFO level with 2 parameters
1333 2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters
1334 2008-01-18 14:49:54,033 d.e.f ERROR IP: 127.0.0.1 User: fred A message at ERROR level with 2 parameters
1335 2008-01-18 14:49:54,033 d.e.f ERROR IP: 127.0.0.1 User: sheila A message at ERROR level with 2 parameters
1336 2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters
1337 2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: jim A message at WARNING level with 2 parameters
1338 2008-01-18 14:49:54,033 d.e.f INFO IP: 192.168.0.1 User: fred A message at INFO level with 2 parameters
1339 2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters
1340 2008-01-18 14:49:54,033 d.e.f WARNING IP: 127.0.0.1 User: jim A message at WARNING level with 2 parameters
Christian Heimes04c420f2008-01-18 18:40:46 +00001341
Christian Heimes790c8232008-01-07 21:14:23 +00001342
Vinay Sajipa7471bf2009-08-15 23:23:37 +00001343Logging to a single file from multiple processes
1344------------------------------------------------
1345
1346Although logging is thread-safe, and logging to a single file from multiple
1347threads in a single process *is* supported, logging to a single file from
1348*multiple processes* is *not* supported, because there is no standard way to
1349serialize access to a single file across multiple processes in Python. If you
1350need to log to a single file from multiple processes, the best way of doing
1351this is to have all the processes log to a :class:`SocketHandler`, and have a
1352separate process which implements a socket server which reads from the socket
1353and logs to file. (If you prefer, you can dedicate one thread in one of the
1354existing processes to perform this function.) The following section documents
1355this approach in more detail and includes a working socket receiver which can
1356be used as a starting point for you to adapt in your own applications.
1357
Vinay Sajip5a92b132009-08-15 23:35:08 +00001358If you are using a recent version of Python which includes the
1359:mod:`multiprocessing` module, you can write your own handler which uses the
1360:class:`Lock` class from this module to serialize access to the file from
1361your processes. The existing :class:`FileHandler` and subclasses do not make
1362use of :mod:`multiprocessing` at present, though they may do so in the future.
Vinay Sajip8c6b0a52009-08-17 13:17:47 +00001363Note that at present, the :mod:`multiprocessing` module does not provide
1364working lock functionality on all platforms (see
1365http://bugs.python.org/issue3770).
Vinay Sajip5a92b132009-08-15 23:35:08 +00001366
Benjamin Peterson8719ad52009-09-11 22:24:02 +00001367
Georg Brandl116aa622007-08-15 14:28:22 +00001368.. _network-logging:
1369
1370Sending and receiving logging events across a network
1371-----------------------------------------------------
1372
1373Let's say you want to send logging events across a network, and handle them at
1374the receiving end. A simple way of doing this is attaching a
1375:class:`SocketHandler` instance to the root logger at the sending end::
1376
1377 import logging, logging.handlers
1378
1379 rootLogger = logging.getLogger('')
1380 rootLogger.setLevel(logging.DEBUG)
1381 socketHandler = logging.handlers.SocketHandler('localhost',
1382 logging.handlers.DEFAULT_TCP_LOGGING_PORT)
1383 # don't bother with a formatter, since a socket handler sends the event as
1384 # an unformatted pickle
1385 rootLogger.addHandler(socketHandler)
1386
1387 # Now, we can log to the root logger, or any other logger. First the root...
1388 logging.info('Jackdaws love my big sphinx of quartz.')
1389
1390 # Now, define a couple of other loggers which might represent areas in your
1391 # application:
1392
1393 logger1 = logging.getLogger('myapp.area1')
1394 logger2 = logging.getLogger('myapp.area2')
1395
1396 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
1397 logger1.info('How quickly daft jumping zebras vex.')
1398 logger2.warning('Jail zesty vixen who grabbed pay from quack.')
1399 logger2.error('The five boxing wizards jump quickly.')
1400
Alexandre Vassalottice261952008-05-12 02:31:37 +00001401At the receiving end, you can set up a receiver using the :mod:`socketserver`
Georg Brandl116aa622007-08-15 14:28:22 +00001402module. Here is a basic working example::
1403
Georg Brandla35f4b92009-05-31 16:41:59 +00001404 import pickle
Georg Brandl116aa622007-08-15 14:28:22 +00001405 import logging
1406 import logging.handlers
Alexandre Vassalottice261952008-05-12 02:31:37 +00001407 import socketserver
Georg Brandl116aa622007-08-15 14:28:22 +00001408 import struct
1409
1410
Alexandre Vassalottice261952008-05-12 02:31:37 +00001411 class LogRecordStreamHandler(socketserver.StreamRequestHandler):
Georg Brandl116aa622007-08-15 14:28:22 +00001412 """Handler for a streaming logging request.
1413
1414 This basically logs the record using whatever logging policy is
1415 configured locally.
1416 """
1417
1418 def handle(self):
1419 """
1420 Handle multiple requests - each expected to be a 4-byte length,
1421 followed by the LogRecord in pickle format. Logs the record
1422 according to whatever policy is configured locally.
1423 """
Collin Winter46334482007-09-10 00:49:57 +00001424 while True:
Georg Brandl116aa622007-08-15 14:28:22 +00001425 chunk = self.connection.recv(4)
1426 if len(chunk) < 4:
1427 break
1428 slen = struct.unpack(">L", chunk)[0]
1429 chunk = self.connection.recv(slen)
1430 while len(chunk) < slen:
1431 chunk = chunk + self.connection.recv(slen - len(chunk))
1432 obj = self.unPickle(chunk)
1433 record = logging.makeLogRecord(obj)
1434 self.handleLogRecord(record)
1435
1436 def unPickle(self, data):
Georg Brandla35f4b92009-05-31 16:41:59 +00001437 return pickle.loads(data)
Georg Brandl116aa622007-08-15 14:28:22 +00001438
1439 def handleLogRecord(self, record):
1440 # if a name is specified, we use the named logger rather than the one
1441 # implied by the record.
1442 if self.server.logname is not None:
1443 name = self.server.logname
1444 else:
1445 name = record.name
1446 logger = logging.getLogger(name)
1447 # N.B. EVERY record gets logged. This is because Logger.handle
1448 # is normally called AFTER logger-level filtering. If you want
1449 # to do filtering, do it at the client end to save wasting
1450 # cycles and network bandwidth!
1451 logger.handle(record)
1452
Alexandre Vassalottice261952008-05-12 02:31:37 +00001453 class LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
Georg Brandl116aa622007-08-15 14:28:22 +00001454 """simple TCP socket-based logging receiver suitable for testing.
1455 """
1456
1457 allow_reuse_address = 1
1458
1459 def __init__(self, host='localhost',
1460 port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
1461 handler=LogRecordStreamHandler):
Alexandre Vassalottice261952008-05-12 02:31:37 +00001462 socketserver.ThreadingTCPServer.__init__(self, (host, port), handler)
Georg Brandl116aa622007-08-15 14:28:22 +00001463 self.abort = 0
1464 self.timeout = 1
1465 self.logname = None
1466
1467 def serve_until_stopped(self):
1468 import select
1469 abort = 0
1470 while not abort:
1471 rd, wr, ex = select.select([self.socket.fileno()],
1472 [], [],
1473 self.timeout)
1474 if rd:
1475 self.handle_request()
1476 abort = self.abort
1477
1478 def main():
1479 logging.basicConfig(
1480 format="%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s")
1481 tcpserver = LogRecordSocketReceiver()
Georg Brandl6911e3c2007-09-04 07:15:32 +00001482 print("About to start TCP server...")
Georg Brandl116aa622007-08-15 14:28:22 +00001483 tcpserver.serve_until_stopped()
1484
1485 if __name__ == "__main__":
1486 main()
1487
1488First run the server, and then the client. On the client side, nothing is
1489printed on the console; on the server side, you should see something like::
1490
1491 About to start TCP server...
1492 59 root INFO Jackdaws love my big sphinx of quartz.
1493 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
1494 69 myapp.area1 INFO How quickly daft jumping zebras vex.
1495 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
1496 69 myapp.area2 ERROR The five boxing wizards jump quickly.
1497
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001498Using arbitrary objects as messages
1499-----------------------------------
1500
1501In the preceding sections and examples, it has been assumed that the message
1502passed when logging the event is a string. However, this is not the only
1503possibility. You can pass an arbitrary object as a message, and its
1504:meth:`__str__` method will be called when the logging system needs to convert
1505it to a string representation. In fact, if you want to, you can avoid
1506computing a string representation altogether - for example, the
1507:class:`SocketHandler` emits an event by pickling it and sending it over the
1508wire.
1509
1510Optimization
1511------------
1512
1513Formatting of message arguments is deferred until it cannot be avoided.
1514However, computing the arguments passed to the logging method can also be
1515expensive, and you may want to avoid doing it if the logger will just throw
1516away your event. To decide what to do, you can call the :meth:`isEnabledFor`
1517method which takes a level argument and returns true if the event would be
1518created by the Logger for that level of call. You can write code like this::
1519
1520 if logger.isEnabledFor(logging.DEBUG):
1521 logger.debug("Message with %s, %s", expensive_func1(),
1522 expensive_func2())
1523
1524so that if the logger's threshold is set above ``DEBUG``, the calls to
1525:func:`expensive_func1` and :func:`expensive_func2` are never made.
1526
1527There are other optimizations which can be made for specific applications which
1528need more precise control over what logging information is collected. Here's a
1529list of things you can do to avoid processing during logging which you don't
1530need:
1531
1532+-----------------------------------------------+----------------------------------------+
1533| What you don't want to collect | How to avoid collecting it |
1534+===============================================+========================================+
1535| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
1536+-----------------------------------------------+----------------------------------------+
1537| Threading information. | Set ``logging.logThreads`` to ``0``. |
1538+-----------------------------------------------+----------------------------------------+
1539| Process information. | Set ``logging.logProcesses`` to ``0``. |
1540+-----------------------------------------------+----------------------------------------+
1541
1542Also note that the core logging module only includes the basic handlers. If
1543you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
1544take up any memory.
1545
1546.. _handler:
Georg Brandl116aa622007-08-15 14:28:22 +00001547
1548Handler Objects
1549---------------
1550
1551Handlers have the following attributes and methods. Note that :class:`Handler`
1552is never instantiated directly; this class acts as a base for more useful
1553subclasses. However, the :meth:`__init__` method in subclasses needs to call
1554:meth:`Handler.__init__`.
1555
1556
1557.. method:: Handler.__init__(level=NOTSET)
1558
1559 Initializes the :class:`Handler` instance by setting its level, setting the list
1560 of filters to the empty list and creating a lock (using :meth:`createLock`) for
1561 serializing access to an I/O mechanism.
1562
1563
1564.. method:: Handler.createLock()
1565
1566 Initializes a thread lock which can be used to serialize access to underlying
1567 I/O functionality which may not be threadsafe.
1568
1569
1570.. method:: Handler.acquire()
1571
1572 Acquires the thread lock created with :meth:`createLock`.
1573
1574
1575.. method:: Handler.release()
1576
1577 Releases the thread lock acquired with :meth:`acquire`.
1578
1579
1580.. method:: Handler.setLevel(lvl)
1581
1582 Sets the threshold for this handler to *lvl*. Logging messages which are less
1583 severe than *lvl* will be ignored. When a handler is created, the level is set
1584 to :const:`NOTSET` (which causes all messages to be processed).
1585
1586
1587.. method:: Handler.setFormatter(form)
1588
1589 Sets the :class:`Formatter` for this handler to *form*.
1590
1591
1592.. method:: Handler.addFilter(filt)
1593
1594 Adds the specified filter *filt* to this handler.
1595
1596
1597.. method:: Handler.removeFilter(filt)
1598
1599 Removes the specified filter *filt* from this handler.
1600
1601
1602.. method:: Handler.filter(record)
1603
1604 Applies this handler's filters to the record and returns a true value if the
1605 record is to be processed.
1606
1607
1608.. method:: Handler.flush()
1609
1610 Ensure all logging output has been flushed. This version does nothing and is
1611 intended to be implemented by subclasses.
1612
1613
1614.. method:: Handler.close()
1615
Benjamin Peterson3e4f0552008-09-02 00:31:15 +00001616 Tidy up any resources used by the handler. This version does no output but
1617 removes the handler from an internal list of handlers which is closed when
1618 :func:`shutdown` is called. Subclasses should ensure that this gets called
1619 from overridden :meth:`close` methods.
Georg Brandl116aa622007-08-15 14:28:22 +00001620
1621
1622.. method:: Handler.handle(record)
1623
1624 Conditionally emits the specified logging record, depending on filters which may
1625 have been added to the handler. Wraps the actual emission of the record with
1626 acquisition/release of the I/O thread lock.
1627
1628
1629.. method:: Handler.handleError(record)
1630
1631 This method should be called from handlers when an exception is encountered
1632 during an :meth:`emit` call. By default it does nothing, which means that
1633 exceptions get silently ignored. This is what is mostly wanted for a logging
1634 system - most users will not care about errors in the logging system, they are
1635 more interested in application errors. You could, however, replace this with a
1636 custom handler if you wish. The specified record is the one which was being
1637 processed when the exception occurred.
1638
1639
1640.. method:: Handler.format(record)
1641
1642 Do formatting for a record - if a formatter is set, use it. Otherwise, use the
1643 default formatter for the module.
1644
1645
1646.. method:: Handler.emit(record)
1647
1648 Do whatever it takes to actually log the specified logging record. This version
1649 is intended to be implemented by subclasses and so raises a
1650 :exc:`NotImplementedError`.
1651
1652
1653StreamHandler
1654^^^^^^^^^^^^^
1655
1656The :class:`StreamHandler` class, located in the core :mod:`logging` package,
1657sends logging output to streams such as *sys.stdout*, *sys.stderr* or any
1658file-like object (or, more precisely, any object which supports :meth:`write`
1659and :meth:`flush` methods).
1660
1661
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001662.. class:: StreamHandler(stream=None)
Georg Brandl116aa622007-08-15 14:28:22 +00001663
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001664 Returns a new instance of the :class:`StreamHandler` class. If *stream* is
Georg Brandl116aa622007-08-15 14:28:22 +00001665 specified, the instance will use it for logging output; otherwise, *sys.stderr*
1666 will be used.
1667
1668
Benjamin Petersone41251e2008-04-25 01:59:09 +00001669 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00001670
Benjamin Petersone41251e2008-04-25 01:59:09 +00001671 If a formatter is specified, it is used to format the record. The record
1672 is then written to the stream with a trailing newline. If exception
1673 information is present, it is formatted using
1674 :func:`traceback.print_exception` and appended to the stream.
Georg Brandl116aa622007-08-15 14:28:22 +00001675
1676
Benjamin Petersone41251e2008-04-25 01:59:09 +00001677 .. method:: flush()
Georg Brandl116aa622007-08-15 14:28:22 +00001678
Benjamin Petersone41251e2008-04-25 01:59:09 +00001679 Flushes the stream by calling its :meth:`flush` method. Note that the
1680 :meth:`close` method is inherited from :class:`Handler` and so does
Benjamin Peterson3e4f0552008-09-02 00:31:15 +00001681 no output, so an explicit :meth:`flush` call may be needed at times.
Georg Brandl116aa622007-08-15 14:28:22 +00001682
1683
1684FileHandler
1685^^^^^^^^^^^
1686
1687The :class:`FileHandler` class, located in the core :mod:`logging` package,
1688sends logging output to a disk file. It inherits the output functionality from
1689:class:`StreamHandler`.
1690
1691
Georg Brandlcd7f32b2009-06-08 09:13:45 +00001692.. class:: FileHandler(filename, mode='a', encoding=None, delay=0)
Georg Brandl116aa622007-08-15 14:28:22 +00001693
1694 Returns a new instance of the :class:`FileHandler` class. The specified file is
1695 opened and used as the stream for logging. If *mode* is not specified,
1696 :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file
Christian Heimese7a15bb2008-01-24 16:21:45 +00001697 with that encoding. If *delay* is true, then file opening is deferred until the
1698 first call to :meth:`emit`. By default, the file grows indefinitely.
Georg Brandl116aa622007-08-15 14:28:22 +00001699
1700
Benjamin Petersone41251e2008-04-25 01:59:09 +00001701 .. method:: close()
Georg Brandl116aa622007-08-15 14:28:22 +00001702
Benjamin Petersone41251e2008-04-25 01:59:09 +00001703 Closes the file.
Georg Brandl116aa622007-08-15 14:28:22 +00001704
1705
Benjamin Petersone41251e2008-04-25 01:59:09 +00001706 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00001707
Benjamin Petersone41251e2008-04-25 01:59:09 +00001708 Outputs the record to the file.
Georg Brandl116aa622007-08-15 14:28:22 +00001709
1710
Vinay Sajipaa672eb2009-01-02 18:53:45 +00001711NullHandler
1712^^^^^^^^^^^
1713
1714.. versionadded:: 3.1
1715
1716The :class:`NullHandler` class, located in the core :mod:`logging` package,
1717does not do any formatting or output. It is essentially a "no-op" handler
1718for use by library developers.
1719
1720
1721.. class:: NullHandler()
1722
1723 Returns a new instance of the :class:`NullHandler` class.
1724
1725
1726 .. method:: emit(record)
1727
1728 This method does nothing.
1729
Vinay Sajip26a2d5e2009-01-10 13:37:26 +00001730See :ref:`library-config` for more information on how to use
1731:class:`NullHandler`.
Benjamin Peterson960cf0f2009-01-09 04:11:44 +00001732
Georg Brandl116aa622007-08-15 14:28:22 +00001733WatchedFileHandler
1734^^^^^^^^^^^^^^^^^^
1735
Benjamin Peterson058e31e2009-01-16 03:54:08 +00001736.. currentmodule:: logging.handlers
Vinay Sajipaa672eb2009-01-02 18:53:45 +00001737
Georg Brandl116aa622007-08-15 14:28:22 +00001738The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers`
1739module, is a :class:`FileHandler` which watches the file it is logging to. If
1740the file changes, it is closed and reopened using the file name.
1741
1742A file change can happen because of usage of programs such as *newsyslog* and
1743*logrotate* which perform log file rotation. This handler, intended for use
1744under Unix/Linux, watches the file to see if it has changed since the last emit.
1745(A file is deemed to have changed if its device or inode have changed.) If the
1746file has changed, the old file stream is closed, and the file opened to get a
1747new stream.
1748
1749This handler is not appropriate for use under Windows, because under Windows
1750open log files cannot be moved or renamed - logging opens the files with
1751exclusive locks - and so there is no need for such a handler. Furthermore,
1752*ST_INO* is not supported under Windows; :func:`stat` always returns zero for
1753this value.
1754
1755
Christian Heimese7a15bb2008-01-24 16:21:45 +00001756.. class:: WatchedFileHandler(filename[,mode[, encoding[, delay]]])
Georg Brandl116aa622007-08-15 14:28:22 +00001757
1758 Returns a new instance of the :class:`WatchedFileHandler` class. The specified
1759 file is opened and used as the stream for logging. If *mode* is not specified,
1760 :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file
Christian Heimese7a15bb2008-01-24 16:21:45 +00001761 with that encoding. If *delay* is true, then file opening is deferred until the
1762 first call to :meth:`emit`. By default, the file grows indefinitely.
Georg Brandl116aa622007-08-15 14:28:22 +00001763
1764
Benjamin Petersone41251e2008-04-25 01:59:09 +00001765 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00001766
Benjamin Petersone41251e2008-04-25 01:59:09 +00001767 Outputs the record to the file, but first checks to see if the file has
1768 changed. If it has, the existing stream is flushed and closed and the
1769 file opened again, before outputting the record to the file.
Georg Brandl116aa622007-08-15 14:28:22 +00001770
1771
1772RotatingFileHandler
1773^^^^^^^^^^^^^^^^^^^
1774
1775The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers`
1776module, supports rotation of disk log files.
1777
1778
Georg Brandlcd7f32b2009-06-08 09:13:45 +00001779.. class:: RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=0)
Georg Brandl116aa622007-08-15 14:28:22 +00001780
1781 Returns a new instance of the :class:`RotatingFileHandler` class. The specified
1782 file is opened and used as the stream for logging. If *mode* is not specified,
Christian Heimese7a15bb2008-01-24 16:21:45 +00001783 ``'a'`` is used. If *encoding* is not *None*, it is used to open the file
1784 with that encoding. If *delay* is true, then file opening is deferred until the
1785 first call to :meth:`emit`. By default, the file grows indefinitely.
Georg Brandl116aa622007-08-15 14:28:22 +00001786
1787 You can use the *maxBytes* and *backupCount* values to allow the file to
1788 :dfn:`rollover` at a predetermined size. When the size is about to be exceeded,
1789 the file is closed and a new file is silently opened for output. Rollover occurs
1790 whenever the current log file is nearly *maxBytes* in length; if *maxBytes* is
1791 zero, rollover never occurs. If *backupCount* is non-zero, the system will save
1792 old log files by appending the extensions ".1", ".2" etc., to the filename. For
1793 example, with a *backupCount* of 5 and a base file name of :file:`app.log`, you
1794 would get :file:`app.log`, :file:`app.log.1`, :file:`app.log.2`, up to
1795 :file:`app.log.5`. The file being written to is always :file:`app.log`. When
1796 this file is filled, it is closed and renamed to :file:`app.log.1`, and if files
1797 :file:`app.log.1`, :file:`app.log.2`, etc. exist, then they are renamed to
1798 :file:`app.log.2`, :file:`app.log.3` etc. respectively.
1799
1800
Benjamin Petersone41251e2008-04-25 01:59:09 +00001801 .. method:: doRollover()
Georg Brandl116aa622007-08-15 14:28:22 +00001802
Benjamin Petersone41251e2008-04-25 01:59:09 +00001803 Does a rollover, as described above.
Georg Brandl116aa622007-08-15 14:28:22 +00001804
1805
Benjamin Petersone41251e2008-04-25 01:59:09 +00001806 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00001807
Benjamin Petersone41251e2008-04-25 01:59:09 +00001808 Outputs the record to the file, catering for rollover as described
1809 previously.
Georg Brandl116aa622007-08-15 14:28:22 +00001810
1811
1812TimedRotatingFileHandler
1813^^^^^^^^^^^^^^^^^^^^^^^^
1814
1815The :class:`TimedRotatingFileHandler` class, located in the
1816:mod:`logging.handlers` module, supports rotation of disk log files at certain
1817timed intervals.
1818
1819
Georg Brandlcd7f32b2009-06-08 09:13:45 +00001820.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=0, utc=False)
Georg Brandl116aa622007-08-15 14:28:22 +00001821
1822 Returns a new instance of the :class:`TimedRotatingFileHandler` class. The
1823 specified file is opened and used as the stream for logging. On rotating it also
1824 sets the filename suffix. Rotating happens based on the product of *when* and
1825 *interval*.
1826
1827 You can use the *when* to specify the type of *interval*. The list of possible
Georg Brandl0c77a822008-06-10 16:37:50 +00001828 values is below. Note that they are not case sensitive.
Georg Brandl116aa622007-08-15 14:28:22 +00001829
Christian Heimesb558a2e2008-03-02 22:46:37 +00001830 +----------------+-----------------------+
1831 | Value | Type of interval |
1832 +================+=======================+
1833 | ``'S'`` | Seconds |
1834 +----------------+-----------------------+
1835 | ``'M'`` | Minutes |
1836 +----------------+-----------------------+
1837 | ``'H'`` | Hours |
1838 +----------------+-----------------------+
1839 | ``'D'`` | Days |
1840 +----------------+-----------------------+
1841 | ``'W'`` | Week day (0=Monday) |
1842 +----------------+-----------------------+
1843 | ``'midnight'`` | Roll over at midnight |
1844 +----------------+-----------------------+
Georg Brandl116aa622007-08-15 14:28:22 +00001845
Christian Heimesb558a2e2008-03-02 22:46:37 +00001846 The system will save old log files by appending extensions to the filename.
1847 The extensions are date-and-time based, using the strftime format
Benjamin Petersonad9d48d2008-04-02 21:49:44 +00001848 ``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on the
Georg Brandl3dbca812008-07-23 16:10:53 +00001849 rollover interval.
Georg Brandl0c77a822008-06-10 16:37:50 +00001850 If the *utc* argument is true, times in UTC will be used; otherwise
1851 local time is used.
1852
1853 If *backupCount* is nonzero, at most *backupCount* files
Benjamin Petersonad9d48d2008-04-02 21:49:44 +00001854 will be kept, and if more would be created when rollover occurs, the oldest
1855 one is deleted. The deletion logic uses the interval to determine which
1856 files to delete, so changing the interval may leave old files lying around.
Georg Brandl116aa622007-08-15 14:28:22 +00001857
1858
Benjamin Petersone41251e2008-04-25 01:59:09 +00001859 .. method:: doRollover()
Georg Brandl116aa622007-08-15 14:28:22 +00001860
Benjamin Petersone41251e2008-04-25 01:59:09 +00001861 Does a rollover, as described above.
Georg Brandl116aa622007-08-15 14:28:22 +00001862
1863
Benjamin Petersone41251e2008-04-25 01:59:09 +00001864 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00001865
Benjamin Petersone41251e2008-04-25 01:59:09 +00001866 Outputs the record to the file, catering for rollover as described above.
Georg Brandl116aa622007-08-15 14:28:22 +00001867
1868
1869SocketHandler
1870^^^^^^^^^^^^^
1871
1872The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module,
1873sends logging output to a network socket. The base class uses a TCP socket.
1874
1875
1876.. class:: SocketHandler(host, port)
1877
1878 Returns a new instance of the :class:`SocketHandler` class intended to
1879 communicate with a remote machine whose address is given by *host* and *port*.
1880
1881
Benjamin Petersone41251e2008-04-25 01:59:09 +00001882 .. method:: close()
Georg Brandl116aa622007-08-15 14:28:22 +00001883
Benjamin Petersone41251e2008-04-25 01:59:09 +00001884 Closes the socket.
Georg Brandl116aa622007-08-15 14:28:22 +00001885
1886
Benjamin Petersone41251e2008-04-25 01:59:09 +00001887 .. method:: emit()
Georg Brandl116aa622007-08-15 14:28:22 +00001888
Benjamin Petersone41251e2008-04-25 01:59:09 +00001889 Pickles the record's attribute dictionary and writes it to the socket in
1890 binary format. If there is an error with the socket, silently drops the
1891 packet. If the connection was previously lost, re-establishes the
1892 connection. To unpickle the record at the receiving end into a
1893 :class:`LogRecord`, use the :func:`makeLogRecord` function.
Georg Brandl116aa622007-08-15 14:28:22 +00001894
1895
Benjamin Petersone41251e2008-04-25 01:59:09 +00001896 .. method:: handleError()
Georg Brandl116aa622007-08-15 14:28:22 +00001897
Benjamin Petersone41251e2008-04-25 01:59:09 +00001898 Handles an error which has occurred during :meth:`emit`. The most likely
1899 cause is a lost connection. Closes the socket so that we can retry on the
1900 next event.
Georg Brandl116aa622007-08-15 14:28:22 +00001901
1902
Benjamin Petersone41251e2008-04-25 01:59:09 +00001903 .. method:: makeSocket()
Georg Brandl116aa622007-08-15 14:28:22 +00001904
Benjamin Petersone41251e2008-04-25 01:59:09 +00001905 This is a factory method which allows subclasses to define the precise
1906 type of socket they want. The default implementation creates a TCP socket
1907 (:const:`socket.SOCK_STREAM`).
Georg Brandl116aa622007-08-15 14:28:22 +00001908
1909
Benjamin Petersone41251e2008-04-25 01:59:09 +00001910 .. method:: makePickle(record)
Georg Brandl116aa622007-08-15 14:28:22 +00001911
Benjamin Petersone41251e2008-04-25 01:59:09 +00001912 Pickles the record's attribute dictionary in binary format with a length
1913 prefix, and returns it ready for transmission across the socket.
Georg Brandl116aa622007-08-15 14:28:22 +00001914
1915
Benjamin Petersone41251e2008-04-25 01:59:09 +00001916 .. method:: send(packet)
Georg Brandl116aa622007-08-15 14:28:22 +00001917
Benjamin Petersone41251e2008-04-25 01:59:09 +00001918 Send a pickled string *packet* to the socket. This function allows for
1919 partial sends which can happen when the network is busy.
Georg Brandl116aa622007-08-15 14:28:22 +00001920
1921
1922DatagramHandler
1923^^^^^^^^^^^^^^^
1924
1925The :class:`DatagramHandler` class, located in the :mod:`logging.handlers`
1926module, inherits from :class:`SocketHandler` to support sending logging messages
1927over UDP sockets.
1928
1929
1930.. class:: DatagramHandler(host, port)
1931
1932 Returns a new instance of the :class:`DatagramHandler` class intended to
1933 communicate with a remote machine whose address is given by *host* and *port*.
1934
1935
Benjamin Petersone41251e2008-04-25 01:59:09 +00001936 .. method:: emit()
Georg Brandl116aa622007-08-15 14:28:22 +00001937
Benjamin Petersone41251e2008-04-25 01:59:09 +00001938 Pickles the record's attribute dictionary and writes it to the socket in
1939 binary format. If there is an error with the socket, silently drops the
1940 packet. To unpickle the record at the receiving end into a
1941 :class:`LogRecord`, use the :func:`makeLogRecord` function.
Georg Brandl116aa622007-08-15 14:28:22 +00001942
1943
Benjamin Petersone41251e2008-04-25 01:59:09 +00001944 .. method:: makeSocket()
Georg Brandl116aa622007-08-15 14:28:22 +00001945
Benjamin Petersone41251e2008-04-25 01:59:09 +00001946 The factory method of :class:`SocketHandler` is here overridden to create
1947 a UDP socket (:const:`socket.SOCK_DGRAM`).
Georg Brandl116aa622007-08-15 14:28:22 +00001948
1949
Benjamin Petersone41251e2008-04-25 01:59:09 +00001950 .. method:: send(s)
Georg Brandl116aa622007-08-15 14:28:22 +00001951
Benjamin Petersone41251e2008-04-25 01:59:09 +00001952 Send a pickled string to a socket.
Georg Brandl116aa622007-08-15 14:28:22 +00001953
1954
1955SysLogHandler
1956^^^^^^^^^^^^^
1957
1958The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module,
1959supports sending logging messages to a remote or local Unix syslog.
1960
1961
Vinay Sajipcbabd7e2009-10-10 20:32:36 +00001962.. class:: SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)
Georg Brandl116aa622007-08-15 14:28:22 +00001963
1964 Returns a new instance of the :class:`SysLogHandler` class intended to
1965 communicate with a remote Unix machine whose address is given by *address* in
1966 the form of a ``(host, port)`` tuple. If *address* is not specified,
Vinay Sajipcbabd7e2009-10-10 20:32:36 +00001967 ``('localhost', 514)`` is used. The address is used to open a socket. An
Georg Brandl116aa622007-08-15 14:28:22 +00001968 alternative to providing a ``(host, port)`` tuple is providing an address as a
1969 string, for example "/dev/log". In this case, a Unix domain socket is used to
1970 send the message to the syslog. If *facility* is not specified,
Vinay Sajipcbabd7e2009-10-10 20:32:36 +00001971 :const:`LOG_USER` is used. The type of socket opened depends on the
1972 *socktype* argument, which defaults to :const:`socket.SOCK_DGRAM` and thus
1973 opens a UDP socket. To open a TCP socket (for use with the newer syslog
1974 daemons such as rsyslog), specify a value of :const:`socket.SOCK_STREAM`.
1975
1976 .. versionchanged:: 3.2
1977 *socktype* was added.
Georg Brandl116aa622007-08-15 14:28:22 +00001978
1979
Benjamin Petersone41251e2008-04-25 01:59:09 +00001980 .. method:: close()
Georg Brandl116aa622007-08-15 14:28:22 +00001981
Benjamin Petersone41251e2008-04-25 01:59:09 +00001982 Closes the socket to the remote host.
Georg Brandl116aa622007-08-15 14:28:22 +00001983
1984
Benjamin Petersone41251e2008-04-25 01:59:09 +00001985 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00001986
Benjamin Petersone41251e2008-04-25 01:59:09 +00001987 The record is formatted, and then sent to the syslog server. If exception
1988 information is present, it is *not* sent to the server.
Georg Brandl116aa622007-08-15 14:28:22 +00001989
1990
Benjamin Petersone41251e2008-04-25 01:59:09 +00001991 .. method:: encodePriority(facility, priority)
Georg Brandl116aa622007-08-15 14:28:22 +00001992
Benjamin Petersone41251e2008-04-25 01:59:09 +00001993 Encodes the facility and priority into an integer. You can pass in strings
1994 or integers - if strings are passed, internal mapping dictionaries are
1995 used to convert them to integers.
Georg Brandl116aa622007-08-15 14:28:22 +00001996
1997
1998NTEventLogHandler
1999^^^^^^^^^^^^^^^^^
2000
2001The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers`
2002module, supports sending logging messages to a local Windows NT, Windows 2000 or
2003Windows XP event log. Before you can use it, you need Mark Hammond's Win32
2004extensions for Python installed.
2005
2006
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002007.. class:: NTEventLogHandler(appname, dllname=None, logtype='Application')
Georg Brandl116aa622007-08-15 14:28:22 +00002008
2009 Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is
2010 used to define the application name as it appears in the event log. An
2011 appropriate registry entry is created using this name. The *dllname* should give
2012 the fully qualified pathname of a .dll or .exe which contains message
2013 definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used
2014 - this is installed with the Win32 extensions and contains some basic
2015 placeholder message definitions. Note that use of these placeholders will make
2016 your event logs big, as the entire message source is held in the log. If you
2017 want slimmer logs, you have to pass in the name of your own .dll or .exe which
2018 contains the message definitions you want to use in the event log). The
2019 *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and
2020 defaults to ``'Application'``.
2021
2022
Benjamin Petersone41251e2008-04-25 01:59:09 +00002023 .. method:: close()
Georg Brandl116aa622007-08-15 14:28:22 +00002024
Benjamin Petersone41251e2008-04-25 01:59:09 +00002025 At this point, you can remove the application name from the registry as a
2026 source of event log entries. However, if you do this, you will not be able
2027 to see the events as you intended in the Event Log Viewer - it needs to be
2028 able to access the registry to get the .dll name. The current version does
Benjamin Peterson3e4f0552008-09-02 00:31:15 +00002029 not do this.
Georg Brandl116aa622007-08-15 14:28:22 +00002030
2031
Benjamin Petersone41251e2008-04-25 01:59:09 +00002032 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002033
Benjamin Petersone41251e2008-04-25 01:59:09 +00002034 Determines the message ID, event category and event type, and then logs
2035 the message in the NT event log.
Georg Brandl116aa622007-08-15 14:28:22 +00002036
2037
Benjamin Petersone41251e2008-04-25 01:59:09 +00002038 .. method:: getEventCategory(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002039
Benjamin Petersone41251e2008-04-25 01:59:09 +00002040 Returns the event category for the record. Override this if you want to
2041 specify your own categories. This version returns 0.
Georg Brandl116aa622007-08-15 14:28:22 +00002042
2043
Benjamin Petersone41251e2008-04-25 01:59:09 +00002044 .. method:: getEventType(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002045
Benjamin Petersone41251e2008-04-25 01:59:09 +00002046 Returns the event type for the record. Override this if you want to
2047 specify your own types. This version does a mapping using the handler's
2048 typemap attribute, which is set up in :meth:`__init__` to a dictionary
2049 which contains mappings for :const:`DEBUG`, :const:`INFO`,
2050 :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
2051 your own levels, you will either need to override this method or place a
2052 suitable dictionary in the handler's *typemap* attribute.
Georg Brandl116aa622007-08-15 14:28:22 +00002053
2054
Benjamin Petersone41251e2008-04-25 01:59:09 +00002055 .. method:: getMessageID(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002056
Benjamin Petersone41251e2008-04-25 01:59:09 +00002057 Returns the message ID for the record. If you are using your own messages,
2058 you could do this by having the *msg* passed to the logger being an ID
2059 rather than a format string. Then, in here, you could use a dictionary
2060 lookup to get the message ID. This version returns 1, which is the base
2061 message ID in :file:`win32service.pyd`.
Georg Brandl116aa622007-08-15 14:28:22 +00002062
2063
2064SMTPHandler
2065^^^^^^^^^^^
2066
2067The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module,
2068supports sending logging messages to an email address via SMTP.
2069
2070
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002071.. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None)
Georg Brandl116aa622007-08-15 14:28:22 +00002072
2073 Returns a new instance of the :class:`SMTPHandler` class. The instance is
2074 initialized with the from and to addresses and subject line of the email. The
2075 *toaddrs* should be a list of strings. To specify a non-standard SMTP port, use
2076 the (host, port) tuple format for the *mailhost* argument. If you use a string,
2077 the standard SMTP port is used. If your SMTP server requires authentication, you
2078 can specify a (username, password) tuple for the *credentials* argument.
2079
Georg Brandl116aa622007-08-15 14:28:22 +00002080
Benjamin Petersone41251e2008-04-25 01:59:09 +00002081 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002082
Benjamin Petersone41251e2008-04-25 01:59:09 +00002083 Formats the record and sends it to the specified addressees.
Georg Brandl116aa622007-08-15 14:28:22 +00002084
2085
Benjamin Petersone41251e2008-04-25 01:59:09 +00002086 .. method:: getSubject(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002087
Benjamin Petersone41251e2008-04-25 01:59:09 +00002088 If you want to specify a subject line which is record-dependent, override
2089 this method.
Georg Brandl116aa622007-08-15 14:28:22 +00002090
2091
2092MemoryHandler
2093^^^^^^^^^^^^^
2094
2095The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module,
2096supports buffering of logging records in memory, periodically flushing them to a
2097:dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
2098event of a certain severity or greater is seen.
2099
2100:class:`MemoryHandler` is a subclass of the more general
2101:class:`BufferingHandler`, which is an abstract class. This buffers logging
2102records in memory. Whenever each record is added to the buffer, a check is made
2103by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it
2104should, then :meth:`flush` is expected to do the needful.
2105
2106
2107.. class:: BufferingHandler(capacity)
2108
2109 Initializes the handler with a buffer of the specified capacity.
2110
2111
Benjamin Petersone41251e2008-04-25 01:59:09 +00002112 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002113
Benjamin Petersone41251e2008-04-25 01:59:09 +00002114 Appends the record to the buffer. If :meth:`shouldFlush` returns true,
2115 calls :meth:`flush` to process the buffer.
Georg Brandl116aa622007-08-15 14:28:22 +00002116
2117
Benjamin Petersone41251e2008-04-25 01:59:09 +00002118 .. method:: flush()
Georg Brandl116aa622007-08-15 14:28:22 +00002119
Benjamin Petersone41251e2008-04-25 01:59:09 +00002120 You can override this to implement custom flushing behavior. This version
2121 just zaps the buffer to empty.
Georg Brandl116aa622007-08-15 14:28:22 +00002122
2123
Benjamin Petersone41251e2008-04-25 01:59:09 +00002124 .. method:: shouldFlush(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002125
Benjamin Petersone41251e2008-04-25 01:59:09 +00002126 Returns true if the buffer is up to capacity. This method can be
2127 overridden to implement custom flushing strategies.
Georg Brandl116aa622007-08-15 14:28:22 +00002128
2129
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002130.. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None)
Georg Brandl116aa622007-08-15 14:28:22 +00002131
2132 Returns a new instance of the :class:`MemoryHandler` class. The instance is
2133 initialized with a buffer size of *capacity*. If *flushLevel* is not specified,
2134 :const:`ERROR` is used. If no *target* is specified, the target will need to be
2135 set using :meth:`setTarget` before this handler does anything useful.
2136
2137
Benjamin Petersone41251e2008-04-25 01:59:09 +00002138 .. method:: close()
Georg Brandl116aa622007-08-15 14:28:22 +00002139
Benjamin Petersone41251e2008-04-25 01:59:09 +00002140 Calls :meth:`flush`, sets the target to :const:`None` and clears the
2141 buffer.
Georg Brandl116aa622007-08-15 14:28:22 +00002142
2143
Benjamin Petersone41251e2008-04-25 01:59:09 +00002144 .. method:: flush()
Georg Brandl116aa622007-08-15 14:28:22 +00002145
Benjamin Petersone41251e2008-04-25 01:59:09 +00002146 For a :class:`MemoryHandler`, flushing means just sending the buffered
2147 records to the target, if there is one. Override if you want different
2148 behavior.
Georg Brandl116aa622007-08-15 14:28:22 +00002149
2150
Benjamin Petersone41251e2008-04-25 01:59:09 +00002151 .. method:: setTarget(target)
Georg Brandl116aa622007-08-15 14:28:22 +00002152
Benjamin Petersone41251e2008-04-25 01:59:09 +00002153 Sets the target handler for this handler.
Georg Brandl116aa622007-08-15 14:28:22 +00002154
2155
Benjamin Petersone41251e2008-04-25 01:59:09 +00002156 .. method:: shouldFlush(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002157
Benjamin Petersone41251e2008-04-25 01:59:09 +00002158 Checks for buffer full or a record at the *flushLevel* or higher.
Georg Brandl116aa622007-08-15 14:28:22 +00002159
2160
2161HTTPHandler
2162^^^^^^^^^^^
2163
2164The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module,
2165supports sending logging messages to a Web server, using either ``GET`` or
2166``POST`` semantics.
2167
2168
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002169.. class:: HTTPHandler(host, url, method='GET')
Georg Brandl116aa622007-08-15 14:28:22 +00002170
2171 Returns a new instance of the :class:`HTTPHandler` class. The instance is
2172 initialized with a host address, url and HTTP method. The *host* can be of the
2173 form ``host:port``, should you need to use a specific port number. If no
2174 *method* is specified, ``GET`` is used.
2175
2176
Benjamin Petersone41251e2008-04-25 01:59:09 +00002177 .. method:: emit(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002178
Benjamin Petersone41251e2008-04-25 01:59:09 +00002179 Sends the record to the Web server as an URL-encoded dictionary.
Georg Brandl116aa622007-08-15 14:28:22 +00002180
2181
Christian Heimes8b0facf2007-12-04 19:30:01 +00002182.. _formatter-objects:
2183
Georg Brandl116aa622007-08-15 14:28:22 +00002184Formatter Objects
2185-----------------
2186
Benjamin Peterson75edad02009-01-01 15:05:06 +00002187.. currentmodule:: logging
2188
Georg Brandl116aa622007-08-15 14:28:22 +00002189:class:`Formatter`\ s have the following attributes and methods. They are
2190responsible for converting a :class:`LogRecord` to (usually) a string which can
2191be interpreted by either a human or an external system. The base
2192:class:`Formatter` allows a formatting string to be specified. If none is
2193supplied, the default value of ``'%(message)s'`` is used.
2194
2195A Formatter can be initialized with a format string which makes use of knowledge
2196of the :class:`LogRecord` attributes - such as the default value mentioned above
2197making use of the fact that the user's message and arguments are pre-formatted
2198into a :class:`LogRecord`'s *message* attribute. This format string contains
Ezio Melotti0639d5a2009-12-19 23:26:38 +00002199standard Python %-style mapping keys. See section :ref:`old-string-formatting`
Georg Brandl116aa622007-08-15 14:28:22 +00002200for more information on string formatting.
2201
2202Currently, the useful mapping keys in a :class:`LogRecord` are:
2203
2204+-------------------------+-----------------------------------------------+
2205| Format | Description |
2206+=========================+===============================================+
2207| ``%(name)s`` | Name of the logger (logging channel). |
2208+-------------------------+-----------------------------------------------+
2209| ``%(levelno)s`` | Numeric logging level for the message |
2210| | (:const:`DEBUG`, :const:`INFO`, |
2211| | :const:`WARNING`, :const:`ERROR`, |
2212| | :const:`CRITICAL`). |
2213+-------------------------+-----------------------------------------------+
2214| ``%(levelname)s`` | Text logging level for the message |
2215| | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
2216| | ``'ERROR'``, ``'CRITICAL'``). |
2217+-------------------------+-----------------------------------------------+
2218| ``%(pathname)s`` | Full pathname of the source file where the |
2219| | logging call was issued (if available). |
2220+-------------------------+-----------------------------------------------+
2221| ``%(filename)s`` | Filename portion of pathname. |
2222+-------------------------+-----------------------------------------------+
2223| ``%(module)s`` | Module (name portion of filename). |
2224+-------------------------+-----------------------------------------------+
2225| ``%(funcName)s`` | Name of function containing the logging call. |
2226+-------------------------+-----------------------------------------------+
2227| ``%(lineno)d`` | Source line number where the logging call was |
2228| | issued (if available). |
2229+-------------------------+-----------------------------------------------+
2230| ``%(created)f`` | Time when the :class:`LogRecord` was created |
2231| | (as returned by :func:`time.time`). |
2232+-------------------------+-----------------------------------------------+
2233| ``%(relativeCreated)d`` | Time in milliseconds when the LogRecord was |
2234| | created, relative to the time the logging |
2235| | module was loaded. |
2236+-------------------------+-----------------------------------------------+
2237| ``%(asctime)s`` | Human-readable time when the |
2238| | :class:`LogRecord` was created. By default |
2239| | this is of the form "2003-07-08 16:49:45,896" |
2240| | (the numbers after the comma are millisecond |
2241| | portion of the time). |
2242+-------------------------+-----------------------------------------------+
2243| ``%(msecs)d`` | Millisecond portion of the time when the |
2244| | :class:`LogRecord` was created. |
2245+-------------------------+-----------------------------------------------+
2246| ``%(thread)d`` | Thread ID (if available). |
2247+-------------------------+-----------------------------------------------+
2248| ``%(threadName)s`` | Thread name (if available). |
2249+-------------------------+-----------------------------------------------+
2250| ``%(process)d`` | Process ID (if available). |
2251+-------------------------+-----------------------------------------------+
2252| ``%(message)s`` | The logged message, computed as ``msg % |
2253| | args``. |
2254+-------------------------+-----------------------------------------------+
2255
Georg Brandl116aa622007-08-15 14:28:22 +00002256
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002257.. class:: Formatter(fmt=None, datefmt=None)
Georg Brandl116aa622007-08-15 14:28:22 +00002258
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002259 Returns a new instance of the :class:`Formatter` class. The instance is
2260 initialized with a format string for the message as a whole, as well as a
2261 format string for the date/time portion of a message. If no *fmt* is
2262 specified, ``'%(message)s'`` is used. If no *datefmt* is specified, the
2263 ISO8601 date format is used.
Georg Brandl116aa622007-08-15 14:28:22 +00002264
2265
Benjamin Petersone41251e2008-04-25 01:59:09 +00002266 .. method:: format(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002267
Benjamin Petersone41251e2008-04-25 01:59:09 +00002268 The record's attribute dictionary is used as the operand to a string
2269 formatting operation. Returns the resulting string. Before formatting the
2270 dictionary, a couple of preparatory steps are carried out. The *message*
2271 attribute of the record is computed using *msg* % *args*. If the
2272 formatting string contains ``'(asctime)'``, :meth:`formatTime` is called
2273 to format the event time. If there is exception information, it is
2274 formatted using :meth:`formatException` and appended to the message. Note
2275 that the formatted exception information is cached in attribute
2276 *exc_text*. This is useful because the exception information can be
2277 pickled and sent across the wire, but you should be careful if you have
2278 more than one :class:`Formatter` subclass which customizes the formatting
2279 of exception information. In this case, you will have to clear the cached
2280 value after a formatter has done its formatting, so that the next
2281 formatter to handle the event doesn't use the cached value but
2282 recalculates it afresh.
Georg Brandl116aa622007-08-15 14:28:22 +00002283
2284
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002285 .. method:: formatTime(record, datefmt=None)
Georg Brandl116aa622007-08-15 14:28:22 +00002286
Benjamin Petersone41251e2008-04-25 01:59:09 +00002287 This method should be called from :meth:`format` by a formatter which
2288 wants to make use of a formatted time. This method can be overridden in
2289 formatters to provide for any specific requirement, but the basic behavior
2290 is as follows: if *datefmt* (a string) is specified, it is used with
2291 :func:`time.strftime` to format the creation time of the
2292 record. Otherwise, the ISO8601 format is used. The resulting string is
2293 returned.
Georg Brandl116aa622007-08-15 14:28:22 +00002294
2295
Benjamin Petersone41251e2008-04-25 01:59:09 +00002296 .. method:: formatException(exc_info)
Georg Brandl116aa622007-08-15 14:28:22 +00002297
Benjamin Petersone41251e2008-04-25 01:59:09 +00002298 Formats the specified exception information (a standard exception tuple as
2299 returned by :func:`sys.exc_info`) as a string. This default implementation
2300 just uses :func:`traceback.print_exception`. The resulting string is
2301 returned.
Georg Brandl116aa622007-08-15 14:28:22 +00002302
2303
2304Filter Objects
2305--------------
2306
2307:class:`Filter`\ s can be used by :class:`Handler`\ s and :class:`Logger`\ s for
2308more sophisticated filtering than is provided by levels. The base filter class
2309only allows events which are below a certain point in the logger hierarchy. For
2310example, a filter initialized with "A.B" will allow events logged by loggers
2311"A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB", "B.A.B" etc. If
2312initialized with the empty string, all events are passed.
2313
2314
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002315.. class:: Filter(name='')
Georg Brandl116aa622007-08-15 14:28:22 +00002316
2317 Returns an instance of the :class:`Filter` class. If *name* is specified, it
2318 names a logger which, together with its children, will have its events allowed
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002319 through the filter. If *name* is the empty string, allows every event.
Georg Brandl116aa622007-08-15 14:28:22 +00002320
2321
Benjamin Petersone41251e2008-04-25 01:59:09 +00002322 .. method:: filter(record)
Georg Brandl116aa622007-08-15 14:28:22 +00002323
Benjamin Petersone41251e2008-04-25 01:59:09 +00002324 Is the specified record to be logged? Returns zero for no, nonzero for
2325 yes. If deemed appropriate, the record may be modified in-place by this
2326 method.
Georg Brandl116aa622007-08-15 14:28:22 +00002327
2328
2329LogRecord Objects
2330-----------------
2331
2332:class:`LogRecord` instances are created every time something is logged. They
2333contain all the information pertinent to the event being logged. The main
2334information passed in is in msg and args, which are combined using msg % args to
2335create the message field of the record. The record also includes information
2336such as when the record was created, the source line where the logging call was
2337made, and any exception information to be logged.
2338
2339
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002340.. class:: LogRecord(name, lvl, pathname, lineno, msg, args, exc_info, func=None)
Georg Brandl116aa622007-08-15 14:28:22 +00002341
2342 Returns an instance of :class:`LogRecord` initialized with interesting
2343 information. The *name* is the logger name; *lvl* is the numeric level;
2344 *pathname* is the absolute pathname of the source file in which the logging
2345 call was made; *lineno* is the line number in that file where the logging
2346 call is found; *msg* is the user-supplied message (a format string); *args*
2347 is the tuple which, together with *msg*, makes up the user message; and
2348 *exc_info* is the exception tuple obtained by calling :func:`sys.exc_info`
2349 (or :const:`None`, if no exception information is available). The *func* is
2350 the name of the function from which the logging call was made. If not
2351 specified, it defaults to ``None``.
2352
Georg Brandl116aa622007-08-15 14:28:22 +00002353
Benjamin Petersone41251e2008-04-25 01:59:09 +00002354 .. method:: getMessage()
Georg Brandl116aa622007-08-15 14:28:22 +00002355
Benjamin Petersone41251e2008-04-25 01:59:09 +00002356 Returns the message for this :class:`LogRecord` instance after merging any
2357 user-supplied arguments with the message.
2358
Georg Brandl116aa622007-08-15 14:28:22 +00002359
Christian Heimes04c420f2008-01-18 18:40:46 +00002360LoggerAdapter Objects
2361---------------------
2362
Christian Heimes04c420f2008-01-18 18:40:46 +00002363:class:`LoggerAdapter` instances are used to conveniently pass contextual
Georg Brandl86def6c2008-01-21 20:36:10 +00002364information into logging calls. For a usage example , see the section on
2365`adding contextual information to your logging output`__.
2366
2367__ context-info_
Christian Heimes04c420f2008-01-18 18:40:46 +00002368
2369.. class:: LoggerAdapter(logger, extra)
2370
2371 Returns an instance of :class:`LoggerAdapter` initialized with an
2372 underlying :class:`Logger` instance and a dict-like object.
2373
Benjamin Petersone41251e2008-04-25 01:59:09 +00002374 .. method:: process(msg, kwargs)
Christian Heimes04c420f2008-01-18 18:40:46 +00002375
Benjamin Petersone41251e2008-04-25 01:59:09 +00002376 Modifies the message and/or keyword arguments passed to a logging call in
2377 order to insert contextual information. This implementation takes the object
2378 passed as *extra* to the constructor and adds it to *kwargs* using key
2379 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
2380 (possibly modified) versions of the arguments passed in.
Christian Heimes04c420f2008-01-18 18:40:46 +00002381
2382In addition to the above, :class:`LoggerAdapter` supports all the logging
2383methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,
2384:meth:`error`, :meth:`exception`, :meth:`critical` and :meth:`log`. These
2385methods have the same signatures as their counterparts in :class:`Logger`, so
2386you can use the two types of instances interchangeably.
2387
Georg Brandl116aa622007-08-15 14:28:22 +00002388
2389Thread Safety
2390-------------
2391
2392The logging module is intended to be thread-safe without any special work
2393needing to be done by its clients. It achieves this though using threading
2394locks; there is one lock to serialize access to the module's shared data, and
2395each handler also creates a lock to serialize access to its underlying I/O.
2396
Benjamin Petersond23f8222009-04-05 19:13:16 +00002397If you are implementing asynchronous signal handlers using the :mod:`signal`
2398module, you may not be able to use logging from within such handlers. This is
2399because lock implementations in the :mod:`threading` module are not always
2400re-entrant, and so cannot be invoked from such signal handlers.
Georg Brandl116aa622007-08-15 14:28:22 +00002401
2402Configuration
2403-------------
2404
2405
2406.. _logging-config-api:
2407
2408Configuration functions
2409^^^^^^^^^^^^^^^^^^^^^^^
2410
Georg Brandl116aa622007-08-15 14:28:22 +00002411The following functions configure the logging module. They are located in the
2412:mod:`logging.config` module. Their use is optional --- you can configure the
2413logging module using these functions or by making calls to the main API (defined
2414in :mod:`logging` itself) and defining handlers which are declared either in
2415:mod:`logging` or :mod:`logging.handlers`.
2416
2417
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002418.. function:: fileConfig(fname, defaults=None, disable_existing_loggers=True)
Georg Brandl116aa622007-08-15 14:28:22 +00002419
Alexandre Vassalotti1d1eaa42008-05-14 22:59:42 +00002420 Reads the logging configuration from a :mod:`configparser`\-format file named
Benjamin Peterson960cf0f2009-01-09 04:11:44 +00002421 *fname*. This function can be called several times from an application,
Alexandre Vassalotti1d1eaa42008-05-14 22:59:42 +00002422 allowing an end user the ability to select from various pre-canned
2423 configurations (if the developer provides a mechanism to present the choices
2424 and load the chosen configuration). Defaults to be passed to the ConfigParser
2425 can be specified in the *defaults* argument.
Georg Brandl116aa622007-08-15 14:28:22 +00002426
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002427 If *disable_existing_loggers* is true, any existing loggers that are not
2428 children of named loggers will be disabled.
Georg Brandl116aa622007-08-15 14:28:22 +00002429
Georg Brandlcd7f32b2009-06-08 09:13:45 +00002430
2431.. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT)
Georg Brandl116aa622007-08-15 14:28:22 +00002432
2433 Starts up a socket server on the specified port, and listens for new
2434 configurations. If no port is specified, the module's default
2435 :const:`DEFAULT_LOGGING_CONFIG_PORT` is used. Logging configurations will be
2436 sent as a file suitable for processing by :func:`fileConfig`. Returns a
2437 :class:`Thread` instance on which you can call :meth:`start` to start the
2438 server, and which you can :meth:`join` when appropriate. To stop the server,
Christian Heimes8b0facf2007-12-04 19:30:01 +00002439 call :func:`stopListening`.
2440
2441 To send a configuration to the socket, read in the configuration file and
2442 send it to the socket as a string of bytes preceded by a four-byte length
2443 string packed in binary using ``struct.pack('>L', n)``.
Georg Brandl116aa622007-08-15 14:28:22 +00002444
2445
2446.. function:: stopListening()
2447
Christian Heimes8b0facf2007-12-04 19:30:01 +00002448 Stops the listening server which was created with a call to :func:`listen`.
2449 This is typically called before calling :meth:`join` on the return value from
Georg Brandl116aa622007-08-15 14:28:22 +00002450 :func:`listen`.
2451
2452
2453.. _logging-config-fileformat:
2454
2455Configuration file format
2456^^^^^^^^^^^^^^^^^^^^^^^^^
2457
Benjamin Peterson960cf0f2009-01-09 04:11:44 +00002458The configuration file format understood by :func:`fileConfig` is based on
2459:mod:`configparser` functionality. The file must contain sections called
2460``[loggers]``, ``[handlers]`` and ``[formatters]`` which identify by name the
2461entities of each type which are defined in the file. For each such entity, there
2462is a separate section which identifies how that entity is configured. Thus, for
2463a logger named ``log01`` in the ``[loggers]`` section, the relevant
2464configuration details are held in a section ``[logger_log01]``. Similarly, a
2465handler called ``hand01`` in the ``[handlers]`` section will have its
2466configuration held in a section called ``[handler_hand01]``, while a formatter
2467called ``form01`` in the ``[formatters]`` section will have its configuration
2468specified in a section called ``[formatter_form01]``. The root logger
2469configuration must be specified in a section called ``[logger_root]``.
Georg Brandl116aa622007-08-15 14:28:22 +00002470
2471Examples of these sections in the file are given below. ::
2472
2473 [loggers]
2474 keys=root,log02,log03,log04,log05,log06,log07
2475
2476 [handlers]
2477 keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
2478
2479 [formatters]
2480 keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
2481
2482The root logger must specify a level and a list of handlers. An example of a
2483root logger section is given below. ::
2484
2485 [logger_root]
2486 level=NOTSET
2487 handlers=hand01
2488
2489The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or
2490``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be
2491logged. Level values are :func:`eval`\ uated in the context of the ``logging``
2492package's namespace.
2493
2494The ``handlers`` entry is a comma-separated list of handler names, which must
2495appear in the ``[handlers]`` section. These names must appear in the
2496``[handlers]`` section and have corresponding sections in the configuration
2497file.
2498
2499For loggers other than the root logger, some additional information is required.
2500This is illustrated by the following example. ::
2501
2502 [logger_parser]
2503 level=DEBUG
2504 handlers=hand01
2505 propagate=1
2506 qualname=compiler.parser
2507
2508The ``level`` and ``handlers`` entries are interpreted as for the root logger,
2509except that if a non-root logger's level is specified as ``NOTSET``, the system
2510consults loggers higher up the hierarchy to determine the effective level of the
2511logger. The ``propagate`` entry is set to 1 to indicate that messages must
2512propagate to handlers higher up the logger hierarchy from this logger, or 0 to
2513indicate that messages are **not** propagated to handlers up the hierarchy. The
2514``qualname`` entry is the hierarchical channel name of the logger, that is to
2515say the name used by the application to get the logger.
2516
2517Sections which specify handler configuration are exemplified by the following.
2518::
2519
2520 [handler_hand01]
2521 class=StreamHandler
2522 level=NOTSET
2523 formatter=form01
2524 args=(sys.stdout,)
2525
2526The ``class`` entry indicates the handler's class (as determined by :func:`eval`
2527in the ``logging`` package's namespace). The ``level`` is interpreted as for
2528loggers, and ``NOTSET`` is taken to mean "log everything".
2529
2530The ``formatter`` entry indicates the key name of the formatter for this
2531handler. If blank, a default formatter (``logging._defaultFormatter``) is used.
2532If a name is specified, it must appear in the ``[formatters]`` section and have
2533a corresponding section in the configuration file.
2534
2535The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
2536package's namespace, is the list of arguments to the constructor for the handler
2537class. Refer to the constructors for the relevant handlers, or to the examples
2538below, to see how typical entries are constructed. ::
2539
2540 [handler_hand02]
2541 class=FileHandler
2542 level=DEBUG
2543 formatter=form02
2544 args=('python.log', 'w')
2545
2546 [handler_hand03]
2547 class=handlers.SocketHandler
2548 level=INFO
2549 formatter=form03
2550 args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
2551
2552 [handler_hand04]
2553 class=handlers.DatagramHandler
2554 level=WARN
2555 formatter=form04
2556 args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
2557
2558 [handler_hand05]
2559 class=handlers.SysLogHandler
2560 level=ERROR
2561 formatter=form05
2562 args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
2563
2564 [handler_hand06]
2565 class=handlers.NTEventLogHandler
2566 level=CRITICAL
2567 formatter=form06
2568 args=('Python Application', '', 'Application')
2569
2570 [handler_hand07]
2571 class=handlers.SMTPHandler
2572 level=WARN
2573 formatter=form07
2574 args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
2575
2576 [handler_hand08]
2577 class=handlers.MemoryHandler
2578 level=NOTSET
2579 formatter=form08
2580 target=
2581 args=(10, ERROR)
2582
2583 [handler_hand09]
2584 class=handlers.HTTPHandler
2585 level=NOTSET
2586 formatter=form09
2587 args=('localhost:9022', '/log', 'GET')
2588
2589Sections which specify formatter configuration are typified by the following. ::
2590
2591 [formatter_form01]
2592 format=F1 %(asctime)s %(levelname)s %(message)s
2593 datefmt=
2594 class=logging.Formatter
2595
2596The ``format`` entry is the overall format string, and the ``datefmt`` entry is
Christian Heimes5b5e81c2007-12-31 16:14:33 +00002597the :func:`strftime`\ -compatible date/time format string. If empty, the
2598package substitutes ISO8601 format date/times, which is almost equivalent to
2599specifying the date format string ``"%Y-%m-%d %H:%M:%S"``. The ISO8601 format
2600also specifies milliseconds, which are appended to the result of using the above
2601format string, with a comma separator. An example time in ISO8601 format is
2602``2003-01-23 00:29:50,411``.
Georg Brandl116aa622007-08-15 14:28:22 +00002603
2604The ``class`` entry is optional. It indicates the name of the formatter's class
2605(as a dotted module and class name.) This option is useful for instantiating a
2606:class:`Formatter` subclass. Subclasses of :class:`Formatter` can present
2607exception tracebacks in an expanded or condensed format.
2608
Christian Heimes8b0facf2007-12-04 19:30:01 +00002609
2610Configuration server example
2611^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2612
2613Here is an example of a module using the logging configuration server::
2614
2615 import logging
2616 import logging.config
2617 import time
2618 import os
2619
2620 # read initial config file
2621 logging.config.fileConfig("logging.conf")
2622
2623 # create and start listener on port 9999
2624 t = logging.config.listen(9999)
2625 t.start()
2626
2627 logger = logging.getLogger("simpleExample")
2628
2629 try:
2630 # loop through logging calls to see the difference
2631 # new configurations make, until Ctrl+C is pressed
2632 while True:
2633 logger.debug("debug message")
2634 logger.info("info message")
2635 logger.warn("warn message")
2636 logger.error("error message")
2637 logger.critical("critical message")
2638 time.sleep(5)
2639 except KeyboardInterrupt:
2640 # cleanup
2641 logging.config.stopListening()
2642 t.join()
2643
2644And here is a script that takes a filename and sends that file to the server,
2645properly preceded with the binary-encoded length, as the new logging
2646configuration::
2647
2648 #!/usr/bin/env python
2649 import socket, sys, struct
2650
2651 data_to_send = open(sys.argv[1], "r").read()
2652
2653 HOST = 'localhost'
2654 PORT = 9999
2655 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
Georg Brandlf6945182008-02-01 11:56:49 +00002656 print("connecting...")
Christian Heimes8b0facf2007-12-04 19:30:01 +00002657 s.connect((HOST, PORT))
Georg Brandlf6945182008-02-01 11:56:49 +00002658 print("sending config...")
Christian Heimes8b0facf2007-12-04 19:30:01 +00002659 s.send(struct.pack(">L", len(data_to_send)))
2660 s.send(data_to_send)
2661 s.close()
Georg Brandlf6945182008-02-01 11:56:49 +00002662 print("complete")
Christian Heimes8b0facf2007-12-04 19:30:01 +00002663
2664
2665More examples
2666-------------
2667
2668Multiple handlers and formatters
2669^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2670
2671Loggers are plain Python objects. The :func:`addHandler` method has no minimum
2672or maximum quota for the number of handlers you may add. Sometimes it will be
2673beneficial for an application to log all messages of all severities to a text
2674file while simultaneously logging errors or above to the console. To set this
2675up, simply configure the appropriate handlers. The logging calls in the
2676application code will remain unchanged. Here is a slight modification to the
2677previous simple module-based configuration example::
2678
2679 import logging
2680
2681 logger = logging.getLogger("simple_example")
2682 logger.setLevel(logging.DEBUG)
2683 # create file handler which logs even debug messages
2684 fh = logging.FileHandler("spam.log")
2685 fh.setLevel(logging.DEBUG)
2686 # create console handler with a higher log level
2687 ch = logging.StreamHandler()
2688 ch.setLevel(logging.ERROR)
2689 # create formatter and add it to the handlers
2690 formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
2691 ch.setFormatter(formatter)
2692 fh.setFormatter(formatter)
2693 # add the handlers to logger
2694 logger.addHandler(ch)
2695 logger.addHandler(fh)
2696
2697 # "application" code
2698 logger.debug("debug message")
2699 logger.info("info message")
2700 logger.warn("warn message")
2701 logger.error("error message")
2702 logger.critical("critical message")
2703
2704Notice that the "application" code does not care about multiple handlers. All
2705that changed was the addition and configuration of a new handler named *fh*.
2706
2707The ability to create new handlers with higher- or lower-severity filters can be
2708very helpful when writing and testing an application. Instead of using many
2709``print`` statements for debugging, use ``logger.debug``: Unlike the print
2710statements, which you will have to delete or comment out later, the logger.debug
2711statements can remain intact in the source code and remain dormant until you
2712need them again. At that time, the only change that needs to happen is to
2713modify the severity level of the logger and/or handler to debug.
2714
2715
2716Using logging in multiple modules
2717^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2718
2719It was mentioned above that multiple calls to
2720``logging.getLogger('someLogger')`` return a reference to the same logger
2721object. This is true not only within the same module, but also across modules
2722as long as it is in the same Python interpreter process. It is true for
2723references to the same object; additionally, application code can define and
2724configure a parent logger in one module and create (but not configure) a child
2725logger in a separate module, and all logger calls to the child will pass up to
2726the parent. Here is a main module::
2727
2728 import logging
2729 import auxiliary_module
2730
2731 # create logger with "spam_application"
2732 logger = logging.getLogger("spam_application")
2733 logger.setLevel(logging.DEBUG)
2734 # create file handler which logs even debug messages
2735 fh = logging.FileHandler("spam.log")
2736 fh.setLevel(logging.DEBUG)
2737 # create console handler with a higher log level
2738 ch = logging.StreamHandler()
2739 ch.setLevel(logging.ERROR)
2740 # create formatter and add it to the handlers
2741 formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
2742 fh.setFormatter(formatter)
2743 ch.setFormatter(formatter)
2744 # add the handlers to the logger
2745 logger.addHandler(fh)
2746 logger.addHandler(ch)
2747
2748 logger.info("creating an instance of auxiliary_module.Auxiliary")
2749 a = auxiliary_module.Auxiliary()
2750 logger.info("created an instance of auxiliary_module.Auxiliary")
2751 logger.info("calling auxiliary_module.Auxiliary.do_something")
2752 a.do_something()
2753 logger.info("finished auxiliary_module.Auxiliary.do_something")
2754 logger.info("calling auxiliary_module.some_function()")
2755 auxiliary_module.some_function()
2756 logger.info("done with auxiliary_module.some_function()")
2757
2758Here is the auxiliary module::
2759
2760 import logging
2761
2762 # create logger
2763 module_logger = logging.getLogger("spam_application.auxiliary")
2764
2765 class Auxiliary:
2766 def __init__(self):
2767 self.logger = logging.getLogger("spam_application.auxiliary.Auxiliary")
2768 self.logger.info("creating an instance of Auxiliary")
2769 def do_something(self):
2770 self.logger.info("doing something")
2771 a = 1 + 1
2772 self.logger.info("done doing something")
2773
2774 def some_function():
2775 module_logger.info("received a call to \"some_function\"")
2776
2777The output looks like this::
2778
Christian Heimes043d6f62008-01-07 17:19:16 +00002779 2005-03-23 23:47:11,663 - spam_application - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002780 creating an instance of auxiliary_module.Auxiliary
Christian Heimes043d6f62008-01-07 17:19:16 +00002781 2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002782 creating an instance of Auxiliary
Christian Heimes043d6f62008-01-07 17:19:16 +00002783 2005-03-23 23:47:11,665 - spam_application - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002784 created an instance of auxiliary_module.Auxiliary
Christian Heimes043d6f62008-01-07 17:19:16 +00002785 2005-03-23 23:47:11,668 - spam_application - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002786 calling auxiliary_module.Auxiliary.do_something
Christian Heimes043d6f62008-01-07 17:19:16 +00002787 2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002788 doing something
Christian Heimes043d6f62008-01-07 17:19:16 +00002789 2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002790 done doing something
Christian Heimes043d6f62008-01-07 17:19:16 +00002791 2005-03-23 23:47:11,670 - spam_application - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002792 finished auxiliary_module.Auxiliary.do_something
Christian Heimes043d6f62008-01-07 17:19:16 +00002793 2005-03-23 23:47:11,671 - spam_application - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002794 calling auxiliary_module.some_function()
Christian Heimes043d6f62008-01-07 17:19:16 +00002795 2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002796 received a call to "some_function"
Christian Heimes043d6f62008-01-07 17:19:16 +00002797 2005-03-23 23:47:11,673 - spam_application - INFO -
Christian Heimes8b0facf2007-12-04 19:30:01 +00002798 done with auxiliary_module.some_function()
2799