Mercurial > cpython-lru_cache-weakref

annotate Doc/library/logging.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents d19d890138f1
children a07ea82a5bb0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 :mod:`logging` --- Logging facility for Python
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 ==============================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. module:: logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 :synopsis: Flexible error logging system for applications.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 .. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 .. index:: pair: Errors; logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 This module defines functions and classes which implement a flexible error
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 logging system for applications.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 Logging is performed by calling methods on instances of the :class:`Logger`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 class (hereafter called :dfn:`loggers`). Each instance has a name, and they are
43631
03056365a1b6 Add :term:s for "new-style class".
Georg Brandl <georg@python.org>
parents: 42630
diff changeset
21 conceptually arranged in a namespace hierarchy using dots (periods) as
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 separators. For example, a logger named "scan" is the parent of loggers
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 and indicate the area of an application in which a logged message originates.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 Logged messages also have levels of importance associated with them. The default
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 levels provided are :const:`DEBUG`, :const:`INFO`, :const:`WARNING`,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 :const:`ERROR` and :const:`CRITICAL`. As a convenience, you indicate the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 importance of a logged message by calling an appropriate method of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 :class:`Logger`. The methods are :meth:`debug`, :meth:`info`, :meth:`warning`,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 :meth:`error` and :meth:`critical`, which mirror the default levels. You are not
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 constrained to use these levels: you can specify your own and use a more general
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 :class:`Logger` method, :meth:`log`, which takes an explicit level argument.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
35
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
36 Logging tutorial
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
37 ----------------
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
38
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
39 The key benefit of having the logging API provided by a standard library module
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
40 is that all Python modules can participate in logging, so your application log
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
41 can include messages from third-party modules.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
42
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
43 It is, of course, possible to log messages with different verbosity levels or to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
44 different destinations. Support for writing log messages to files, HTTP
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
45 GET/POST locations, email via SMTP, generic sockets, or OS-specific logging
45429
853af5bbb497 A lot more typo fixes by Ori Avtalion.
Georg Brandl <georg@python.org>
parents: 44909
diff changeset
46 mechanisms are all supported by the standard module. You can also create your
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
47 own log destination class if you have special requirements not met by any of the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
48 built-in classes.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
49
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
50 Simple examples
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
51 ^^^^^^^^^^^^^^^
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
52
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
53 .. sectionauthor:: Doug Hellmann
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
54 .. (see <http://blog.doughellmann.com/2007/05/pymotw-logging.html>)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
55
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
56 Most applications are probably going to want to log to a file, so let's start
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
57 with that case. Using the :func:`basicConfig` function, we can set up the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
58 default handler so that debug messages are written to a file::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
59
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
60 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
61 LOG_FILENAME = '/tmp/logging_example.out'
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
62 logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG,)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
63
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
64 logging.debug('This message should go to the log file')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
65
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
66 And now if we open the file and look at what we have, we should find the log
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
67 message::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
68
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
69 DEBUG:root:This message should go to the log file
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
70
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
71 If you run the script repeatedly, the additional log messages are appended to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
72 the file. To create a new file each time, you can pass a filemode argument to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
73 :func:`basicConfig` with a value of ``'w'``. Rather than managing the file size
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
74 yourself, though, it is simpler to use a :class:`RotatingFileHandler`::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
75
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
76 import glob
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
77 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
78 import logging.handlers
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
79
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
80 LOG_FILENAME = '/tmp/logging_rotatingfile_example.out'
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
81
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
82 # Set up a specific logger with our desired output level
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
83 my_logger = logging.getLogger('MyLogger')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
84 my_logger.setLevel(logging.DEBUG)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
85
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
86 # Add the log message handler to the logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
87 handler = logging.handlers.RotatingFileHandler(
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
88 LOG_FILENAME, maxBytes=20, backupCount=5)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
89
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
90 my_logger.addHandler(handler)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
91
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
92 # Log some messages
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
93 for i in range(20):
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
94 my_logger.debug('i = %d' % i)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
95
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
96 # See what files are created
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
97 logfiles = glob.glob('%s*' % LOG_FILENAME)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
98
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
99 for filename in logfiles:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
100 print filename
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
101
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
102 The result should be 6 separate files, each with part of the log history for the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
103 application::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
104
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
105 /tmp/logging_rotatingfile_example.out
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
106 /tmp/logging_rotatingfile_example.out.1
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
107 /tmp/logging_rotatingfile_example.out.2
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
108 /tmp/logging_rotatingfile_example.out.3
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
109 /tmp/logging_rotatingfile_example.out.4
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
110 /tmp/logging_rotatingfile_example.out.5
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
111
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
112 The most current file is always :file:`/tmp/logging_rotatingfile_example.out`,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
113 and each time it reaches the size limit it is renamed with the suffix
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
114 ``.1``. Each of the existing backup files is renamed to increment the suffix
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
115 (``.1`` becomes ``.2``, etc.) and the ``.5`` file is erased.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
116
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
117 Obviously this example sets the log length much much too small as an extreme
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
118 example. You would want to set *maxBytes* to an appropriate value.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
119
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
120 Another useful feature of the logging API is the ability to produce different
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
121 messages at different log levels. This allows you to instrument your code with
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
122 debug messages, for example, but turning the log level down so that those debug
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
123 messages are not written for your production system. The default levels are
50714
bbf464210984 Corrected minor typo and added .currentmodule directives to fix missing cross-references.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50695
diff changeset
124 ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, ``DEBUG`` and ``NOTSET``.
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
125
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
126 The logger, handler, and log message call each specify a level. The log message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
127 is only emitted if the handler and logger are configured to emit messages of
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
128 that level or lower. For example, if a message is ``CRITICAL``, and the logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
129 is set to ``ERROR``, the message is emitted. If a message is a ``WARNING``, and
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
130 the logger is set to produce only ``ERROR``\s, the message is not emitted::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
131
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
132 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
133 import sys
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
134
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
135 LEVELS = {'debug': logging.DEBUG,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
136 'info': logging.INFO,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
137 'warning': logging.WARNING,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
138 'error': logging.ERROR,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
139 'critical': logging.CRITICAL}
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
140
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
141 if len(sys.argv) > 1:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
142 level_name = sys.argv[1]
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
143 level = LEVELS.get(level_name, logging.NOTSET)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
144 logging.basicConfig(level=level)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
145
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
146 logging.debug('This is a debug message')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
147 logging.info('This is an info message')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
148 logging.warning('This is a warning message')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
149 logging.error('This is an error message')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
150 logging.critical('This is a critical error message')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
152 Run the script with an argument like 'debug' or 'warning' to see which messages
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
153 show up at different levels::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
154
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
155 $ python logging_level_example.py debug
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
156 DEBUG:root:This is a debug message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
157 INFO:root:This is an info message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
158 WARNING:root:This is a warning message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
159 ERROR:root:This is an error message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
160 CRITICAL:root:This is a critical error message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
161
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
162 $ python logging_level_example.py info
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
163 INFO:root:This is an info message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
164 WARNING:root:This is a warning message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
165 ERROR:root:This is an error message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
166 CRITICAL:root:This is a critical error message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
167
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
168 You will notice that these log messages all have ``root`` embedded in them. The
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
169 logging module supports a hierarchy of loggers with different names. An easy
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
170 way to tell where a specific log message comes from is to use a separate logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
171 object for each of your modules. Each new logger "inherits" the configuration
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
172 of its parent, and log messages sent to a logger include the name of that
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
173 logger. Optionally, each logger can be configured differently, so that messages
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
174 from different modules are handled in different ways. Let's look at a simple
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
175 example of how to log from different modules so it is easy to trace the source
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
176 of the message::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
177
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
178 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
179
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
180 logging.basicConfig(level=logging.WARNING)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
181
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
182 logger1 = logging.getLogger('package1.module1')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
183 logger2 = logging.getLogger('package2.module2')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
184
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
185 logger1.warning('This message comes from one module')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
186 logger2.warning('And this message comes from another module')
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
187
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
188 And the output::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
189
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
190 $ python logging_modules_example.py
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
191 WARNING:package1.module1:This message comes from one module
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
192 WARNING:package2.module2:And this message comes from another module
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
193
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
194 There are many more options for configuring logging, including different log
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
195 message formatting options, having messages delivered to multiple destinations,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
196 and changing the configuration of a long-running application on the fly using a
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
197 socket interface. All of these options are covered in depth in the library
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
198 module documentation.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
199
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
200 Loggers
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
201 ^^^^^^^
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
202
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
203 The logging library takes a modular approach and offers the several categories
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
204 of components: loggers, handlers, filters, and formatters. Loggers expose the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
205 interface that application code directly uses. Handlers send the log records to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
206 the appropriate destination. Filters provide a finer grained facility for
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
207 determining which log records to send on to a handler. Formatters specify the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
208 layout of the resultant log record.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
209
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
210 :class:`Logger` objects have a threefold job. First, they expose several
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
211 methods to application code so that applications can log messages at runtime.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
212 Second, logger objects determine which log messages to act upon based upon
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
213 severity (the default filtering facility) or filter objects. Third, logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
214 objects pass along relevant log messages to all interested log handlers.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
215
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
216 The most widely used methods on logger objects fall into two categories:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
217 configuration and message sending.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
218
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
219 * :meth:`Logger.setLevel` specifies the lowest-severity log message a logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
220 will handle, where debug is the lowest built-in severity level and critical is
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
221 the highest built-in severity. For example, if the severity level is info,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
222 the logger will handle only info, warning, error, and critical messages and
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
223 will ignore debug messages.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
224
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
225 * :meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove filter
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
226 objects from the logger object. This tutorial does not address filters.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
227
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
228 With the logger object configured, the following methods create log messages:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
229
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
230 * :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
231 :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
232 a message and a level that corresponds to their respective method names. The
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
233 message is actually a format string, which may contain the standard string
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
234 substitution syntax of :const:`%s`, :const:`%d`, :const:`%f`, and so on. The
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
235 rest of their arguments is a list of objects that correspond with the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
236 substitution fields in the message. With regard to :const:`**kwargs`, the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
237 logging methods care only about a keyword of :const:`exc_info` and use it to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
238 determine whether to log exception information.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
239
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
240 * :meth:`Logger.exception` creates a log message similar to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
241 :meth:`Logger.error`. The difference is that :meth:`Logger.exception` dumps a
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
242 stack trace along with it. Call this method only from an exception handler.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
243
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
244 * :meth:`Logger.log` takes a log level as an explicit argument. This is a
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
245 little more verbose for logging messages than using the log level convenience
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
246 methods listed above, but this is how to log at custom log levels.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
247
45512
e57ffa2b5d07 Add minor markup for a string.
Brett Cannon <bcannon@gmail.com>
parents: 45429
diff changeset
248 :func:`getLogger` returns a reference to a logger instance with the specified
e57ffa2b5d07 Add minor markup for a string.
Brett Cannon <bcannon@gmail.com>
parents: 45429
diff changeset
249 if it it is provided, or ``root`` if not. The names are period-separated
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
250 hierarchical structures. Multiple calls to :func:`getLogger` with the same name
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
251 will return a reference to the same logger object. Loggers that are further
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
252 down in the hierarchical list are children of loggers higher up in the list.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
253 For example, given a logger with a name of ``foo``, loggers with names of
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
254 ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all children of ``foo``.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
255 Child loggers propagate messages up to their parent loggers. Because of this,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
256 it is unnecessary to define and configure all the loggers an application uses.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
257 It is sufficient to configure a top-level logger and create child loggers as
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
258 needed.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
259
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
260
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
261 Handlers
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
262 ^^^^^^^^
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
263
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
264 :class:`Handler` objects are responsible for dispatching the appropriate log
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
265 messages (based on the log messages' severity) to the handler's specified
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
266 destination. Logger objects can add zero or more handler objects to themselves
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
267 with an :func:`addHandler` method. As an example scenario, an application may
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
268 want to send all log messages to a log file, all log messages of error or higher
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
269 to stdout, and all messages of critical to an email address. This scenario
45429
853af5bbb497 A lot more typo fixes by Ori Avtalion.
Georg Brandl <georg@python.org>
parents: 44909
diff changeset
270 requires three individual handlers where each handler is responsible for sending
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
271 messages of a specific severity to a specific location.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
272
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
273 The standard library includes quite a few handler types; this tutorial uses only
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
274 :class:`StreamHandler` and :class:`FileHandler` in its examples.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
275
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
276 There are very few methods in a handler for application developers to concern
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
277 themselves with. The only handler methods that seem relevant for application
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
278 developers who are using the built-in handler objects (that is, not creating
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
279 custom handlers) are the following configuration methods:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
280
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
281 * The :meth:`Handler.setLevel` method, just as in logger objects, specifies the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
282 lowest severity that will be dispatched to the appropriate destination. Why
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
283 are there two :func:`setLevel` methods? The level set in the logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
284 determines which severity of messages it will pass to its handlers. The level
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
285 set in each handler determines which messages that handler will send on.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
286 :func:`setFormatter` selects a Formatter object for this handler to use.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
287
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
288 * :func:`addFilter` and :func:`removeFilter` respectively configure and
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
289 deconfigure filter objects on handlers.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
290
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
291 Application code should not directly instantiate and use handlers. Instead, the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
292 :class:`Handler` class is a base class that defines the interface that all
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
293 Handlers should have and establishes some default behavior that child classes
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
294 can use (or override).
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
295
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
296
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
297 Formatters
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
298 ^^^^^^^^^^
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
299
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
300 Formatter objects configure the final order, structure, and contents of the log
45512
e57ffa2b5d07 Add minor markup for a string.
Brett Cannon <bcannon@gmail.com>
parents: 45429
diff changeset
301 message. Unlike the base :class:`logging.Handler` class, application code may
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
302 instantiate formatter classes, although you could likely subclass the formatter
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
303 if your application needs special behavior. The constructor takes two optional
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
304 arguments: a message format string and a date format string. If there is no
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
305 message format string, the default is to use the raw message. If there is no
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
306 date format string, the default date format is::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
307
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
308 %Y-%m-%d %H:%M:%S
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
309
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
310 with the milliseconds tacked on at the end.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
311
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
312 The message format string uses ``%(<dictionary key>)s`` styled string
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
313 substitution; the possible keys are documented in :ref:`formatter`.
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
314
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
315 The following message format string will log the time in a human-readable
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
316 format, the severity of the message, and the contents of the message, in that
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
317 order::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
318
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
319 "%(asctime)s - %(levelname)s - %(message)s"
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
320
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
321
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
322 Configuring Logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
323 ^^^^^^^^^^^^^^^^^^^
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
324
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
325 Programmers can configure logging either by creating loggers, handlers, and
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
326 formatters explicitly in a main module with the configuration methods listed
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
327 above (using Python code), or by creating a logging config file. The following
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
328 code is an example of configuring a very simple logger, a console handler, and a
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
329 simple formatter in a Python module::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
330
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
331 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
332
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
333 # create logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
334 logger = logging.getLogger("simple_example")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
335 logger.setLevel(logging.DEBUG)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
336 # create console handler and set level to debug
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
337 ch = logging.StreamHandler()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
338 ch.setLevel(logging.DEBUG)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
339 # create formatter
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
340 formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
341 # add formatter to ch
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
342 ch.setFormatter(formatter)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
343 # add ch to logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
344 logger.addHandler(ch)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
345
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
346 # "application" code
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
347 logger.debug("debug message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
348 logger.info("info message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
349 logger.warn("warn message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
350 logger.error("error message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
351 logger.critical("critical message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
352
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
353 Running this module from the command line produces the following output::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
354
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
355 $ python simple_logging_module.py
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
356 2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
357 2005-03-19 15:10:26,620 - simple_example - INFO - info message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
358 2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
359 2005-03-19 15:10:26,697 - simple_example - ERROR - error message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
360 2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
361
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
362 The following Python module creates a logger, handler, and formatter nearly
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
363 identical to those in the example listed above, with the only difference being
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
364 the names of the objects::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
365
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
366 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
367 import logging.config
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
368
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
369 logging.config.fileConfig("logging.conf")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
370
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
371 # create logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
372 logger = logging.getLogger("simpleExample")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
373
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
374 # "application" code
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
375 logger.debug("debug message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
376 logger.info("info message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
377 logger.warn("warn message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
378 logger.error("error message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
379 logger.critical("critical message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
380
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
381 Here is the logging.conf file::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
382
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
383 [loggers]
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
384 keys=root,simpleExample
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
385
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
386 [handlers]
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
387 keys=consoleHandler
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
388
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
389 [formatters]
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
390 keys=simpleFormatter
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
391
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
392 [logger_root]
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
393 level=DEBUG
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
394 handlers=consoleHandler
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
395
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
396 [logger_simpleExample]
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
397 level=DEBUG
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
398 handlers=consoleHandler
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
399 qualname=simpleExample
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
400 propagate=0
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
401
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
402 [handler_consoleHandler]
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
403 class=StreamHandler
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
404 level=DEBUG
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
405 formatter=simpleFormatter
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
406 args=(sys.stdout,)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
407
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
408 [formatter_simpleFormatter]
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
409 format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
410 datefmt=
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
411
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
412 The output is nearly identical to that of the non-config-file-based example::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
413
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
414 $ python simple_logging_config.py
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
415 2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
416 2005-03-19 15:38:55,979 - simpleExample - INFO - info message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
417 2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
418 2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
419 2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
420
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
421 You can see that the config file approach has a few advantages over the Python
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
422 code approach, mainly separation of configuration and code and the ability of
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
423 noncoders to easily modify the logging properties.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
424
50694
dbe39ebd3025 Minor documentation changes cross-referencing NullHandler to the documentation on configuring logging in a library.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50455
diff changeset
425 .. _library-config:
dbe39ebd3025 Minor documentation changes cross-referencing NullHandler to the documentation on configuring logging in a library.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50455
diff changeset
426
48927
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
427 Configuring Logging for a Library
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
428 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
429
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
430 When developing a library which uses logging, some consideration needs to be
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
431 given to its configuration. If the using application does not use logging, and
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
432 library code makes logging calls, then a one-off message "No handlers could be
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
433 found for logger X.Y.Z" is printed to the console. This message is intended
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
434 to catch mistakes in logging configuration, but will confuse an application
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
435 developer who is not aware of logging by the library.
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
436
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
437 In addition to documenting how a library uses logging, a good way to configure
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
438 library logging so that it does not cause a spurious message is to add a
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
439 handler which does nothing. This avoids the message being printed, since a
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
440 handler will be found: it just doesn't produce any output. If the library user
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
441 configures logging for application use, presumably that configuration will add
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
442 some handlers, and if levels are suitably configured then logging calls made
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
443 in library code will send output to those handlers, as normal.
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
444
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
445 A do-nothing handler can be simply defined as follows::
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
446
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
447 import logging
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
448
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
449 class NullHandler(logging.Handler):
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
450 def emit(self, record):
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
451 pass
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
452
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
453 An instance of this handler should be added to the top-level logger of the
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
454 logging namespace used by the library. If all logging by a library *foo* is
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
455 done using loggers with names matching "foo.x.y", then the code::
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
456
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
457 import logging
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
458
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
459 h = NullHandler()
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
460 logging.getLogger("foo").addHandler(h)
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
461
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
462 should have the desired effect. If an organisation produces a number of
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
463 libraries, then the logger name specified can be "orgname.foo" rather than
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
464 just "foo".
519e0475991f Added section about configuring logging in a library. Thanks to Thomas Heller for the idea.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48011
diff changeset
465
49955
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
466 .. versionadded:: 2.7
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
467
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
468 The :class:`NullHandler` class was not present in previous versions, but is now
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
469 included, so that it need not be defined in library code.
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
470
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
471
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
472
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
473 Logging Levels
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
474 --------------
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
475
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
476 The numeric values of logging levels are given in the following table. These are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
477 primarily of interest if you want to define your own levels, and need them to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
478 have specific values relative to the predefined levels. If you define a level
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
479 with the same numeric value, it overwrites the predefined value; the predefined
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
480 name is lost.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
481
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
482 +--------------+---------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
483 | Level | Numeric value |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
484 +==============+===============+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
485 | ``CRITICAL`` | 50 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
486 +--------------+---------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
487 | ``ERROR`` | 40 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
488 +--------------+---------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
489 | ``WARNING`` | 30 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
490 +--------------+---------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
491 | ``INFO`` | 20 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
492 +--------------+---------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
493 | ``DEBUG`` | 10 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
494 +--------------+---------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
495 | ``NOTSET`` | 0 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
496 +--------------+---------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
497
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
498 Levels can also be associated with loggers, being set either by the developer or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
499 through loading a saved logging configuration. When a logging method is called
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
500 on a logger, the logger compares its own level with the level associated with
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
501 the method call. If the logger's level is higher than the method call's, no
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
502 logging message is actually generated. This is the basic mechanism controlling
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
503 the verbosity of logging output.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
504
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
505 Logging messages are encoded as instances of the :class:`LogRecord` class. When
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
506 a logger decides to actually log an event, a :class:`LogRecord` instance is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
507 created from the logging message.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
508
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
509 Logging messages are subjected to a dispatch mechanism through the use of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
510 :dfn:`handlers`, which are instances of subclasses of the :class:`Handler`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
511 class. Handlers are responsible for ensuring that a logged message (in the form
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
512 of a :class:`LogRecord`) ends up in a particular location (or set of locations)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
513 which is useful for the target audience for that message (such as end users,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
514 support desk staff, system administrators, developers). Handlers are passed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
515 :class:`LogRecord` instances intended for particular destinations. Each logger
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
516 can have zero, one or more handlers associated with it (via the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
517 :meth:`addHandler` method of :class:`Logger`). In addition to any handlers
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
518 directly associated with a logger, *all handlers associated with all ancestors
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
519 of the logger* are called to dispatch the message.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
520
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
521 Just as for loggers, handlers can have levels associated with them. A handler's
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
522 level acts as a filter in the same way as a logger's level does. If a handler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
523 decides to actually dispatch an event, the :meth:`emit` method is used to send
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
524 the message to its destination. Most user-defined subclasses of :class:`Handler`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
525 will need to override this :meth:`emit`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
526
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
527 Useful Handlers
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
528 ---------------
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
529
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
530 In addition to the base :class:`Handler` class, many useful subclasses are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
531 provided:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
532
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
533 #. :ref:`stream-handler` instances send error messages to streams (file-like
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
534 objects).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
535
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
536 #. :ref:`file-handler` instances send error messages to disk files.
50808
2680a4beaea1 Minor changes/corrections in markup.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50807
diff changeset
537
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
538 #. :class:`BaseRotatingHandler` is the base class for handlers that
50750
bc92bb20819f Minor changes/corrections in markup.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50714
diff changeset
539 rotate log files at a certain point. It is not meant to be instantiated
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
540 directly. Instead, use :ref:`rotating-file-handler` or
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
541 :ref:`timed-rotating-file-handler`.
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
542
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
543 #. :ref:`rotating-file-handler` instances send error messages to disk
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
544 files, with support for maximum log file sizes and log file rotation.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
545
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
546 #. :ref:`timed-rotating-file-handler` instances send error messages to
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
547 disk files, rotating the log file at certain timed intervals.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
548
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
549 #. :ref:`socket-handler` instances send error messages to TCP/IP
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
550 sockets.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
551
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
552 #. :ref:`datagram-handler` instances send error messages to UDP
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
553 sockets.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
554
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
555 #. :ref:`smtp-handler` instances send error messages to a designated
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
556 email address.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
557
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
558 #. :ref:`syslog-handler` instances send error messages to a Unix
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
559 syslog daemon, possibly on a remote machine.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
560
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
561 #. :ref:`nt-eventlog-handler` instances send error messages to a
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
562 Windows NT/2000/XP event log.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
563
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
564 #. :ref:`memory-handler` instances send error messages to a buffer
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
565 in memory, which is flushed whenever specific criteria are met.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
566
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
567 #. :ref:`http-handler` instances send error messages to an HTTP
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
568 server using either ``GET`` or ``POST`` semantics.
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
569
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
570 #. :ref:`watched-file-handler` instances watch the file they are
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
571 logging to. If the file changes, it is closed and reopened using the file
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
572 name. This handler is only useful on Unix-like systems; Windows does not
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
573 support the underlying mechanism used.
50714
bbf464210984 Corrected minor typo and added .currentmodule directives to fix missing cross-references.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50695
diff changeset
574
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
575 #. :ref:`null-handler` instances do nothing with error messages. They are used
49955
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
576 by library developers who want to use logging, but want to avoid the "No
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
577 handlers could be found for logger XXX" message which can be displayed if
50694
dbe39ebd3025 Minor documentation changes cross-referencing NullHandler to the documentation on configuring logging in a library.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50455
diff changeset
578 the library user has not configured logging. See :ref:`library-config` for
dbe39ebd3025 Minor documentation changes cross-referencing NullHandler to the documentation on configuring logging in a library.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50455
diff changeset
579 more information.
49955
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
580
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
581 .. versionadded:: 2.7
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
582
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
583 The :class:`NullHandler` class was not present in previous versions.
878d40468c4e Issue #4384: Added logging integration with warnings module using captureWarnings(). This change includes a NullHandler which does nothing; it will be of use to library developers who want to avoid the "No handlers could be found for logger XXX" message which can appear if the library user doesn't configure logging.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48934
diff changeset
584
50371
f73fc441744f Minor documentation change relating to NullHandler.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 49955
diff changeset
585 The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler`
f73fc441744f Minor documentation change relating to NullHandler.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 49955
diff changeset
586 classes are defined in the core logging package. The other handlers are
f73fc441744f Minor documentation change relating to NullHandler.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 49955
diff changeset
587 defined in a sub- module, :mod:`logging.handlers`. (There is also another
f73fc441744f Minor documentation change relating to NullHandler.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 49955
diff changeset
588 sub-module, :mod:`logging.config`, for configuration functionality.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
589
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
590 Logged messages are formatted for presentation through instances of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
591 :class:`Formatter` class. They are initialized with a format string suitable for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
592 use with the % operator and a dictionary.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
593
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
594 For formatting multiple messages in a batch, instances of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
595 :class:`BufferingFormatter` can be used. In addition to the format string (which
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
596 is applied to each message in the batch), there is provision for header and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
597 trailer format strings.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
598
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
599 When filtering based on logger level and/or handler level is not enough,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
600 instances of :class:`Filter` can be added to both :class:`Logger` and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
601 :class:`Handler` instances (through their :meth:`addFilter` method). Before
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
602 deciding to process a message further, both loggers and handlers consult all
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
603 their filters for permission. If any filter returns a false value, the message
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
604 is not processed further.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
605
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
606 The basic :class:`Filter` functionality allows filtering by specific logger
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
607 name. If this feature is used, messages sent to the named logger and its
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
608 children are allowed through the filter, and all others dropped.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
609
50807
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
610 Module-Level Functions
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
611 ----------------------
884cd3f19b20 Made minor changes/corrections in markup. Added a couple of section headings.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50750
diff changeset
612
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
613 In addition to the classes described above, there are a number of module- level
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
614 functions.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
615
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
616
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
617 .. function:: getLogger([name])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
618
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
619 Return a logger with the specified name or, if no name is specified, return a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
620 logger which is the root logger of the hierarchy. If specified, the name is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
621 typically a dot-separated hierarchical name like *"a"*, *"a.b"* or *"a.b.c.d"*.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
622 Choice of these names is entirely up to the developer who is using logging.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
623
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
624 All calls to this function with a given name return the same logger instance.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
625 This means that logger instances never need to be passed between different parts
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
626 of an application.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
627
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
628
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
629 .. function:: getLoggerClass()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
630
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
631 Return either the standard :class:`Logger` class, or the last class passed to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
632 :func:`setLoggerClass`. This function may be called from within a new class
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
633 definition, to ensure that installing a customised :class:`Logger` class will
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
634 not undo customisations already applied by other code. For example::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
635
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
636 class MyLogger(logging.getLoggerClass()):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
637 # ... override behaviour here
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
638
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
639
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
640 .. function:: debug(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
641
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
642 Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
643 message format string, and the *args* are the arguments which are merged into
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
644 *msg* using the string formatting operator. (Note that this means that you can
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
645 use keywords in the format string, together with a single dictionary argument.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
646
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
647 There are two keyword arguments in *kwargs* which are inspected: *exc_info*
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
648 which, if it does not evaluate as false, causes exception information to be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
649 added to the logging message. If an exception tuple (in the format returned by
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
650 :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
651 is called to get the exception information.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
652
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
653 The other optional keyword argument is *extra* which can be used to pass a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
654 dictionary which is used to populate the __dict__ of the LogRecord created for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
655 the logging event with user-defined attributes. These custom attributes can then
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
656 be used as you like. For example, they could be incorporated into logged
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
657 messages. For example::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
658
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
659 FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
660 logging.basicConfig(format=FORMAT)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
661 d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
662 logging.warning("Protocol problem: %s", "connection reset", extra=d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
663
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
664 would print something like ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
665
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
666 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
667
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
668 The keys in the dictionary passed in *extra* should not clash with the keys used
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
669 by the logging system. (See the :class:`Formatter` documentation for more
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
670 information on which keys are used by the logging system.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
671
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
672 If you choose to use these attributes in logged messages, you need to exercise
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
673 some care. In the above example, for instance, the :class:`Formatter` has been
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
674 set up with a format string which expects 'clientip' and 'user' in the attribute
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
675 dictionary of the LogRecord. If these are missing, the message will not be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
676 logged because a string formatting exception will occur. So in this case, you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
677 always need to pass the *extra* dictionary with these keys.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
678
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
679 While this might be annoying, this feature is intended for use in specialized
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
680 circumstances, such as multi-threaded servers where the same code executes in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
681 many contexts, and interesting conditions which arise are dependent on this
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
682 context (such as remote client IP address and authenticated user name, in the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
683 above example). In such circumstances, it is likely that specialized
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
684 :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
685
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
686 .. versionchanged:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
687 *extra* was added.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
688
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
689
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
690 .. function:: info(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
691
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
692 Logs a message with level :const:`INFO` on the root logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
693 interpreted as for :func:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
694
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
695
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
696 .. function:: warning(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
697
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
698 Logs a message with level :const:`WARNING` on the root logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
699 interpreted as for :func:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
700
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
701
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
702 .. function:: error(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
703
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
704 Logs a message with level :const:`ERROR` on the root logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
705 interpreted as for :func:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
706
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
707
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
708 .. function:: critical(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
709
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
710 Logs a message with level :const:`CRITICAL` on the root logger. The arguments
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
711 are interpreted as for :func:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
712
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
713
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
714 .. function:: exception(msg[, *args])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
715
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
716 Logs a message with level :const:`ERROR` on the root logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
717 interpreted as for :func:`debug`. Exception info is added to the logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
718 message. This function should only be called from an exception handler.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
719
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
720
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
721 .. function:: log(level, msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
722
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
723 Logs a message with level *level* on the root logger. The other arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
724 interpreted as for :func:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
725
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
726
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
727 .. function:: disable(lvl)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
728
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
729 Provides an overriding level *lvl* for all loggers which takes precedence over
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
730 the logger's own level. When the need arises to temporarily throttle logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
731 output down across the whole application, this function can be useful.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
732
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
733
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
734 .. function:: addLevelName(lvl, levelName)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
735
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
736 Associates level *lvl* with text *levelName* in an internal dictionary, which is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
737 used to map numeric levels to a textual representation, for example when a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
738 :class:`Formatter` formats a message. This function can also be used to define
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
739 your own levels. The only constraints are that all levels used must be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
740 registered using this function, levels should be positive integers and they
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
741 should increase in increasing order of severity.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
742
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
743
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
744 .. function:: getLevelName(lvl)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
745
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
746 Returns the textual representation of logging level *lvl*. If the level is one
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
747 of the predefined levels :const:`CRITICAL`, :const:`ERROR`, :const:`WARNING`,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
748 :const:`INFO` or :const:`DEBUG` then you get the corresponding string. If you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
749 have associated levels with names using :func:`addLevelName` then the name you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
750 have associated with *lvl* is returned. If a numeric value corresponding to one
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
751 of the defined levels is passed in, the corresponding string representation is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
752 returned. Otherwise, the string "Level %s" % lvl is returned.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
753
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
754
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
755 .. function:: makeLogRecord(attrdict)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
756
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
757 Creates and returns a new :class:`LogRecord` instance whose attributes are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
758 defined by *attrdict*. This function is useful for taking a pickled
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
759 :class:`LogRecord` attribute dictionary, sent over a socket, and reconstituting
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
760 it as a :class:`LogRecord` instance at the receiving end.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
761
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
762
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
763 .. function:: basicConfig([**kwargs])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
764
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
765 Does basic configuration for the logging system by creating a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
766 :class:`StreamHandler` with a default :class:`Formatter` and adding it to the
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
767 root logger. The function does nothing if any handlers have been defined for
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
768 the root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
769 :func:`error` and :func:`critical` will call :func:`basicConfig` automatically
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
770 if no handlers are defined for the root logger.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
771
46783
84af0cfa7b81 Add a sentence to basicConfig() that is in the docstring.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
772 This function does nothing if the root logger already has handlers configured.
84af0cfa7b81 Add a sentence to basicConfig() that is in the docstring.
Georg Brandl <georg@python.org>
parents: 46555
diff changeset
773
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
774 .. versionchanged:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
775 Formerly, :func:`basicConfig` did not take any keyword arguments.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
776
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
777 The following keyword arguments are supported.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
778
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
779 +--------------+---------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
780 | Format | Description |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
781 +==============+=============================================+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
782 | ``filename`` | Specifies that a FileHandler be created, |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
783 | | using the specified filename, rather than a |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
784 | | StreamHandler. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
785 +--------------+---------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
786 | ``filemode`` | Specifies the mode to open the file, if |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
787 | | filename is specified (if filemode is |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
788 | | unspecified, it defaults to 'a'). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
789 +--------------+---------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
790 | ``format`` | Use the specified format string for the |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
791 | | handler. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
792 +--------------+---------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
793 | ``datefmt`` | Use the specified date/time format. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
794 +--------------+---------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
795 | ``level`` | Set the root logger level to the specified |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
796 | | level. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
797 +--------------+---------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
798 | ``stream`` | Use the specified stream to initialize the |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
799 | | StreamHandler. Note that this argument is |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
800 | | incompatible with 'filename' - if both are |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
801 | | present, 'stream' is ignored. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
802 +--------------+---------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
803
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
804
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
805 .. function:: shutdown()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
806
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
807 Informs the logging system to perform an orderly shutdown by flushing and
45783
79dea65332f8 Clarified documentation on use of shutdown().
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 45611
diff changeset
808 closing all handlers. This should be called at application exit and no
79dea65332f8 Clarified documentation on use of shutdown().
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 45611
diff changeset
809 further use of the logging system should be made after this call.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
810
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
811
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
812 .. function:: setLoggerClass(klass)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
813
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
814 Tells the logging system to use the class *klass* when instantiating a logger.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
815 The class should define :meth:`__init__` such that only a name argument is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
816 required, and the :meth:`__init__` should call :meth:`Logger.__init__`. This
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
817 function is typically called before any loggers are instantiated by applications
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
818 which need to use custom logger behavior.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
819
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
820
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
821 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
822
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
823 :pep:`282` - A Logging System
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
824 The proposal which described this feature for inclusion in the Python standard
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
825 library.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
826
44195
9ad4aedf349b Diverse markup fixes.
Georg Brandl <georg@python.org>
parents: 44151
diff changeset
827 `Original Python logging package <http://www.red-dove.com/python_logging.html>`_
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
828 This is the original source for the :mod:`logging` package. The version of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
829 package available from this site is suitable for use with Python 1.5.2, 2.1.x
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
830 and 2.2.x, which do not include the :mod:`logging` package in the standard
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
831 library.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
832
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
833 .. _logger:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
834
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
835 Logger Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
836 --------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
837
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
838 Loggers have the following attributes and methods. Note that Loggers are never
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
839 instantiated directly, but always through the module-level function
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
840 ``logging.getLogger(name)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
841
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
842
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
843 .. attribute:: Logger.propagate
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
844
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
845 If this evaluates to false, logging messages are not passed by this logger or by
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
846 child loggers to higher level (ancestor) loggers. The constructor sets this
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
847 attribute to 1.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
848
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
849
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
850 .. method:: Logger.setLevel(lvl)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
851
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
852 Sets the threshold for this logger to *lvl*. Logging messages which are less
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
853 severe than *lvl* will be ignored. When a logger is created, the level is set to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
854 :const:`NOTSET` (which causes all messages to be processed when the logger is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
855 the root logger, or delegation to the parent when the logger is a non-root
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
856 logger). Note that the root logger is created with level :const:`WARNING`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
857
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
858 The term "delegation to the parent" means that if a logger has a level of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
859 NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
860 a level other than NOTSET is found, or the root is reached.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
861
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
862 If an ancestor is found with a level other than NOTSET, then that ancestor's
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
863 level is treated as the effective level of the logger where the ancestor search
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
864 began, and is used to determine how a logging event is handled.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
865
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
866 If the root is reached, and it has a level of NOTSET, then all messages will be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
867 processed. Otherwise, the root's level will be used as the effective level.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
868
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
869
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
870 .. method:: Logger.isEnabledFor(lvl)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
871
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
872 Indicates if a message of severity *lvl* would be processed by this logger.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
873 This method checks first the module-level level set by
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
874 ``logging.disable(lvl)`` and then the logger's effective level as determined
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
875 by :meth:`getEffectiveLevel`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
876
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
877
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
878 .. method:: Logger.getEffectiveLevel()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
879
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
880 Indicates the effective level for this logger. If a value other than
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
881 :const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
882 the hierarchy is traversed towards the root until a value other than
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
883 :const:`NOTSET` is found, and that value is returned.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
884
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
885
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
886 .. method:: Logger.debug(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
887
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
888 Logs a message with level :const:`DEBUG` on this logger. The *msg* is the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
889 message format string, and the *args* are the arguments which are merged into
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
890 *msg* using the string formatting operator. (Note that this means that you can
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
891 use keywords in the format string, together with a single dictionary argument.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
892
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
893 There are two keyword arguments in *kwargs* which are inspected: *exc_info*
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
894 which, if it does not evaluate as false, causes exception information to be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
895 added to the logging message. If an exception tuple (in the format returned by
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
896 :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
897 is called to get the exception information.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
898
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
899 The other optional keyword argument is *extra* which can be used to pass a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
900 dictionary which is used to populate the __dict__ of the LogRecord created for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
901 the logging event with user-defined attributes. These custom attributes can then
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
902 be used as you like. For example, they could be incorporated into logged
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
903 messages. For example::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
904
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
905 FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
906 logging.basicConfig(format=FORMAT)
43643
eb908a19c05a Bug #1313, fix typo (wrong variable name) in example.
Neal Norwitz <nnorwitz@gmail.com>
parents: 43631
diff changeset
907 d = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' }
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
908 logger = logging.getLogger("tcpserver")
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
909 logger.warning("Protocol problem: %s", "connection reset", extra=d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
910
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
911 would print something like ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
912
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
913 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
914
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
915 The keys in the dictionary passed in *extra* should not clash with the keys used
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
916 by the logging system. (See the :class:`Formatter` documentation for more
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
917 information on which keys are used by the logging system.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
918
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
919 If you choose to use these attributes in logged messages, you need to exercise
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
920 some care. In the above example, for instance, the :class:`Formatter` has been
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
921 set up with a format string which expects 'clientip' and 'user' in the attribute
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
922 dictionary of the LogRecord. If these are missing, the message will not be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
923 logged because a string formatting exception will occur. So in this case, you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
924 always need to pass the *extra* dictionary with these keys.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
925
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
926 While this might be annoying, this feature is intended for use in specialized
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
927 circumstances, such as multi-threaded servers where the same code executes in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
928 many contexts, and interesting conditions which arise are dependent on this
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
929 context (such as remote client IP address and authenticated user name, in the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
930 above example). In such circumstances, it is likely that specialized
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
931 :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
932
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
933 .. versionchanged:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
934 *extra* was added.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
935
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
936
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
937 .. method:: Logger.info(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
938
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
939 Logs a message with level :const:`INFO` on this logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
940 interpreted as for :meth:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
941
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
942
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
943 .. method:: Logger.warning(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
944
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
945 Logs a message with level :const:`WARNING` on this logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
946 interpreted as for :meth:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
947
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
948
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
949 .. method:: Logger.error(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
950
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
951 Logs a message with level :const:`ERROR` on this logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
952 interpreted as for :meth:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
953
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
954
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
955 .. method:: Logger.critical(msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
956
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
957 Logs a message with level :const:`CRITICAL` on this logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
958 interpreted as for :meth:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
959
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
960
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
961 .. method:: Logger.log(lvl, msg[, *args[, **kwargs]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
962
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
963 Logs a message with integer level *lvl* on this logger. The other arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
964 interpreted as for :meth:`debug`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
965
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
966
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
967 .. method:: Logger.exception(msg[, *args])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
968
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
969 Logs a message with level :const:`ERROR` on this logger. The arguments are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
970 interpreted as for :meth:`debug`. Exception info is added to the logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
971 message. This method should only be called from an exception handler.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
972
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
973
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
974 .. method:: Logger.addFilter(filt)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
975
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
976 Adds the specified filter *filt* to this logger.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
977
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
978
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
979 .. method:: Logger.removeFilter(filt)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
980
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
981 Removes the specified filter *filt* from this logger.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
982
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
983
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
984 .. method:: Logger.filter(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
985
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
986 Applies this logger's filters to the record and returns a true value if the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
987 record is to be processed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
988
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
989
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
990 .. method:: Logger.addHandler(hdlr)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
991
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
992 Adds the specified handler *hdlr* to this logger.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
993
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
994
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
995 .. method:: Logger.removeHandler(hdlr)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
996
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
997 Removes the specified handler *hdlr* from this logger.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
998
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
999
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1000 .. method:: Logger.findCaller()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1001
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1002 Finds the caller's source filename and line number. Returns the filename, line
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1003 number and function name as a 3-element tuple.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1004
42630
20aec9f34598 Manually patched a few things that didn't get merged in, but should.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
1005 .. versionchanged:: 2.4
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1006 The function name was added. In earlier versions, the filename and line number
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1007 were returned as a 2-element tuple..
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1008
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1009
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1010 .. method:: Logger.handle(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1011
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1012 Handles a record by passing it to all handlers associated with this logger and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1013 its ancestors (until a false value of *propagate* is found). This method is used
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1014 for unpickled records received from a socket, as well as those created locally.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1015 Logger-level filtering is applied using :meth:`filter`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1016
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1017
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1018 .. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info [, func, extra])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1019
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1020 This is a factory method which can be overridden in subclasses to create
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1021 specialized :class:`LogRecord` instances.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1022
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1023 .. versionchanged:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1024 *func* and *extra* were added.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1025
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1026
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1027 .. _minimal-example:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1028
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1029 Basic example
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1030 -------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1031
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1032 .. versionchanged:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1033 formerly :func:`basicConfig` did not take any keyword arguments.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1034
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1035 The :mod:`logging` package provides a lot of flexibility, and its configuration
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1036 can appear daunting. This section demonstrates that simple use of the logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1037 package is possible.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1038
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1039 The simplest example shows logging to the console::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1040
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1041 import logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1042
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1043 logging.debug('A debug message')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1044 logging.info('Some information')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1045 logging.warning('A shot across the bows')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1046
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1047 If you run the above script, you'll see this::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1048
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1049 WARNING:root:A shot across the bows
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1050
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1051 Because no particular logger was specified, the system used the root logger. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1052 debug and info messages didn't appear because by default, the root logger is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1053 configured to only handle messages with a severity of WARNING or above. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1054 message format is also a configuration default, as is the output destination of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1055 the messages - ``sys.stderr``. The severity level, the message format and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1056 destination can be easily changed, as shown in the example below::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1057
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1058 import logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1059
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1060 logging.basicConfig(level=logging.DEBUG,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1061 format='%(asctime)s %(levelname)s %(message)s',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1062 filename='/tmp/myapp.log',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1063 filemode='w')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1064 logging.debug('A debug message')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1065 logging.info('Some information')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1066 logging.warning('A shot across the bows')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1067
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1068 The :meth:`basicConfig` method is used to change the configuration defaults,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1069 which results in output (written to ``/tmp/myapp.log``) which should look
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1070 something like the following::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1071
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1072 2004-07-02 13:00:08,743 DEBUG A debug message
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1073 2004-07-02 13:00:08,743 INFO Some information
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1074 2004-07-02 13:00:08,743 WARNING A shot across the bows
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1075
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1076 This time, all messages with a severity of DEBUG or above were handled, and the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1077 format of the messages was also changed, and output went to the specified file
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1078 rather than the console.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1079
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1080 Formatting uses standard Python string formatting - see section
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1081 :ref:`string-formatting`. The format string takes the following common
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1082 specifiers. For a complete list of specifiers, consult the :class:`Formatter`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1083 documentation.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1084
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1085 +-------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1086 | Format | Description |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1087 +===================+===============================================+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1088 | ``%(name)s`` | Name of the logger (logging channel). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1089 +-------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1090 | ``%(levelname)s`` | Text logging level for the message |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1091 | | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1092 | | ``'ERROR'``, ``'CRITICAL'``). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1093 +-------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1094 | ``%(asctime)s`` | Human-readable time when the |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1095 | | :class:`LogRecord` was created. By default |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1096 | | this is of the form "2003-07-08 16:49:45,896" |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1097 | | (the numbers after the comma are millisecond |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1098 | | portion of the time). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1099 +-------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1100 | ``%(message)s`` | The logged message. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1101 +-------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1102
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1103 To change the date/time format, you can pass an additional keyword parameter,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1104 *datefmt*, as in the following::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1105
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1106 import logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1107
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1108 logging.basicConfig(level=logging.DEBUG,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1109 format='%(asctime)s %(levelname)-8s %(message)s',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1110 datefmt='%a, %d %b %Y %H:%M:%S',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1111 filename='/temp/myapp.log',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1112 filemode='w')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1113 logging.debug('A debug message')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1114 logging.info('Some information')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1115 logging.warning('A shot across the bows')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1116
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1117 which would result in output like ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1118
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1119 Fri, 02 Jul 2004 13:06:18 DEBUG A debug message
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1120 Fri, 02 Jul 2004 13:06:18 INFO Some information
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1121 Fri, 02 Jul 2004 13:06:18 WARNING A shot across the bows
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1122
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1123 The date format string follows the requirements of :func:`strftime` - see the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1124 documentation for the :mod:`time` module.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1126 If, instead of sending logging output to the console or a file, you'd rather use
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1127 a file-like object which you have created separately, you can pass it to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1128 :func:`basicConfig` using the *stream* keyword argument. Note that if both
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1129 *stream* and *filename* keyword arguments are passed, the *stream* argument is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1130 ignored.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1131
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1132 Of course, you can put variable information in your output. To do this, simply
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1133 have the message be a format string and pass in additional arguments containing
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1134 the variable information, as in the following example::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1135
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1136 import logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1137
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1138 logging.basicConfig(level=logging.DEBUG,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1139 format='%(asctime)s %(levelname)-8s %(message)s',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1140 datefmt='%a, %d %b %Y %H:%M:%S',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1141 filename='/temp/myapp.log',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1142 filemode='w')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1143 logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1144
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1145 which would result in ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1146
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1147 Wed, 21 Jul 2004 15:35:16 ERROR Pack my box with 5 dozen liquor jugs
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1148
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1149
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1150 .. _multiple-destinations:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1151
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1152 Logging to multiple destinations
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1153 --------------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1154
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1155 Let's say you want to log to console and file with different message formats and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1156 in differing circumstances. Say you want to log messages with levels of DEBUG
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1157 and higher to file, and those messages at level INFO and higher to the console.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1158 Let's also assume that the file should contain timestamps, but the console
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1159 messages should not. Here's how you can achieve this::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1160
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1161 import logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1162
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1163 # set up logging to file - see previous section for more details
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1164 logging.basicConfig(level=logging.DEBUG,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1165 format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1166 datefmt='%m-%d %H:%M',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1167 filename='/temp/myapp.log',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1168 filemode='w')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1169 # define a Handler which writes INFO messages or higher to the sys.stderr
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1170 console = logging.StreamHandler()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1171 console.setLevel(logging.INFO)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1172 # set a format which is simpler for console use
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1173 formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1174 # tell the handler to use this format
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1175 console.setFormatter(formatter)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1176 # add the handler to the root logger
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1177 logging.getLogger('').addHandler(console)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1178
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1179 # Now, we can log to the root logger, or any other logger. First the root...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1180 logging.info('Jackdaws love my big sphinx of quartz.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1181
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1182 # Now, define a couple of other loggers which might represent areas in your
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1183 # application:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1184
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1185 logger1 = logging.getLogger('myapp.area1')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1186 logger2 = logging.getLogger('myapp.area2')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1187
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1188 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1189 logger1.info('How quickly daft jumping zebras vex.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1190 logger2.warning('Jail zesty vixen who grabbed pay from quack.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1191 logger2.error('The five boxing wizards jump quickly.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1192
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1193 When you run this, on the console you will see ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1194
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1195 root : INFO Jackdaws love my big sphinx of quartz.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1196 myapp.area1 : INFO How quickly daft jumping zebras vex.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1197 myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1198 myapp.area2 : ERROR The five boxing wizards jump quickly.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1199
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1200 and in the file you will see something like ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1201
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1202 10-22 22:19 root INFO Jackdaws love my big sphinx of quartz.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1203 10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1204 10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1205 10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1206 10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1207
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1208 As you can see, the DEBUG message only shows up in the file. The other messages
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1209 are sent to both destinations.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1210
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1211 This example uses console and file handlers, but you can use any number and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1212 combination of handlers you choose.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1213
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1214
44580
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1215 .. _context-info:
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1216
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1217 Adding contextual information to your logging output
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1218 ----------------------------------------------------
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1219
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1220 Sometimes you want logging output to contain contextual information in
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1221 addition to the parameters passed to the logging call. For example, in a
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1222 networked application, it may be desirable to log client-specific information
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1223 in the log (e.g. remote client's username, or IP address). Although you could
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1224 use the *extra* parameter to achieve this, it's not always convenient to pass
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1225 the information in this way. While it might be tempting to create
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1226 :class:`Logger` instances on a per-connection basis, this is not a good idea
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1227 because these instances are not garbage collected. While this is not a problem
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1228 in practice, when the number of :class:`Logger` instances is dependent on the
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1229 level of granularity you want to use in logging an application, it could
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1230 be hard to manage if the number of :class:`Logger` instances becomes
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1231 effectively unbounded.
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1232
44744
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1233 An easy way in which you can pass contextual information to be output along
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1234 with logging event information is to use the :class:`LoggerAdapter` class.
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1235 This class is designed to look like a :class:`Logger`, so that you can call
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1236 :meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`,
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1237 :meth:`exception`, :meth:`critical` and :meth:`log`. These methods have the
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1238 same signatures as their counterparts in :class:`Logger`, so you can use the
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1239 two types of instances interchangeably.
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1240
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1241 When you create an instance of :class:`LoggerAdapter`, you pass it a
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1242 :class:`Logger` instance and a dict-like object which contains your contextual
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1243 information. When you call one of the logging methods on an instance of
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1244 :class:`LoggerAdapter`, it delegates the call to the underlying instance of
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1245 :class:`Logger` passed to its constructor, and arranges to pass the contextual
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1246 information in the delegated call. Here's a snippet from the code of
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1247 :class:`LoggerAdapter`::
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1248
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1249 def debug(self, msg, *args, **kwargs):
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1250 """
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1251 Delegate a debug call to the underlying logger, after adding
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1252 contextual information from this adapter instance.
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1253 """
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1254 msg, kwargs = self.process(msg, kwargs)
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1255 self.logger.debug(msg, *args, **kwargs)
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1256
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1257 The :meth:`process` method of :class:`LoggerAdapter` is where the contextual
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1258 information is added to the logging output. It's passed the message and
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1259 keyword arguments of the logging call, and it passes back (potentially)
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1260 modified versions of these to use in the call to the underlying logger. The
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1261 default implementation of this method leaves the message alone, but inserts
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1262 an "extra" key in the keyword argument whose value is the dict-like object
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1263 passed to the constructor. Of course, if you had passed an "extra" keyword
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1264 argument in the call to the adapter, it will be silently overwritten.
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1265
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1266 The advantage of using "extra" is that the values in the dict-like object are
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1267 merged into the :class:`LogRecord` instance's __dict__, allowing you to use
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1268 customized strings with your :class:`Formatter` instances which know about
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1269 the keys of the dict-like object. If you need a different method, e.g. if you
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1270 want to prepend or append the contextual information to the message string,
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1271 you just need to subclass :class:`LoggerAdapter` and override :meth:`process`
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1272 to do what you need. Here's an example script which uses this class, which
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1273 also illustrates what dict-like behaviour is needed from an arbitrary
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1274 "dict-like" object for use in the constructor::
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1275
44758
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1276 import logging
44849
32412fceb1b3 Minor documentation change - hyperlink tidied up.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44758
diff changeset
1277
44758
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1278 class ConnInfo:
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1279 """
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1280 An example class which shows how an arbitrary class can be used as
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1281 the 'extra' context information repository passed to a LoggerAdapter.
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1282 """
44849
32412fceb1b3 Minor documentation change - hyperlink tidied up.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44758
diff changeset
1283
44758
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1284 def __getitem__(self, name):
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1285 """
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1286 To allow this instance to look like a dict.
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1287 """
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1288 from random import choice
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1289 if name == "ip":
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1290 result = choice(["127.0.0.1", "192.168.0.1"])
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1291 elif name == "user":
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1292 result = choice(["jim", "fred", "sheila"])
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1293 else:
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1294 result = self.__dict__.get(name, "?")
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1295 return result
44849
32412fceb1b3 Minor documentation change - hyperlink tidied up.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44758
diff changeset
1296
44758
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1297 def __iter__(self):
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1298 """
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1299 To allow iteration over keys, which will be merged into
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1300 the LogRecord dict before formatting and output.
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1301 """
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1302 keys = ["ip", "user"]
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1303 keys.extend(self.__dict__.keys())
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1304 return keys.__iter__()
44849
32412fceb1b3 Minor documentation change - hyperlink tidied up.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44758
diff changeset
1305
44758
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1306 if __name__ == "__main__":
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1307 from random import choice
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1308 levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1309 a1 = logging.LoggerAdapter(logging.getLogger("a.b.c"),
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1310 { "ip" : "123.231.231.123", "user" : "sheila" })
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1311 logging.basicConfig(level=logging.DEBUG,
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1312 format="%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s")
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1313 a1.debug("A debug message")
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1314 a1.info("An info message with %s", "some parameters")
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1315 a2 = logging.LoggerAdapter(logging.getLogger("d.e.f"), ConnInfo())
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1316 for x in range(10):
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1317 lvl = choice(levels)
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1318 lvlname = logging.getLevelName(lvl)
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1319 a2.log(lvl, "A message at %s level with %d %s", lvlname, 2, "parameters")
44744
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1320
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1321 When this script is run, the output should look something like this::
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1322
44758
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1323 2008-01-18 14:49:54,023 a.b.c DEBUG IP: 123.231.231.123 User: sheila A debug message
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1324 2008-01-18 14:49:54,023 a.b.c INFO IP: 123.231.231.123 User: sheila An info message with some parameters
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1325 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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1326 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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1327 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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1328 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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1329 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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1330 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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1331 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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1332 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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
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
febde3caf291 Fix markup.
Georg Brandl <georg@python.org>
parents: 44744
diff changeset
1334 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
44744
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1335
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1336 .. versionadded:: 2.6
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1337
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1338 The :class:`LoggerAdapter` class was not present in previous versions.
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
1339
44580
e9756266e0b9 Added section about adding contextual information to log output.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44560
diff changeset
1340
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1341 .. _network-logging:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1342
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1343 Sending and receiving logging events across a network
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1344 -----------------------------------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1345
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1346 Let's say you want to send logging events across a network, and handle them at
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1347 the receiving end. A simple way of doing this is attaching a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1348 :class:`SocketHandler` instance to the root logger at the sending end::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1349
51745
9815da43a1ce revert r69777 since all the experts agree that extra import lines distract from the code
Benjamin Peterson <benjamin@python.org>
parents: 51742
diff changeset
1350 import logging, logging.handlers
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1351
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1352 rootLogger = logging.getLogger('')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1353 rootLogger.setLevel(logging.DEBUG)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1354 socketHandler = logging.handlers.SocketHandler('localhost',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1355 logging.handlers.DEFAULT_TCP_LOGGING_PORT)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1356 # don't bother with a formatter, since a socket handler sends the event as
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1357 # an unformatted pickle
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1358 rootLogger.addHandler(socketHandler)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1359
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1360 # Now, we can log to the root logger, or any other logger. First the root...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1361 logging.info('Jackdaws love my big sphinx of quartz.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1362
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1363 # Now, define a couple of other loggers which might represent areas in your
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1364 # application:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1365
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1366 logger1 = logging.getLogger('myapp.area1')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1367 logger2 = logging.getLogger('myapp.area2')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1368
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1369 logger1.debug('Quick zephyrs blow, vexing daft Jim.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1370 logger1.info('How quickly daft jumping zebras vex.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1371 logger2.warning('Jail zesty vixen who grabbed pay from quack.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1372 logger2.error('The five boxing wizards jump quickly.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1373
47241
ba1fa511b72d socketserver renaming reversal part 3: move the module into the right
Georg Brandl <georg@python.org>
parents: 47009
diff changeset
1374 At the receiving end, you can set up a receiver using the :mod:`SocketServer`
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1375 module. Here is a basic working example::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1376
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1377 import cPickle
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1378 import logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1379 import logging.handlers
47241
ba1fa511b72d socketserver renaming reversal part 3: move the module into the right
Georg Brandl <georg@python.org>
parents: 47009
diff changeset
1380 import SocketServer
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1381 import struct
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1382
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1383
47241
ba1fa511b72d socketserver renaming reversal part 3: move the module into the right
Georg Brandl <georg@python.org>
parents: 47009
diff changeset
1384 class LogRecordStreamHandler(SocketServer.StreamRequestHandler):
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1385 """Handler for a streaming logging request.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1386
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1387 This basically logs the record using whatever logging policy is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1388 configured locally.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1389 """
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1390
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1391 def handle(self):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1392 """
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1393 Handle multiple requests - each expected to be a 4-byte length,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1394 followed by the LogRecord in pickle format. Logs the record
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1395 according to whatever policy is configured locally.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1396 """
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1397 while 1:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1398 chunk = self.connection.recv(4)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1399 if len(chunk) < 4:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1400 break
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1401 slen = struct.unpack(">L", chunk)[0]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1402 chunk = self.connection.recv(slen)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1403 while len(chunk) < slen:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1404 chunk = chunk + self.connection.recv(slen - len(chunk))
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1405 obj = self.unPickle(chunk)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1406 record = logging.makeLogRecord(obj)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1407 self.handleLogRecord(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1408
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1409 def unPickle(self, data):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1410 return cPickle.loads(data)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1411
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1412 def handleLogRecord(self, record):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1413 # if a name is specified, we use the named logger rather than the one
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1414 # implied by the record.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1415 if self.server.logname is not None:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1416 name = self.server.logname
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1417 else:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1418 name = record.name
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1419 logger = logging.getLogger(name)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1420 # N.B. EVERY record gets logged. This is because Logger.handle
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1421 # is normally called AFTER logger-level filtering. If you want
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1422 # to do filtering, do it at the client end to save wasting
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1423 # cycles and network bandwidth!
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1424 logger.handle(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1425
47241
ba1fa511b72d socketserver renaming reversal part 3: move the module into the right
Georg Brandl <georg@python.org>
parents: 47009
diff changeset
1426 class LogRecordSocketReceiver(SocketServer.ThreadingTCPServer):
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1427 """simple TCP socket-based logging receiver suitable for testing.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1428 """
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1429
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1430 allow_reuse_address = 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1431
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1432 def __init__(self, host='localhost',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1433 port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1434 handler=LogRecordStreamHandler):
47241
ba1fa511b72d socketserver renaming reversal part 3: move the module into the right
Georg Brandl <georg@python.org>
parents: 47009
diff changeset
1435 SocketServer.ThreadingTCPServer.__init__(self, (host, port), handler)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1436 self.abort = 0
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1437 self.timeout = 1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1438 self.logname = None
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1439
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1440 def serve_until_stopped(self):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1441 import select
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1442 abort = 0
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1443 while not abort:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1444 rd, wr, ex = select.select([self.socket.fileno()],
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1445 [], [],
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1446 self.timeout)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1447 if rd:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1448 self.handle_request()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1449 abort = self.abort
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1450
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1451 def main():
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1452 logging.basicConfig(
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1453 format="%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s")
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1454 tcpserver = LogRecordSocketReceiver()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1455 print "About to start TCP server..."
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1456 tcpserver.serve_until_stopped()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1457
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1458 if __name__ == "__main__":
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1459 main()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1460
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1461 First run the server, and then the client. On the client side, nothing is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1462 printed on the console; on the server side, you should see something like::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1463
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1464 About to start TCP server...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1465 59 root INFO Jackdaws love my big sphinx of quartz.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1466 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1467 69 myapp.area1 INFO How quickly daft jumping zebras vex.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1468 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1469 69 myapp.area2 ERROR The five boxing wizards jump quickly.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1470
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1471
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1472 .. _handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1473
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1474 Handler Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1475 ---------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1476
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1477 Handlers have the following attributes and methods. Note that :class:`Handler`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1478 is never instantiated directly; this class acts as a base for more useful
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1479 subclasses. However, the :meth:`__init__` method in subclasses needs to call
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1480 :meth:`Handler.__init__`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1481
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1482
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1483 .. method:: Handler.__init__(level=NOTSET)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1484
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1485 Initializes the :class:`Handler` instance by setting its level, setting the list
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1486 of filters to the empty list and creating a lock (using :meth:`createLock`) for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1487 serializing access to an I/O mechanism.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1488
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1489
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1490 .. method:: Handler.createLock()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1491
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1492 Initializes a thread lock which can be used to serialize access to underlying
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1493 I/O functionality which may not be threadsafe.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1494
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1495
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1496 .. method:: Handler.acquire()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1497
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1498 Acquires the thread lock created with :meth:`createLock`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1499
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1500
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1501 .. method:: Handler.release()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1502
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1503 Releases the thread lock acquired with :meth:`acquire`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1504
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1505
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1506 .. method:: Handler.setLevel(lvl)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1507
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1508 Sets the threshold for this handler to *lvl*. Logging messages which are less
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1509 severe than *lvl* will be ignored. When a handler is created, the level is set
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1510 to :const:`NOTSET` (which causes all messages to be processed).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1511
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1513 .. method:: Handler.setFormatter(form)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1514
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1515 Sets the :class:`Formatter` for this handler to *form*.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1516
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1517
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1518 .. method:: Handler.addFilter(filt)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1519
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1520 Adds the specified filter *filt* to this handler.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1521
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1522
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1523 .. method:: Handler.removeFilter(filt)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1524
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1525 Removes the specified filter *filt* from this handler.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1526
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1527
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1528 .. method:: Handler.filter(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1529
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1530 Applies this handler's filters to the record and returns a true value if the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1531 record is to be processed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1532
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1533
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1534 .. method:: Handler.flush()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1535
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1536 Ensure all logging output has been flushed. This version does nothing and is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1537 intended to be implemented by subclasses.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1538
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1539
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1540 .. method:: Handler.close()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1541
48934
37a9f690a94a Bug #3738: Documentation is now more accurate in describing handler close methods.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48927
diff changeset
1542 Tidy up any resources used by the handler. This version does no output but
37a9f690a94a Bug #3738: Documentation is now more accurate in describing handler close methods.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48927
diff changeset
1543 removes the handler from an internal list of handlers which is closed when
37a9f690a94a Bug #3738: Documentation is now more accurate in describing handler close methods.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48927
diff changeset
1544 :func:`shutdown` is called. Subclasses should ensure that this gets called
37a9f690a94a Bug #3738: Documentation is now more accurate in describing handler close methods.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48927
diff changeset
1545 from overridden :meth:`close` methods.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1546
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1547
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1548 .. method:: Handler.handle(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1549
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1550 Conditionally emits the specified logging record, depending on filters which may
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1551 have been added to the handler. Wraps the actual emission of the record with
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1552 acquisition/release of the I/O thread lock.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1553
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1554
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1555 .. method:: Handler.handleError(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1556
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1557 This method should be called from handlers when an exception is encountered
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1558 during an :meth:`emit` call. By default it does nothing, which means that
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1559 exceptions get silently ignored. This is what is mostly wanted for a logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1560 system - most users will not care about errors in the logging system, they are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1561 more interested in application errors. You could, however, replace this with a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1562 custom handler if you wish. The specified record is the one which was being
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1563 processed when the exception occurred.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1564
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1565
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1566 .. method:: Handler.format(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1567
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1568 Do formatting for a record - if a formatter is set, use it. Otherwise, use the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1569 default formatter for the module.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1570
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1571
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1572 .. method:: Handler.emit(record)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1573
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1574 Do whatever it takes to actually log the specified logging record. This version
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1575 is intended to be implemented by subclasses and so raises a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1576 :exc:`NotImplementedError`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1577
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1578
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1579 .. _stream-handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1580
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1581 StreamHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1582 ^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1583
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1584 The :class:`StreamHandler` class, located in the core :mod:`logging` package,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1585 sends logging output to streams such as *sys.stdout*, *sys.stderr* or any
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1586 file-like object (or, more precisely, any object which supports :meth:`write`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1587 and :meth:`flush` methods).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1588
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1589
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1590 .. class:: StreamHandler([strm])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1591
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1592 Returns a new instance of the :class:`StreamHandler` class. If *strm* is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1593 specified, the instance will use it for logging output; otherwise, *sys.stderr*
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1594 will be used.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1595
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1596
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1597 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1598
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1599 If a formatter is specified, it is used to format the record. The record
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1600 is then written to the stream with a trailing newline. If exception
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1601 information is present, it is formatted using
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1602 :func:`traceback.print_exception` and appended to the stream.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1603
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1604
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1605 .. method:: flush()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1606
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1607 Flushes the stream by calling its :meth:`flush` method. Note that the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1608 :meth:`close` method is inherited from :class:`Handler` and so does
48934
37a9f690a94a Bug #3738: Documentation is now more accurate in describing handler close methods.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48927
diff changeset
1609 no output, so an explicit :meth:`flush` call may be needed at times.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1610
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1611
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1612 .. _file-handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1613
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1614 FileHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1615 ^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1616
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1617 The :class:`FileHandler` class, located in the core :mod:`logging` package,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1618 sends logging output to a disk file. It inherits the output functionality from
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1619 :class:`StreamHandler`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1620
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1621
44909
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1622 .. class:: FileHandler(filename[, mode[, encoding[, delay]]])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1623
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1624 Returns a new instance of the :class:`FileHandler` class. The specified file is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1625 opened and used as the stream for logging. If *mode* is not specified,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1626 :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file
44909
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1627 with that encoding. If *delay* is true, then file opening is deferred until the
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1628 first call to :meth:`emit`. By default, the file grows indefinitely.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1629
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1630
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1631 .. method:: close()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1632
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1633 Closes the file.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1634
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1635
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1636 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1637
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1638 Outputs the record to the file.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1639
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1640 .. _null-handler:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1641
50455
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1642 NullHandler
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1643 ^^^^^^^^^^^
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1644
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1645 .. versionadded:: 2.7
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1646
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1647 The :class:`NullHandler` class, located in the core :mod:`logging` package,
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1648 does not do any formatting or output. It is essentially a "no-op" handler
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1649 for use by library developers.
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1650
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1651
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1652 .. class:: NullHandler()
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1653
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1654 Returns a new instance of the :class:`NullHandler` class.
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1655
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1656
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1657 .. method:: emit(record)
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1658
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1659 This method does nothing.
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1660
50694
dbe39ebd3025 Minor documentation changes cross-referencing NullHandler to the documentation on configuring logging in a library.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50455
diff changeset
1661 See :ref:`library-config` for more information on how to use
dbe39ebd3025 Minor documentation changes cross-referencing NullHandler to the documentation on configuring logging in a library.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50455
diff changeset
1662 :class:`NullHandler`.
dbe39ebd3025 Minor documentation changes cross-referencing NullHandler to the documentation on configuring logging in a library.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50455
diff changeset
1663
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1664 .. _watched-file-handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1665
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1666 WatchedFileHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1667 ^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1668
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1669 .. versionadded:: 2.6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1670
50808
2680a4beaea1 Minor changes/corrections in markup.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50807
diff changeset
1671 .. currentmodule:: logging.handlers
50455
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
1672
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1673 The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1674 module, is a :class:`FileHandler` which watches the file it is logging to. If
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1675 the file changes, it is closed and reopened using the file name.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1676
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1677 A file change can happen because of usage of programs such as *newsyslog* and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1678 *logrotate* which perform log file rotation. This handler, intended for use
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1679 under Unix/Linux, watches the file to see if it has changed since the last emit.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1680 (A file is deemed to have changed if its device or inode have changed.) If the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1681 file has changed, the old file stream is closed, and the file opened to get a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1682 new stream.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1683
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1684 This handler is not appropriate for use under Windows, because under Windows
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1685 open log files cannot be moved or renamed - logging opens the files with
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1686 exclusive locks - and so there is no need for such a handler. Furthermore,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1687 *ST_INO* is not supported under Windows; :func:`stat` always returns zero for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1688 this value.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1689
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1690
44909
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1691 .. class:: WatchedFileHandler(filename[,mode[, encoding[, delay]]])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1692
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1693 Returns a new instance of the :class:`WatchedFileHandler` class. The specified
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1694 file is opened and used as the stream for logging. If *mode* is not specified,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1695 :const:`'a'` is used. If *encoding* is not *None*, it is used to open the file
44909
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1696 with that encoding. If *delay* is true, then file opening is deferred until the
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1697 first call to :meth:`emit`. By default, the file grows indefinitely.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1698
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1699
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1700 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1701
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1702 Outputs the record to the file, but first checks to see if the file has
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1703 changed. If it has, the existing stream is flushed and closed and the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1704 file opened again, before outputting the record to the file.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1705
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1706 .. _rotating-file-handler:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1707
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1708 RotatingFileHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1709 ^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1710
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1711 The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1712 module, supports rotation of disk log files.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1713
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1714
44909
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1715 .. class:: RotatingFileHandler(filename[, mode[, maxBytes[, backupCount[, encoding[, delay]]]]])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1716
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1717 Returns a new instance of the :class:`RotatingFileHandler` class. The specified
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1718 file is opened and used as the stream for logging. If *mode* is not specified,
44909
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1719 ``'a'`` is used. If *encoding* is not *None*, it is used to open the file
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1720 with that encoding. If *delay* is true, then file opening is deferred until the
cba3084b27e7 Added documentation for optional delay argument to FileHandler and subclasses.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44849
diff changeset
1721 first call to :meth:`emit`. By default, the file grows indefinitely.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1722
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1723 You can use the *maxBytes* and *backupCount* values to allow the file to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1724 :dfn:`rollover` at a predetermined size. When the size is about to be exceeded,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1725 the file is closed and a new file is silently opened for output. Rollover occurs
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1726 whenever the current log file is nearly *maxBytes* in length; if *maxBytes* is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1727 zero, rollover never occurs. If *backupCount* is non-zero, the system will save
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1728 old log files by appending the extensions ".1", ".2" etc., to the filename. For
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1729 example, with a *backupCount* of 5 and a base file name of :file:`app.log`, you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1730 would get :file:`app.log`, :file:`app.log.1`, :file:`app.log.2`, up to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1731 :file:`app.log.5`. The file being written to is always :file:`app.log`. When
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1732 this file is filled, it is closed and renamed to :file:`app.log.1`, and if files
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1733 :file:`app.log.1`, :file:`app.log.2`, etc. exist, then they are renamed to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1734 :file:`app.log.2`, :file:`app.log.3` etc. respectively.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1735
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1736
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1737 .. method:: doRollover()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1738
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1739 Does a rollover, as described above.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1740
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1741
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1742 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1743
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1744 Outputs the record to the file, catering for rollover as described
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1745 previously.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1746
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1747 .. _timed-rotating-file-handler:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1748
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1749 TimedRotatingFileHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1750 ^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1751
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1752 The :class:`TimedRotatingFileHandler` class, located in the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1753 :mod:`logging.handlers` module, supports rotation of disk log files at certain
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1754 timed intervals.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1755
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1756
47482
b55309ef54c7 Document 'utc' parameter
Andrew M. Kuchling <amk@amk.ca>
parents: 47252
diff changeset
1757 .. class:: TimedRotatingFileHandler(filename [,when [,interval [,backupCount[, encoding[, delay[, utc]]]]]])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1758
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1759 Returns a new instance of the :class:`TimedRotatingFileHandler` class. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1760 specified file is opened and used as the stream for logging. On rotating it also
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1761 sets the filename suffix. Rotating happens based on the product of *when* and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1762 *interval*.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1763
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1764 You can use the *when* to specify the type of *interval*. The list of possible
47487
7880a4277158 Markup fix.
Georg Brandl <georg@python.org>
parents: 47482
diff changeset
1765 values is below. Note that they are not case sensitive.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1766
45610
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1767 +----------------+-----------------------+
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1768 | Value | Type of interval |
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1769 +================+=======================+
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1770 | ``'S'`` | Seconds |
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1771 +----------------+-----------------------+
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1772 | ``'M'`` | Minutes |
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1773 +----------------+-----------------------+
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1774 | ``'H'`` | Hours |
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1775 +----------------+-----------------------+
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1776 | ``'D'`` | Days |
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1777 +----------------+-----------------------+
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1778 | ``'W'`` | Week day (0=Monday) |
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1779 +----------------+-----------------------+
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1780 | ``'midnight'`` | Roll over at midnight |
0a8eecac5ad1 Make clear that the constants are strings.
Georg Brandl <georg@python.org>
parents: 45512
diff changeset
1781 +----------------+-----------------------+
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1782
45611
f653c0b8916b Fix factual error.
Georg Brandl <georg@python.org>
parents: 45610
diff changeset
1783 The system will save old log files by appending extensions to the filename.
f653c0b8916b Fix factual error.
Georg Brandl <georg@python.org>
parents: 45610
diff changeset
1784 The extensions are date-and-time based, using the strftime format
46258
a94469c74b9e Added updates with respect to recent changes to TimedRotatingFileHandler.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 45783
diff changeset
1785 ``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on the
48011
1acfe428e8f1 Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 47487
diff changeset
1786 rollover interval.
47487
7880a4277158 Markup fix.
Georg Brandl <georg@python.org>
parents: 47482
diff changeset
1787 If the *utc* argument is true, times in UTC will be used; otherwise
47482
b55309ef54c7 Document 'utc' parameter
Andrew M. Kuchling <amk@amk.ca>
parents: 47252
diff changeset
1788 local time is used.
b55309ef54c7 Document 'utc' parameter
Andrew M. Kuchling <amk@amk.ca>
parents: 47252
diff changeset
1789
b55309ef54c7 Document 'utc' parameter
Andrew M. Kuchling <amk@amk.ca>
parents: 47252
diff changeset
1790 If *backupCount* is nonzero, at most *backupCount* files
46258
a94469c74b9e Added updates with respect to recent changes to TimedRotatingFileHandler.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 45783
diff changeset
1791 will be kept, and if more would be created when rollover occurs, the oldest
a94469c74b9e Added updates with respect to recent changes to TimedRotatingFileHandler.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 45783
diff changeset
1792 one is deleted. The deletion logic uses the interval to determine which
a94469c74b9e Added updates with respect to recent changes to TimedRotatingFileHandler.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 45783
diff changeset
1793 files to delete, so changing the interval may leave old files lying around.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1794
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1795
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1796 .. method:: doRollover()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1797
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1798 Does a rollover, as described above.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1799
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1800
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1801 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1802
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1803 Outputs the record to the file, catering for rollover as described above.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1804
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1805
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1806 .. _socket-handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1807
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1808 SocketHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1809 ^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1810
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1811 The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1812 sends logging output to a network socket. The base class uses a TCP socket.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1813
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1814
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1815 .. class:: SocketHandler(host, port)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1816
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1817 Returns a new instance of the :class:`SocketHandler` class intended to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1818 communicate with a remote machine whose address is given by *host* and *port*.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1819
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1820
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1821 .. method:: close()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1822
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1823 Closes the socket.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1824
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1825
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1826 .. method:: emit()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1827
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1828 Pickles the record's attribute dictionary and writes it to the socket in
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1829 binary format. If there is an error with the socket, silently drops the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1830 packet. If the connection was previously lost, re-establishes the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1831 connection. To unpickle the record at the receiving end into a
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1832 :class:`LogRecord`, use the :func:`makeLogRecord` function.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1833
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1834
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1835 .. method:: handleError()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1836
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1837 Handles an error which has occurred during :meth:`emit`. The most likely
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1838 cause is a lost connection. Closes the socket so that we can retry on the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1839 next event.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1840
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1841
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1842 .. method:: makeSocket()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1843
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1844 This is a factory method which allows subclasses to define the precise
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1845 type of socket they want. The default implementation creates a TCP socket
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1846 (:const:`socket.SOCK_STREAM`).
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1847
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1848
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1849 .. method:: makePickle(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1850
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1851 Pickles the record's attribute dictionary in binary format with a length
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1852 prefix, and returns it ready for transmission across the socket.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1853
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1854
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1855 .. method:: send(packet)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1856
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1857 Send a pickled string *packet* to the socket. This function allows for
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1858 partial sends which can happen when the network is busy.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1859
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1860
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1861 .. _datagram-handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1862
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1863 DatagramHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1864 ^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1865
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1866 The :class:`DatagramHandler` class, located in the :mod:`logging.handlers`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1867 module, inherits from :class:`SocketHandler` to support sending logging messages
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1868 over UDP sockets.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1869
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1870
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1871 .. class:: DatagramHandler(host, port)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1872
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1873 Returns a new instance of the :class:`DatagramHandler` class intended to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1874 communicate with a remote machine whose address is given by *host* and *port*.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1875
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1876
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1877 .. method:: emit()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1878
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1879 Pickles the record's attribute dictionary and writes it to the socket in
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1880 binary format. If there is an error with the socket, silently drops the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1881 packet. To unpickle the record at the receiving end into a
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1882 :class:`LogRecord`, use the :func:`makeLogRecord` function.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1883
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1884
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1885 .. method:: makeSocket()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1886
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1887 The factory method of :class:`SocketHandler` is here overridden to create
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1888 a UDP socket (:const:`socket.SOCK_DGRAM`).
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1889
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1890
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1891 .. method:: send(s)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1892
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1893 Send a pickled string to a socket.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1894
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1895
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1896 .. _syslog-handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1897
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1898 SysLogHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1899 ^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1900
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1901 The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1902 supports sending logging messages to a remote or local Unix syslog.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1903
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1904
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1905 .. class:: SysLogHandler([address[, facility]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1906
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1907 Returns a new instance of the :class:`SysLogHandler` class intended to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1908 communicate with a remote Unix machine whose address is given by *address* in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1909 the form of a ``(host, port)`` tuple. If *address* is not specified,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1910 ``('localhost', 514)`` is used. The address is used to open a UDP socket. An
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1911 alternative to providing a ``(host, port)`` tuple is providing an address as a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1912 string, for example "/dev/log". In this case, a Unix domain socket is used to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1913 send the message to the syslog. If *facility* is not specified,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1914 :const:`LOG_USER` is used.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1915
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1916
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1917 .. method:: close()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1918
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1919 Closes the socket to the remote host.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1920
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1921
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1922 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1923
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1924 The record is formatted, and then sent to the syslog server. If exception
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1925 information is present, it is *not* sent to the server.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1926
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1927
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1928 .. method:: encodePriority(facility, priority)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1929
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1930 Encodes the facility and priority into an integer. You can pass in strings
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1931 or integers - if strings are passed, internal mapping dictionaries are
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1932 used to convert them to integers.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1933
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1934
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1935 .. _nt-eventlog-handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
1936
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1937 NTEventLogHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1938 ^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1939
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1940 The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1941 module, supports sending logging messages to a local Windows NT, Windows 2000 or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1942 Windows XP event log. Before you can use it, you need Mark Hammond's Win32
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1943 extensions for Python installed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1944
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1945
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1946 .. class:: NTEventLogHandler(appname[, dllname[, logtype]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1947
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1948 Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1949 used to define the application name as it appears in the event log. An
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1950 appropriate registry entry is created using this name. The *dllname* should give
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1951 the fully qualified pathname of a .dll or .exe which contains message
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1952 definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1953 - this is installed with the Win32 extensions and contains some basic
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1954 placeholder message definitions. Note that use of these placeholders will make
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1955 your event logs big, as the entire message source is held in the log. If you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1956 want slimmer logs, you have to pass in the name of your own .dll or .exe which
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1957 contains the message definitions you want to use in the event log). The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1958 *logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1959 defaults to ``'Application'``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1960
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1961
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1962 .. method:: close()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1963
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1964 At this point, you can remove the application name from the registry as a
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1965 source of event log entries. However, if you do this, you will not be able
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1966 to see the events as you intended in the Event Log Viewer - it needs to be
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1967 able to access the registry to get the .dll name. The current version does
48934
37a9f690a94a Bug #3738: Documentation is now more accurate in describing handler close methods.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 48927
diff changeset
1968 not do this.
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1969
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1970
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1971 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1972
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1973 Determines the message ID, event category and event type, and then logs
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1974 the message in the NT event log.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1975
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1976
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1977 .. method:: getEventCategory(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1978
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1979 Returns the event category for the record. Override this if you want to
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1980 specify your own categories. This version returns 0.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1981
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1982
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1983 .. method:: getEventType(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1984
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1985 Returns the event type for the record. Override this if you want to
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1986 specify your own types. This version does a mapping using the handler's
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1987 typemap attribute, which is set up in :meth:`__init__` to a dictionary
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1988 which contains mappings for :const:`DEBUG`, :const:`INFO`,
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1989 :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1990 your own levels, you will either need to override this method or place a
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1991 suitable dictionary in the handler's *typemap* attribute.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1992
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1993
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1994 .. method:: getMessageID(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1995
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1996 Returns the message ID for the record. If you are using your own messages,
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1997 you could do this by having the *msg* passed to the logger being an ID
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1998 rather than a format string. Then, in here, you could use a dictionary
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
1999 lookup to get the message ID. This version returns 1, which is the base
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2000 message ID in :file:`win32service.pyd`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2001
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2002 .. _smtp-handler:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2003
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2004 SMTPHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2005 ^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2006
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2007 The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2008 supports sending logging messages to an email address via SMTP.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2009
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2010
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2011 .. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject[, credentials])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2012
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2013 Returns a new instance of the :class:`SMTPHandler` class. The instance is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2014 initialized with the from and to addresses and subject line of the email. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2015 *toaddrs* should be a list of strings. To specify a non-standard SMTP port, use
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2016 the (host, port) tuple format for the *mailhost* argument. If you use a string,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2017 the standard SMTP port is used. If your SMTP server requires authentication, you
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2018 can specify a (username, password) tuple for the *credentials* argument.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2019
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2020 .. versionchanged:: 2.6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2021 *credentials* was added.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2022
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2023
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2024 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2025
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2026 Formats the record and sends it to the specified addressees.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2027
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2028
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2029 .. method:: getSubject(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2030
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2031 If you want to specify a subject line which is record-dependent, override
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2032 this method.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2033
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2034 .. _memory-handler:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2035
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2036 MemoryHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2037 ^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2038
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2039 The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2040 supports buffering of logging records in memory, periodically flushing them to a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2041 :dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2042 event of a certain severity or greater is seen.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2043
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2044 :class:`MemoryHandler` is a subclass of the more general
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2045 :class:`BufferingHandler`, which is an abstract class. This buffers logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2046 records in memory. Whenever each record is added to the buffer, a check is made
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2047 by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2048 should, then :meth:`flush` is expected to do the needful.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2049
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2050
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2051 .. class:: BufferingHandler(capacity)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2052
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2053 Initializes the handler with a buffer of the specified capacity.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2054
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2055
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2056 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2057
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2058 Appends the record to the buffer. If :meth:`shouldFlush` returns true,
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2059 calls :meth:`flush` to process the buffer.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2060
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2061
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2062 .. method:: flush()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2063
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2064 You can override this to implement custom flushing behavior. This version
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2065 just zaps the buffer to empty.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2066
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2067
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2068 .. method:: shouldFlush(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2069
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2070 Returns true if the buffer is up to capacity. This method can be
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2071 overridden to implement custom flushing strategies.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2072
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2073
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2074 .. class:: MemoryHandler(capacity[, flushLevel [, target]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2075
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2076 Returns a new instance of the :class:`MemoryHandler` class. The instance is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2077 initialized with a buffer size of *capacity*. If *flushLevel* is not specified,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2078 :const:`ERROR` is used. If no *target* is specified, the target will need to be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2079 set using :meth:`setTarget` before this handler does anything useful.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2080
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2081
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2082 .. method:: close()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2083
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2084 Calls :meth:`flush`, sets the target to :const:`None` and clears the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2085 buffer.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2086
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2087
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2088 .. method:: flush()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2089
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2090 For a :class:`MemoryHandler`, flushing means just sending the buffered
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2091 records to the target, if there is one. Override if you want different
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2092 behavior.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2093
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2094
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2095 .. method:: setTarget(target)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2096
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2097 Sets the target handler for this handler.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2098
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2099
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2100 .. method:: shouldFlush(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2101
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2102 Checks for buffer full or a record at the *flushLevel* or higher.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2103
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2104
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2105 .. _http-handler:
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2106
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2107 HTTPHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2108 ^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2109
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2110 The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2111 supports sending logging messages to a Web server, using either ``GET`` or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2112 ``POST`` semantics.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2113
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2114
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2115 .. class:: HTTPHandler(host, url[, method])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2116
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2117 Returns a new instance of the :class:`HTTPHandler` class. The instance is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2118 initialized with a host address, url and HTTP method. The *host* can be of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2119 form ``host:port``, should you need to use a specific port number. If no
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2120 *method* is specified, ``GET`` is used.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2121
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2122
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2123 .. method:: emit(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2124
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2125 Sends the record to the Web server as an URL-encoded dictionary.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2126
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2127
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2128 .. _formatter:
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2129
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2130 Formatter Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2131 -----------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2132
50415
e5dbf38b1dac Handlers are in the `logging.handlers` module.
Georg Brandl <georg@python.org>
parents: 50371
diff changeset
2133 .. currentmodule:: logging
e5dbf38b1dac Handlers are in the `logging.handlers` module.
Georg Brandl <georg@python.org>
parents: 50371
diff changeset
2134
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2135 :class:`Formatter`\ s have the following attributes and methods. They are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2136 responsible for converting a :class:`LogRecord` to (usually) a string which can
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2137 be interpreted by either a human or an external system. The base
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2138 :class:`Formatter` allows a formatting string to be specified. If none is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2139 supplied, the default value of ``'%(message)s'`` is used.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2140
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2141 A Formatter can be initialized with a format string which makes use of knowledge
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2142 of the :class:`LogRecord` attributes - such as the default value mentioned above
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2143 making use of the fact that the user's message and arguments are pre-formatted
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2144 into a :class:`LogRecord`'s *message* attribute. This format string contains
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2145 standard python %-style mapping keys. See section :ref:`string-formatting`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2146 for more information on string formatting.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2147
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2148 Currently, the useful mapping keys in a :class:`LogRecord` are:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2149
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2150 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2151 | Format | Description |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2152 +=========================+===============================================+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2153 | ``%(name)s`` | Name of the logger (logging channel). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2154 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2155 | ``%(levelno)s`` | Numeric logging level for the message |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2156 | | (:const:`DEBUG`, :const:`INFO`, |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2157 | | :const:`WARNING`, :const:`ERROR`, |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2158 | | :const:`CRITICAL`). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2159 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2160 | ``%(levelname)s`` | Text logging level for the message |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2161 | | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2162 | | ``'ERROR'``, ``'CRITICAL'``). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2163 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2164 | ``%(pathname)s`` | Full pathname of the source file where the |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2165 | | logging call was issued (if available). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2166 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2167 | ``%(filename)s`` | Filename portion of pathname. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2168 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2169 | ``%(module)s`` | Module (name portion of filename). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2170 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2171 | ``%(funcName)s`` | Name of function containing the logging call. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2172 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2173 | ``%(lineno)d`` | Source line number where the logging call was |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2174 | | issued (if available). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2175 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2176 | ``%(created)f`` | Time when the :class:`LogRecord` was created |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2177 | | (as returned by :func:`time.time`). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2178 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2179 | ``%(relativeCreated)d`` | Time in milliseconds when the LogRecord was |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2180 | | created, relative to the time the logging |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2181 | | module was loaded. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2182 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2183 | ``%(asctime)s`` | Human-readable time when the |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2184 | | :class:`LogRecord` was created. By default |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2185 | | this is of the form "2003-07-08 16:49:45,896" |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2186 | | (the numbers after the comma are millisecond |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2187 | | portion of the time). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2188 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2189 | ``%(msecs)d`` | Millisecond portion of the time when the |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2190 | | :class:`LogRecord` was created. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2191 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2192 | ``%(thread)d`` | Thread ID (if available). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2193 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2194 | ``%(threadName)s`` | Thread name (if available). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2195 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2196 | ``%(process)d`` | Process ID (if available). |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2197 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2198 | ``%(message)s`` | The logged message, computed as ``msg % |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2199 | | args``. |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2200 +-------------------------+-----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2201
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2202 .. versionchanged:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2203 *funcName* was added.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2204
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2205
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2206 .. class:: Formatter([fmt[, datefmt]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2207
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2208 Returns a new instance of the :class:`Formatter` class. The instance is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2209 initialized with a format string for the message as a whole, as well as a format
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2210 string for the date/time portion of a message. If no *fmt* is specified,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2211 ``'%(message)s'`` is used. If no *datefmt* is specified, the ISO8601 date format
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2212 is used.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2213
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2214
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2215 .. method:: format(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2216
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2217 The record's attribute dictionary is used as the operand to a string
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2218 formatting operation. Returns the resulting string. Before formatting the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2219 dictionary, a couple of preparatory steps are carried out. The *message*
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2220 attribute of the record is computed using *msg* % *args*. If the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2221 formatting string contains ``'(asctime)'``, :meth:`formatTime` is called
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2222 to format the event time. If there is exception information, it is
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2223 formatted using :meth:`formatException` and appended to the message. Note
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2224 that the formatted exception information is cached in attribute
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2225 *exc_text*. This is useful because the exception information can be
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2226 pickled and sent across the wire, but you should be careful if you have
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2227 more than one :class:`Formatter` subclass which customizes the formatting
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2228 of exception information. In this case, you will have to clear the cached
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2229 value after a formatter has done its formatting, so that the next
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2230 formatter to handle the event doesn't use the cached value but
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2231 recalculates it afresh.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2232
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2233
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2234 .. method:: formatTime(record[, datefmt])
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2235
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2236 This method should be called from :meth:`format` by a formatter which
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2237 wants to make use of a formatted time. This method can be overridden in
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2238 formatters to provide for any specific requirement, but the basic behavior
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2239 is as follows: if *datefmt* (a string) is specified, it is used with
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2240 :func:`time.strftime` to format the creation time of the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2241 record. Otherwise, the ISO8601 format is used. The resulting string is
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2242 returned.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2243
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2244
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2245 .. method:: formatException(exc_info)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2246
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2247 Formats the specified exception information (a standard exception tuple as
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2248 returned by :func:`sys.exc_info`) as a string. This default implementation
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2249 just uses :func:`traceback.print_exception`. The resulting string is
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2250 returned.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2251
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2252 .. _filter:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2253
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2254 Filter Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2255 --------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2256
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2257 Filters can be used by :class:`Handler`\ s and :class:`Logger`\ s for
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2258 more sophisticated filtering than is provided by levels. The base filter class
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2259 only allows events which are below a certain point in the logger hierarchy. For
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2260 example, a filter initialized with "A.B" will allow events logged by loggers
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2261 "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB", "B.A.B" etc. If
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2262 initialized with the empty string, all events are passed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2263
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2264
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2265 .. class:: Filter([name])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2266
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2267 Returns an instance of the :class:`Filter` class. If *name* is specified, it
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2268 names a logger which, together with its children, will have its events allowed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2269 through the filter. If no name is specified, allows every event.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2270
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2271
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2272 .. method:: filter(record)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2273
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2274 Is the specified record to be logged? Returns zero for no, nonzero for
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2275 yes. If deemed appropriate, the record may be modified in-place by this
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2276 method.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2277
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2278 .. _log-record:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2279
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2280 LogRecord Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2281 -----------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2282
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2283 :class:`LogRecord` instances are created every time something is logged. They
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2284 contain all the information pertinent to the event being logged. The main
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2285 information passed in is in msg and args, which are combined using msg % args to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2286 create the message field of the record. The record also includes information
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2287 such as when the record was created, the source line where the logging call was
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2288 made, and any exception information to be logged.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2289
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2290
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2291 .. class:: LogRecord(name, lvl, pathname, lineno, msg, args, exc_info [, func])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2292
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2293 Returns an instance of :class:`LogRecord` initialized with interesting
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2294 information. The *name* is the logger name; *lvl* is the numeric level;
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2295 *pathname* is the absolute pathname of the source file in which the logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2296 call was made; *lineno* is the line number in that file where the logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2297 call is found; *msg* is the user-supplied message (a format string); *args*
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2298 is the tuple which, together with *msg*, makes up the user message; and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2299 *exc_info* is the exception tuple obtained by calling :func:`sys.exc_info`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2300 (or :const:`None`, if no exception information is available). The *func* is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2301 the name of the function from which the logging call was made. If not
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2302 specified, it defaults to ``None``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2303
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2304 .. versionchanged:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2305 *func* was added.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2306
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2307
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2308 .. method:: getMessage()
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2309
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2310 Returns the message for this :class:`LogRecord` instance after merging any
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2311 user-supplied arguments with the message.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2312
50892
a6611615c76b Added more cross-reference targets and tidied up list of useful handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50808
diff changeset
2313 .. _logger-adapter:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2314
44744
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2315 LoggerAdapter Objects
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2316 ---------------------
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2317
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2318 .. versionadded:: 2.6
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2319
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2320 :class:`LoggerAdapter` instances are used to conveniently pass contextual
44849
32412fceb1b3 Minor documentation change - hyperlink tidied up.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44758
diff changeset
2321 information into logging calls. For a usage example , see the section on
32412fceb1b3 Minor documentation change - hyperlink tidied up.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44758
diff changeset
2322 `adding contextual information to your logging output`__.
32412fceb1b3 Minor documentation change - hyperlink tidied up.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44758
diff changeset
2323
32412fceb1b3 Minor documentation change - hyperlink tidied up.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44758
diff changeset
2324 __ context-info_
44744
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2325
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2326 .. class:: LoggerAdapter(logger, extra)
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2327
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2328 Returns an instance of :class:`LoggerAdapter` initialized with an
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2329 underlying :class:`Logger` instance and a dict-like object.
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2330
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2331 .. method:: process(msg, kwargs)
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2332
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2333 Modifies the message and/or keyword arguments passed to a logging call in
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2334 order to insert contextual information. This implementation takes the object
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2335 passed as *extra* to the constructor and adds it to *kwargs* using key
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2336 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 46258
diff changeset
2337 (possibly modified) versions of the arguments passed in.
44744
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2338
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2339 In addition to the above, :class:`LoggerAdapter` supports all the logging
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2340 methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2341 :meth:`error`, :meth:`exception`, :meth:`critical` and :meth:`log`. These
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2342 methods have the same signatures as their counterparts in :class:`Logger`, so
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2343 you can use the two types of instances interchangeably.
d9833d2bf469 Added section on passing contextual information to logging and documentation for the LoggerAdapter class.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44580
diff changeset
2344
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2345
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2346 Thread Safety
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2347 -------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2348
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2349 The logging module is intended to be thread-safe without any special work
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2350 needing to be done by its clients. It achieves this though using threading
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2351 locks; there is one lock to serialize access to the module's shared data, and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2352 each handler also creates a lock to serialize access to its underlying I/O.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2353
52780
d19d890138f1 Clarified warning about logging use from asynchronous signal handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 52771
diff changeset
2354 If you are implementing asynchronous signal handlers using the :mod:`signal`
d19d890138f1 Clarified warning about logging use from asynchronous signal handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 52771
diff changeset
2355 module, you may not be able to use logging from within such handlers. This is
d19d890138f1 Clarified warning about logging use from asynchronous signal handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 52771
diff changeset
2356 because lock implementations in the :mod:`threading` module are not always
d19d890138f1 Clarified warning about logging use from asynchronous signal handlers.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 52771
diff changeset
2357 re-entrant, and so cannot be invoked from such signal handlers.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2358
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2359 Configuration
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2360 -------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2361
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2362
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2363 .. _logging-config-api:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2364
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2365 Configuration functions
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2366 ^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2367
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2368 The following functions configure the logging module. They are located in the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2369 :mod:`logging.config` module. Their use is optional --- you can configure the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2370 logging module using these functions or by making calls to the main API (defined
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2371 in :mod:`logging` itself) and defining handlers which are declared either in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2372 :mod:`logging` or :mod:`logging.handlers`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2373
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2374
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2375 .. function:: fileConfig(fname[, defaults])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2376
50455
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2377 Reads the logging configuration from a :mod:`ConfigParser`\-format file named
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2378 *fname*. This function can be called several times from an application,
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2379 allowing an end user the ability to select from various pre-canned
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2380 configurations (if the developer provides a mechanism to present the choices
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2381 and load the chosen configuration). Defaults to be passed to the ConfigParser
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2382 can be specified in the *defaults* argument.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2383
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2384
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2385 .. function:: listen([port])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2386
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2387 Starts up a socket server on the specified port, and listens for new
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2388 configurations. If no port is specified, the module's default
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2389 :const:`DEFAULT_LOGGING_CONFIG_PORT` is used. Logging configurations will be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2390 sent as a file suitable for processing by :func:`fileConfig`. Returns a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2391 :class:`Thread` instance on which you can call :meth:`start` to start the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2392 server, and which you can :meth:`join` when appropriate. To stop the server,
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2393 call :func:`stopListening`.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2394
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2395 To send a configuration to the socket, read in the configuration file and
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2396 send it to the socket as a string of bytes preceded by a four-byte length
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2397 string packed in binary using ``struct.pack('>L', n)``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2398
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2399
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2400 .. function:: stopListening()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2401
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2402 Stops the listening server which was created with a call to :func:`listen`.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2403 This is typically called before calling :meth:`join` on the return value from
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2404 :func:`listen`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2405
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2406
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2407 .. _logging-config-fileformat:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2408
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2409 Configuration file format
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2410 ^^^^^^^^^^^^^^^^^^^^^^^^^
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2411
47252
e534ee0a4cd0 ConfigParser renaming reversal part 3: move module into place and adapt imports.
Georg Brandl <georg@python.org>
parents: 47241
diff changeset
2412 The configuration file format understood by :func:`fileConfig` is based on
50455
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2413 :mod:`ConfigParser` functionality. The file must contain sections called
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2414 ``[loggers]``, ``[handlers]`` and ``[formatters]`` which identify by name the
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2415 entities of each type which are defined in the file. For each such entity,
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2416 there is a separate section which identifies how that entity is configured.
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2417 Thus, for a logger named ``log01`` in the ``[loggers]`` section, the relevant
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2418 configuration details are held in a section ``[logger_log01]``. Similarly, a
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2419 handler called ``hand01`` in the ``[handlers]`` section will have its
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2420 configuration held in a section called ``[handler_hand01]``, while a formatter
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2421 called ``form01`` in the ``[formatters]`` section will have its configuration
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2422 specified in a section called ``[formatter_form01]``. The root logger
ff106453254a Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 50415
diff changeset
2423 configuration must be specified in a section called ``[logger_root]``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2424
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2425 Examples of these sections in the file are given below. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2426
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2427 [loggers]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2428 keys=root,log02,log03,log04,log05,log06,log07
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2429
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2430 [handlers]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2431 keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2432
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2433 [formatters]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2434 keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2435
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2436 The root logger must specify a level and a list of handlers. An example of a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2437 root logger section is given below. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2438
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2439 [logger_root]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2440 level=NOTSET
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2441 handlers=hand01
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2442
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2443 The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2444 ``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2445 logged. Level values are :func:`eval`\ uated in the context of the ``logging``
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2446 package's namespace.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2447
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2448 The ``handlers`` entry is a comma-separated list of handler names, which must
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2449 appear in the ``[handlers]`` section. These names must appear in the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2450 ``[handlers]`` section and have corresponding sections in the configuration
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2451 file.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2452
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2453 For loggers other than the root logger, some additional information is required.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2454 This is illustrated by the following example. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2455
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2456 [logger_parser]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2457 level=DEBUG
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2458 handlers=hand01
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2459 propagate=1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2460 qualname=compiler.parser
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2461
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2462 The ``level`` and ``handlers`` entries are interpreted as for the root logger,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2463 except that if a non-root logger's level is specified as ``NOTSET``, the system
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2464 consults loggers higher up the hierarchy to determine the effective level of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2465 logger. The ``propagate`` entry is set to 1 to indicate that messages must
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2466 propagate to handlers higher up the logger hierarchy from this logger, or 0 to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2467 indicate that messages are **not** propagated to handlers up the hierarchy. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2468 ``qualname`` entry is the hierarchical channel name of the logger, that is to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2469 say the name used by the application to get the logger.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2470
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2471 Sections which specify handler configuration are exemplified by the following.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2472 ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2473
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2474 [handler_hand01]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2475 class=StreamHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2476 level=NOTSET
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2477 formatter=form01
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2478 args=(sys.stdout,)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2479
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2480 The ``class`` entry indicates the handler's class (as determined by :func:`eval`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2481 in the ``logging`` package's namespace). The ``level`` is interpreted as for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2482 loggers, and ``NOTSET`` is taken to mean "log everything".
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2483
48011
1acfe428e8f1 Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 47487
diff changeset
2484 .. versionchanged:: 2.6
1acfe428e8f1 Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 47487
diff changeset
2485 Added support for resolving the handler's class as a dotted module and class
1acfe428e8f1 Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 47487
diff changeset
2486 name.
1acfe428e8f1 Issue #3389: Allow resolving dotted names for handlers in logging configuration files. Thanks to Philip Jenvey for the patch.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 47487
diff changeset
2487
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2488 The ``formatter`` entry indicates the key name of the formatter for this
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2489 handler. If blank, a default formatter (``logging._defaultFormatter``) is used.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2490 If a name is specified, it must appear in the ``[formatters]`` section and have
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2491 a corresponding section in the configuration file.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2492
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2493 The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2494 package's namespace, is the list of arguments to the constructor for the handler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2495 class. Refer to the constructors for the relevant handlers, or to the examples
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2496 below, to see how typical entries are constructed. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2497
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2498 [handler_hand02]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2499 class=FileHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2500 level=DEBUG
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2501 formatter=form02
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2502 args=('python.log', 'w')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2503
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2504 [handler_hand03]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2505 class=handlers.SocketHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2506 level=INFO
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2507 formatter=form03
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2508 args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2509
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2510 [handler_hand04]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2511 class=handlers.DatagramHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2512 level=WARN
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2513 formatter=form04
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2514 args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2515
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2516 [handler_hand05]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2517 class=handlers.SysLogHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2518 level=ERROR
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2519 formatter=form05
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2520 args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2521
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2522 [handler_hand06]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2523 class=handlers.NTEventLogHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2524 level=CRITICAL
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2525 formatter=form06
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2526 args=('Python Application', '', 'Application')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2527
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2528 [handler_hand07]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2529 class=handlers.SMTPHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2530 level=WARN
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2531 formatter=form07
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2532 args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2533
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2534 [handler_hand08]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2535 class=handlers.MemoryHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2536 level=NOTSET
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2537 formatter=form08
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2538 target=
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2539 args=(10, ERROR)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2540
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2541 [handler_hand09]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2542 class=handlers.HTTPHandler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2543 level=NOTSET
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2544 formatter=form09
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2545 args=('localhost:9022', '/log', 'GET')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2546
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2547 Sections which specify formatter configuration are typified by the following. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2548
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2549 [formatter_form01]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2550 format=F1 %(asctime)s %(levelname)s %(message)s
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2551 datefmt=
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2552 class=logging.Formatter
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2553
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2554 The ``format`` entry is the overall format string, and the ``datefmt`` entry is
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44195
diff changeset
2555 the :func:`strftime`\ -compatible date/time format string. If empty, the
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44195
diff changeset
2556 package substitutes ISO8601 format date/times, which is almost equivalent to
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44195
diff changeset
2557 specifying the date format string ``"%Y-%m-%d %H:%M:%S"``. The ISO8601 format
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44195
diff changeset
2558 also specifies milliseconds, which are appended to the result of using the above
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44195
diff changeset
2559 format string, with a comma separator. An example time in ISO8601 format is
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 44195
diff changeset
2560 ``2003-01-23 00:29:50,411``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2561
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2562 The ``class`` entry is optional. It indicates the name of the formatter's class
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2563 (as a dotted module and class name.) This option is useful for instantiating a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2564 :class:`Formatter` subclass. Subclasses of :class:`Formatter` can present
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2565 exception tracebacks in an expanded or condensed format.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2566
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2567
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2568 Configuration server example
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2569 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2570
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2571 Here is an example of a module using the logging configuration server::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2572
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2573 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2574 import logging.config
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2575 import time
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2576 import os
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2577
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2578 # read initial config file
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2579 logging.config.fileConfig("logging.conf")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2580
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2581 # create and start listener on port 9999
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2582 t = logging.config.listen(9999)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2583 t.start()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2584
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2585 logger = logging.getLogger("simpleExample")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2586
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2587 try:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2588 # loop through logging calls to see the difference
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2589 # new configurations make, until Ctrl+C is pressed
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2590 while True:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2591 logger.debug("debug message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2592 logger.info("info message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2593 logger.warn("warn message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2594 logger.error("error message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2595 logger.critical("critical message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2596 time.sleep(5)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2597 except KeyboardInterrupt:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2598 # cleanup
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2599 logging.config.stopListening()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2600 t.join()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2601
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2602 And here is a script that takes a filename and sends that file to the server,
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2603 properly preceded with the binary-encoded length, as the new logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2604 configuration::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2605
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2606 #!/usr/bin/env python
51745
9815da43a1ce revert r69777 since all the experts agree that extra import lines distract from the code
Benjamin Peterson <benjamin@python.org>
parents: 51742
diff changeset
2607 import socket, sys, struct
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2608
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2609 data_to_send = open(sys.argv[1], "r").read()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2610
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2611 HOST = 'localhost'
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2612 PORT = 9999
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2613 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2614 print "connecting..."
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2615 s.connect((HOST, PORT))
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2616 print "sending config..."
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2617 s.send(struct.pack(">L", len(data_to_send)))
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2618 s.send(data_to_send)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2619 s.close()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2620 print "complete"
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2621
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2622
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2623 More examples
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2624 -------------
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2625
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2626 Multiple handlers and formatters
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2627 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2628
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2629 Loggers are plain Python objects. The :func:`addHandler` method has no minimum
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2630 or maximum quota for the number of handlers you may add. Sometimes it will be
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2631 beneficial for an application to log all messages of all severities to a text
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2632 file while simultaneously logging errors or above to the console. To set this
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2633 up, simply configure the appropriate handlers. The logging calls in the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2634 application code will remain unchanged. Here is a slight modification to the
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2635 previous simple module-based configuration example::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2636
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2637 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2638
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2639 logger = logging.getLogger("simple_example")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2640 logger.setLevel(logging.DEBUG)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2641 # create file handler which logs even debug messages
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2642 fh = logging.FileHandler("spam.log")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2643 fh.setLevel(logging.DEBUG)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2644 # create console handler with a higher log level
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2645 ch = logging.StreamHandler()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2646 ch.setLevel(logging.ERROR)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2647 # create formatter and add it to the handlers
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2648 formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2649 ch.setFormatter(formatter)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2650 fh.setFormatter(formatter)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2651 # add the handlers to logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2652 logger.addHandler(ch)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2653 logger.addHandler(fh)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2654
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2655 # "application" code
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2656 logger.debug("debug message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2657 logger.info("info message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2658 logger.warn("warn message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2659 logger.error("error message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2660 logger.critical("critical message")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2661
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2662 Notice that the "application" code does not care about multiple handlers. All
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2663 that changed was the addition and configuration of a new handler named *fh*.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2664
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2665 The ability to create new handlers with higher- or lower-severity filters can be
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2666 very helpful when writing and testing an application. Instead of using many
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2667 ``print`` statements for debugging, use ``logger.debug``: Unlike the print
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2668 statements, which you will have to delete or comment out later, the logger.debug
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2669 statements can remain intact in the source code and remain dormant until you
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2670 need them again. At that time, the only change that needs to happen is to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2671 modify the severity level of the logger and/or handler to debug.
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2672
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2673
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2674 Using logging in multiple modules
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2675 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2676
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2677 It was mentioned above that multiple calls to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2678 ``logging.getLogger('someLogger')`` return a reference to the same logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2679 object. This is true not only within the same module, but also across modules
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2680 as long as it is in the same Python interpreter process. It is true for
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2681 references to the same object; additionally, application code can define and
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2682 configure a parent logger in one module and create (but not configure) a child
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2683 logger in a separate module, and all logger calls to the child will pass up to
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2684 the parent. Here is a main module::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2685
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2686 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2687 import auxiliary_module
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2688
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2689 # create logger with "spam_application"
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2690 logger = logging.getLogger("spam_application")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2691 logger.setLevel(logging.DEBUG)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2692 # create file handler which logs even debug messages
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2693 fh = logging.FileHandler("spam.log")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2694 fh.setLevel(logging.DEBUG)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2695 # create console handler with a higher log level
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2696 ch = logging.StreamHandler()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2697 ch.setLevel(logging.ERROR)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2698 # create formatter and add it to the handlers
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2699 formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2700 fh.setFormatter(formatter)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2701 ch.setFormatter(formatter)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2702 # add the handlers to the logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2703 logger.addHandler(fh)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2704 logger.addHandler(ch)
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2705
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2706 logger.info("creating an instance of auxiliary_module.Auxiliary")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2707 a = auxiliary_module.Auxiliary()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2708 logger.info("created an instance of auxiliary_module.Auxiliary")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2709 logger.info("calling auxiliary_module.Auxiliary.do_something")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2710 a.do_something()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2711 logger.info("finished auxiliary_module.Auxiliary.do_something")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2712 logger.info("calling auxiliary_module.some_function()")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2713 auxiliary_module.some_function()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2714 logger.info("done with auxiliary_module.some_function()")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2715
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2716 Here is the auxiliary module::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2717
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2718 import logging
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2719
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2720 # create logger
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2721 module_logger = logging.getLogger("spam_application.auxiliary")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2722
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2723 class Auxiliary:
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2724 def __init__(self):
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2725 self.logger = logging.getLogger("spam_application.auxiliary.Auxiliary")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2726 self.logger.info("creating an instance of Auxiliary")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2727 def do_something(self):
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2728 self.logger.info("doing something")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2729 a = 1 + 1
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2730 self.logger.info("done doing something")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2731
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2732 def some_function():
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2733 module_logger.info("received a call to \"some_function\"")
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2734
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2735 The output looks like this::
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2736
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2737 2005-03-23 23:47:11,663 - spam_application - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2738 creating an instance of auxiliary_module.Auxiliary
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2739 2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2740 creating an instance of Auxiliary
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2741 2005-03-23 23:47:11,665 - spam_application - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2742 created an instance of auxiliary_module.Auxiliary
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2743 2005-03-23 23:47:11,668 - spam_application - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2744 calling auxiliary_module.Auxiliary.do_something
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2745 2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2746 doing something
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2747 2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2748 done doing something
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2749 2005-03-23 23:47:11,670 - spam_application - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2750 finished auxiliary_module.Auxiliary.do_something
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2751 2005-03-23 23:47:11,671 - spam_application - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2752 calling auxiliary_module.some_function()
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2753 2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2754 received a call to "some_function"
44560
b98977f0aba1 Updated docs for basicConfig to indicate it's a no-op if handlers have been defined for the root logger.
Vinay Sajip <vinay_sajip@yahoo.co.uk>
parents: 44383
diff changeset
2755 2005-03-23 23:47:11,673 - spam_application - INFO -
44151
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2756 done with auxiliary_module.some_function()
16ba00168c6a Add tutorial and examples to logging docs, from GHOP student "oscar8thegrouch".
Georg Brandl <georg@python.org>
parents: 43643
diff changeset
2757