Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`logging` --- Logging facility for Python |
| 2 | ============================================== |
| 3 | |
| 4 | .. module:: logging |
Vinay Sajip | 1d5d685 | 2010-12-12 22:47:13 +0000 | [diff] [blame] | 5 | :synopsis: Flexible event logging system for applications. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com> |
| 8 | .. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com> |
| 9 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 10 | **Source code:** :source:`Lib/logging/__init__.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | .. index:: pair: Errors; logging |
| 13 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 14 | .. sidebar:: Important |
| 15 | |
Vinay Sajip | 01094e1 | 2010-12-19 13:41:26 +0000 | [diff] [blame] | 16 | This page contains the API reference information. For tutorial |
| 17 | information and discussion of more advanced topics, see |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 18 | |
| 19 | * :ref:`Basic Tutorial <logging-basic-tutorial>` |
| 20 | * :ref:`Advanced Tutorial <logging-advanced-tutorial>` |
| 21 | * :ref:`Logging Cookbook <logging-cookbook>` |
| 22 | |
Vinay Sajip | 31b862d | 2013-09-05 23:01:07 +0100 | [diff] [blame] | 23 | -------------- |
| 24 | |
Vinay Sajip | 1d5d685 | 2010-12-12 22:47:13 +0000 | [diff] [blame] | 25 | This module defines functions and classes which implement a flexible event |
Vinay Sajip | 36675b6 | 2010-12-12 22:30:17 +0000 | [diff] [blame] | 26 | logging system for applications and libraries. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | |
Vinay Sajip | a18b959 | 2010-12-12 13:20:55 +0000 | [diff] [blame] | 28 | The key benefit of having the logging API provided by a standard library module |
| 29 | is that all Python modules can participate in logging, so your application log |
| 30 | can include your own messages integrated with messages from third-party |
| 31 | modules. |
| 32 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 33 | The module provides a lot of functionality and flexibility. If you are |
| 34 | unfamiliar with logging, the best way to get to grips with it is to see the |
Vinay Sajip | 01094e1 | 2010-12-19 13:41:26 +0000 | [diff] [blame] | 35 | tutorials (see the links on the right). |
Vinay Sajip | a18b959 | 2010-12-12 13:20:55 +0000 | [diff] [blame] | 36 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 37 | The basic classes defined by the module, together with their functions, are |
| 38 | listed below. |
Vinay Sajip | 9a6b400 | 2010-12-14 19:40:21 +0000 | [diff] [blame] | 39 | |
| 40 | * Loggers expose the interface that application code directly uses. |
| 41 | * Handlers send the log records (created by loggers) to the appropriate |
| 42 | destination. |
| 43 | * Filters provide a finer grained facility for determining which log records |
| 44 | to output. |
| 45 | * Formatters specify the layout of log records in the final output. |
Vinay Sajip | a18b959 | 2010-12-12 13:20:55 +0000 | [diff] [blame] | 46 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 48 | .. _logger: |
Vinay Sajip | 5286ccf | 2010-12-12 13:25:29 +0000 | [diff] [blame] | 49 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 50 | Logger Objects |
Christian Heimes | 8b0facf | 2007-12-04 19:30:01 +0000 | [diff] [blame] | 51 | -------------- |
| 52 | |
Vinay Sajip | 074faff | 2012-04-10 19:59:50 +0100 | [diff] [blame] | 53 | Loggers have the following attributes and methods. Note that Loggers are never |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 54 | instantiated directly, but always through the module-level function |
Vinay Sajip | 074faff | 2012-04-10 19:59:50 +0100 | [diff] [blame] | 55 | ``logging.getLogger(name)``. Multiple calls to :func:`getLogger` with the same |
| 56 | name will always return a reference to the same Logger object. |
| 57 | |
| 58 | The ``name`` is potentially a period-separated hierarchical value, like |
| 59 | ``foo.bar.baz`` (though it could also be just plain ``foo``, for example). |
| 60 | Loggers that are further down in the hierarchical list are children of loggers |
| 61 | higher up in the list. For example, given a logger with a name of ``foo``, |
| 62 | loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all |
| 63 | descendants of ``foo``. The logger name hierarchy is analogous to the Python |
| 64 | package hierarchy, and identical to it if you organise your loggers on a |
| 65 | per-module basis using the recommended construction |
| 66 | ``logging.getLogger(__name__)``. That's because in a module, ``__name__`` |
| 67 | is the module's name in the Python package namespace. |
| 68 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 70 | .. class:: Logger |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 72 | .. attribute:: Logger.propagate |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 74 | If this attribute evaluates to true, events logged to this logger will be |
| 75 | passed to the handlers of higher level (ancestor) loggers, in addition to |
| 76 | any handlers attached to this logger. Messages are passed directly to the |
| 77 | ancestor loggers' handlers - neither the level nor filters of the ancestor |
| 78 | loggers in question are considered. |
Vinay Sajip | 287f246 | 2011-11-23 08:54:22 +0000 | [diff] [blame] | 79 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 80 | If this evaluates to false, logging messages are not passed to the handlers |
| 81 | of ancestor loggers. |
Vinay Sajip | 287f246 | 2011-11-23 08:54:22 +0000 | [diff] [blame] | 82 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 83 | The constructor sets this attribute to ``True``. |
Vinay Sajip | c8c8c69 | 2010-09-17 10:09:04 +0000 | [diff] [blame] | 84 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 85 | .. note:: If you attach a handler to a logger *and* one or more of its |
| 86 | ancestors, it may emit the same record multiple times. In general, you |
| 87 | should not need to attach a handler to more than one logger - if you just |
| 88 | attach it to the appropriate logger which is highest in the logger |
| 89 | hierarchy, then it will see all events logged by all descendant loggers, |
| 90 | provided that their propagate setting is left set to ``True``. A common |
| 91 | scenario is to attach handlers only to the root logger, and to let |
| 92 | propagation take care of the rest. |
Vinay Sajip | c8c8c69 | 2010-09-17 10:09:04 +0000 | [diff] [blame] | 93 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 94 | .. method:: Logger.setLevel(level) |
Vinay Sajip | f234eb9 | 2010-12-12 17:37:27 +0000 | [diff] [blame] | 95 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 96 | Sets the threshold for this logger to *level*. Logging messages which are less |
| 97 | severe than *level* will be ignored; logging messages which have severity *level* |
Vinay Sajip | 0653fba | 2017-07-06 17:51:28 +0100 | [diff] [blame] | 98 | or higher will be emitted by whichever handler or handlers service this logger, |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 99 | unless a handler's level has been set to a higher severity level than *level*. |
Vinay Sajip | 0653fba | 2017-07-06 17:51:28 +0100 | [diff] [blame] | 100 | |
| 101 | When a logger is created, the level is set to :const:`NOTSET` (which causes |
| 102 | all messages to be processed when the logger is the root logger, or delegation |
| 103 | to the parent when the logger is a non-root logger). Note that the root logger |
| 104 | is created with level :const:`WARNING`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 105 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 106 | The term 'delegation to the parent' means that if a logger has a level of |
| 107 | NOTSET, its chain of ancestor loggers is traversed until either an ancestor with |
| 108 | a level other than NOTSET is found, or the root is reached. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 109 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 110 | If an ancestor is found with a level other than NOTSET, then that ancestor's |
| 111 | level is treated as the effective level of the logger where the ancestor search |
| 112 | began, and is used to determine how a logging event is handled. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 113 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 114 | If the root is reached, and it has a level of NOTSET, then all messages will be |
| 115 | processed. Otherwise, the root's level will be used as the effective level. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 116 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 117 | See :ref:`levels` for a list of levels. |
Vinay Sajip | 800e11b | 2013-12-19 11:50:24 +0000 | [diff] [blame] | 118 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 119 | .. versionchanged:: 3.2 |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 120 | The *level* parameter now accepts a string representation of the |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 121 | level such as 'INFO' as an alternative to the integer constants |
| 122 | such as :const:`INFO`. Note, however, that levels are internally stored |
| 123 | as integers, and methods such as e.g. :meth:`getEffectiveLevel` and |
| 124 | :meth:`isEnabledFor` will return/expect to be passed integers. |
Gregory P. Smith | c1f079f | 2012-01-14 12:46:17 -0800 | [diff] [blame] | 125 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 126 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 127 | .. method:: Logger.isEnabledFor(lvl) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 128 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 129 | Indicates if a message of severity *lvl* would be processed by this logger. |
| 130 | This method checks first the module-level level set by |
| 131 | ``logging.disable(lvl)`` and then the logger's effective level as determined |
| 132 | by :meth:`getEffectiveLevel`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 133 | |
| 134 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 135 | .. method:: Logger.getEffectiveLevel() |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 136 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 137 | Indicates the effective level for this logger. If a value other than |
| 138 | :const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise, |
| 139 | the hierarchy is traversed towards the root until a value other than |
| 140 | :const:`NOTSET` is found, and that value is returned. The value returned is |
| 141 | an integer, typically one of :const:`logging.DEBUG`, :const:`logging.INFO` |
| 142 | etc. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 143 | |
| 144 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 145 | .. method:: Logger.getChild(suffix) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 146 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 147 | Returns a logger which is a descendant to this logger, as determined by the suffix. |
| 148 | Thus, ``logging.getLogger('abc').getChild('def.ghi')`` would return the same |
| 149 | logger as would be returned by ``logging.getLogger('abc.def.ghi')``. This is a |
| 150 | convenience method, useful when the parent logger is named using e.g. ``__name__`` |
| 151 | rather than a literal string. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 152 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 153 | .. versionadded:: 3.2 |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 154 | |
| 155 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 156 | .. method:: Logger.debug(msg, *args, **kwargs) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 157 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 158 | Logs a message with level :const:`DEBUG` on this logger. The *msg* is the |
| 159 | message format string, and the *args* are the arguments which are merged into |
| 160 | *msg* using the string formatting operator. (Note that this means that you can |
| 161 | use keywords in the format string, together with a single dictionary argument.) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 162 | |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 163 | There are four keyword arguments in *kwargs* which are inspected: |
| 164 | *exc_info*, *stack_info*, *stacklevel* and *extra*. |
Vinay Sajip | 02a8f9e | 2014-09-14 21:29:11 +0100 | [diff] [blame] | 165 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 166 | If *exc_info* does not evaluate as false, it causes exception information to be |
| 167 | added to the logging message. If an exception tuple (in the format returned by |
| 168 | :func:`sys.exc_info`) or an exception instance is provided, it is used; |
| 169 | otherwise, :func:`sys.exc_info` is called to get the exception information. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 170 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 171 | The second optional keyword argument is *stack_info*, which defaults to |
| 172 | ``False``. If true, stack information is added to the logging |
| 173 | message, including the actual logging call. Note that this is not the same |
| 174 | stack information as that displayed through specifying *exc_info*: The |
| 175 | former is stack frames from the bottom of the stack up to the logging call |
| 176 | in the current thread, whereas the latter is information about stack frames |
| 177 | which have been unwound, following an exception, while searching for |
| 178 | exception handlers. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 179 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 180 | You can specify *stack_info* independently of *exc_info*, e.g. to just show |
| 181 | how you got to a certain point in your code, even when no exceptions were |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 182 | raised. The stack frames are printed following a header line which says: |
| 183 | |
| 184 | .. code-block:: none |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 185 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 186 | Stack (most recent call last): |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 187 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 188 | This mimics the ``Traceback (most recent call last):`` which is used when |
| 189 | displaying exception frames. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 190 | |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 191 | The third optional keyword argument is *stacklevel*, which defaults to ``1``. |
| 192 | If greater than 1, the corresponding number of stack frames are skipped |
| 193 | when computing the line number and function name set in the :class:`LogRecord` |
| 194 | created for the logging event. This can be used in logging helpers so that |
| 195 | the function name, filename and line number recorded are not the information |
| 196 | for the helper function/method, but rather its caller. The name of this |
| 197 | parameter mirrors the equivalent one in the :mod:`warnings` module. |
| 198 | |
| 199 | The fourth keyword argument is *extra* which can be used to pass a |
| 200 | dictionary which is used to populate the __dict__ of the :class:`LogRecord` |
| 201 | created for the logging event with user-defined attributes. These custom |
| 202 | attributes can then be used as you like. For example, they could be |
| 203 | incorporated into logged messages. For example:: |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 204 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 205 | FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s' |
| 206 | logging.basicConfig(format=FORMAT) |
| 207 | d = {'clientip': '192.168.0.1', 'user': 'fbloggs'} |
| 208 | logger = logging.getLogger('tcpserver') |
| 209 | logger.warning('Protocol problem: %s', 'connection reset', extra=d) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 210 | |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 211 | would print something like |
| 212 | |
| 213 | .. code-block:: none |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 214 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 215 | 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 216 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 217 | The keys in the dictionary passed in *extra* should not clash with the keys used |
| 218 | by the logging system. (See the :class:`Formatter` documentation for more |
| 219 | information on which keys are used by the logging system.) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 220 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 221 | If you choose to use these attributes in logged messages, you need to exercise |
| 222 | some care. In the above example, for instance, the :class:`Formatter` has been |
| 223 | set up with a format string which expects 'clientip' and 'user' in the attribute |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 224 | dictionary of the :class:`LogRecord`. If these are missing, the message will |
| 225 | not be logged because a string formatting exception will occur. So in this case, |
| 226 | you always need to pass the *extra* dictionary with these keys. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 227 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 228 | While this might be annoying, this feature is intended for use in specialized |
| 229 | circumstances, such as multi-threaded servers where the same code executes in |
| 230 | many contexts, and interesting conditions which arise are dependent on this |
| 231 | context (such as remote client IP address and authenticated user name, in the |
| 232 | above example). In such circumstances, it is likely that specialized |
| 233 | :class:`Formatter`\ s would be used with particular :class:`Handler`\ s. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 234 | |
Sergey Fedoseev | f120288 | 2018-07-06 05:01:16 +0500 | [diff] [blame] | 235 | .. versionchanged:: 3.2 |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 236 | The *stack_info* parameter was added. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 237 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 238 | .. versionchanged:: 3.5 |
| 239 | The *exc_info* parameter can now accept exception instances. |
Vinay Sajip | 02a8f9e | 2014-09-14 21:29:11 +0100 | [diff] [blame] | 240 | |
Sergey Fedoseev | f120288 | 2018-07-06 05:01:16 +0500 | [diff] [blame] | 241 | .. versionchanged:: 3.8 |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 242 | The *stacklevel* parameter was added. |
| 243 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 244 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 245 | .. method:: Logger.info(msg, *args, **kwargs) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 246 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 247 | Logs a message with level :const:`INFO` on this logger. The arguments are |
| 248 | interpreted as for :meth:`debug`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 249 | |
| 250 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 251 | .. method:: Logger.warning(msg, *args, **kwargs) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 252 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 253 | Logs a message with level :const:`WARNING` on this logger. The arguments are |
| 254 | interpreted as for :meth:`debug`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 255 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 256 | .. note:: There is an obsolete method ``warn`` which is functionally |
| 257 | identical to ``warning``. As ``warn`` is deprecated, please do not use |
| 258 | it - use ``warning`` instead. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 259 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 260 | .. method:: Logger.error(msg, *args, **kwargs) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 261 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 262 | Logs a message with level :const:`ERROR` on this logger. The arguments are |
| 263 | interpreted as for :meth:`debug`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 264 | |
| 265 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 266 | .. method:: Logger.critical(msg, *args, **kwargs) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 267 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 268 | Logs a message with level :const:`CRITICAL` on this logger. The arguments are |
| 269 | interpreted as for :meth:`debug`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 270 | |
| 271 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 272 | .. method:: Logger.log(lvl, msg, *args, **kwargs) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 273 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 274 | Logs a message with integer level *lvl* on this logger. The other arguments are |
| 275 | interpreted as for :meth:`debug`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 276 | |
| 277 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 278 | .. method:: Logger.exception(msg, *args, **kwargs) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 279 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 280 | Logs a message with level :const:`ERROR` on this logger. The arguments are |
| 281 | interpreted as for :meth:`debug`. Exception info is added to the logging |
| 282 | message. This method should only be called from an exception handler. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 283 | |
| 284 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 285 | .. method:: Logger.addFilter(filter) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 286 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 287 | Adds the specified filter *filter* to this logger. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 288 | |
| 289 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 290 | .. method:: Logger.removeFilter(filter) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 291 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 292 | Removes the specified filter *filter* from this logger. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 293 | |
| 294 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 295 | .. method:: Logger.filter(record) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 296 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 297 | Applies this logger's filters to the record and returns a true value if the |
| 298 | record is to be processed. The filters are consulted in turn, until one of |
| 299 | them returns a false value. If none of them return a false value, the record |
| 300 | will be processed (passed to handlers). If one returns a false value, no |
| 301 | further processing of the record occurs. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 302 | |
| 303 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 304 | .. method:: Logger.addHandler(hdlr) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 305 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 306 | Adds the specified handler *hdlr* to this logger. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 307 | |
| 308 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 309 | .. method:: Logger.removeHandler(hdlr) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 310 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 311 | Removes the specified handler *hdlr* from this logger. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 312 | |
| 313 | |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 314 | .. method:: Logger.findCaller(stack_info=False, stacklevel=1) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 315 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 316 | Finds the caller's source filename and line number. Returns the filename, line |
| 317 | number, function name and stack information as a 4-element tuple. The stack |
| 318 | information is returned as ``None`` unless *stack_info* is ``True``. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 319 | |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 320 | The *stacklevel* parameter is passed from code calling the :meth:`debug` |
| 321 | and other APIs. If greater than 1, the excess is used to skip stack frames |
| 322 | before determining the values to be returned. This will generally be useful |
| 323 | when calling logging APIs from helper/wrapper code, so that the information |
| 324 | in the event log refers not to the helper/wrapper code, but to the code that |
| 325 | calls it. |
| 326 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 327 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 328 | .. method:: Logger.handle(record) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 329 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 330 | Handles a record by passing it to all handlers associated with this logger and |
| 331 | its ancestors (until a false value of *propagate* is found). This method is used |
| 332 | for unpickled records received from a socket, as well as those created locally. |
| 333 | Logger-level filtering is applied using :meth:`~Logger.filter`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 334 | |
| 335 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 336 | .. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 337 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 338 | This is a factory method which can be overridden in subclasses to create |
| 339 | specialized :class:`LogRecord` instances. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 340 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 341 | .. method:: Logger.hasHandlers() |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 342 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 343 | Checks to see if this logger has any handlers configured. This is done by |
| 344 | looking for handlers in this logger and its parents in the logger hierarchy. |
| 345 | Returns ``True`` if a handler was found, else ``False``. The method stops searching |
| 346 | up the hierarchy whenever a logger with the 'propagate' attribute set to |
| 347 | false is found - that will be the last logger which is checked for the |
| 348 | existence of handlers. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 349 | |
Jim Fasarakis-Hilliard | 55ace65 | 2017-05-07 21:40:18 +0300 | [diff] [blame] | 350 | .. versionadded:: 3.2 |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 351 | |
Vinay Sajip | 6260d9f | 2017-06-06 16:34:29 +0100 | [diff] [blame] | 352 | .. versionchanged:: 3.7 |
James Walker | 982c723 | 2018-02-28 19:46:35 -0400 | [diff] [blame] | 353 | Loggers can now be pickled and unpickled. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 354 | |
Vinay Sajip | 800e11b | 2013-12-19 11:50:24 +0000 | [diff] [blame] | 355 | .. _levels: |
| 356 | |
| 357 | Logging Levels |
| 358 | -------------- |
| 359 | |
| 360 | The numeric values of logging levels are given in the following table. These are |
| 361 | primarily of interest if you want to define your own levels, and need them to |
| 362 | have specific values relative to the predefined levels. If you define a level |
| 363 | with the same numeric value, it overwrites the predefined value; the predefined |
| 364 | name is lost. |
| 365 | |
| 366 | +--------------+---------------+ |
| 367 | | Level | Numeric value | |
| 368 | +==============+===============+ |
| 369 | | ``CRITICAL`` | 50 | |
| 370 | +--------------+---------------+ |
| 371 | | ``ERROR`` | 40 | |
| 372 | +--------------+---------------+ |
| 373 | | ``WARNING`` | 30 | |
| 374 | +--------------+---------------+ |
| 375 | | ``INFO`` | 20 | |
| 376 | +--------------+---------------+ |
| 377 | | ``DEBUG`` | 10 | |
| 378 | +--------------+---------------+ |
| 379 | | ``NOTSET`` | 0 | |
| 380 | +--------------+---------------+ |
| 381 | |
| 382 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 383 | .. _handler: |
| 384 | |
| 385 | Handler Objects |
Benjamin Peterson | 058e31e | 2009-01-16 03:54:08 +0000 | [diff] [blame] | 386 | --------------- |
| 387 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 388 | Handlers have the following attributes and methods. Note that :class:`Handler` |
| 389 | is never instantiated directly; this class acts as a base for more useful |
| 390 | subclasses. However, the :meth:`__init__` method in subclasses needs to call |
| 391 | :meth:`Handler.__init__`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 392 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 393 | .. class:: Handler |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 394 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 395 | .. method:: Handler.__init__(level=NOTSET) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 396 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 397 | Initializes the :class:`Handler` instance by setting its level, setting the list |
| 398 | of filters to the empty list and creating a lock (using :meth:`createLock`) for |
| 399 | serializing access to an I/O mechanism. |
Vinay Sajip | 30bf122 | 2009-01-10 19:23:34 +0000 | [diff] [blame] | 400 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 401 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 402 | .. method:: Handler.createLock() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 403 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 404 | Initializes a thread lock which can be used to serialize access to underlying |
| 405 | I/O functionality which may not be threadsafe. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 406 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 407 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 408 | .. method:: Handler.acquire() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 409 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 410 | Acquires the thread lock created with :meth:`createLock`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 411 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 412 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 413 | .. method:: Handler.release() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 414 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 415 | Releases the thread lock acquired with :meth:`acquire`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 416 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 417 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 418 | .. method:: Handler.setLevel(level) |
Vinay Sajip | 30bf122 | 2009-01-10 19:23:34 +0000 | [diff] [blame] | 419 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 420 | Sets the threshold for this handler to *level*. Logging messages which are |
| 421 | less severe than *level* will be ignored. When a handler is created, the |
| 422 | level is set to :const:`NOTSET` (which causes all messages to be |
| 423 | processed). |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 424 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 425 | See :ref:`levels` for a list of levels. |
Vinay Sajip | 800e11b | 2013-12-19 11:50:24 +0000 | [diff] [blame] | 426 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 427 | .. versionchanged:: 3.2 |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 428 | The *level* parameter now accepts a string representation of the |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 429 | level such as 'INFO' as an alternative to the integer constants |
| 430 | such as :const:`INFO`. |
Gregory P. Smith | c1f079f | 2012-01-14 12:46:17 -0800 | [diff] [blame] | 431 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 432 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 433 | .. method:: Handler.setFormatter(fmt) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 434 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 435 | Sets the :class:`Formatter` for this handler to *fmt*. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 436 | |
| 437 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 438 | .. method:: Handler.addFilter(filter) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 439 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 440 | Adds the specified filter *filter* to this handler. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 441 | |
| 442 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 443 | .. method:: Handler.removeFilter(filter) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 444 | |
Vinay Sajip | a9f8df6 | 2017-12-09 11:09:04 +0000 | [diff] [blame] | 445 | Removes the specified filter *filter* from this handler. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 446 | |
| 447 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 448 | .. method:: Handler.filter(record) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 449 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 450 | Applies this handler's filters to the record and returns a true value if the |
| 451 | record is to be processed. The filters are consulted in turn, until one of |
| 452 | them returns a false value. If none of them return a false value, the record |
| 453 | will be emitted. If one returns a false value, the handler will not emit the |
| 454 | record. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 455 | |
| 456 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 457 | .. method:: Handler.flush() |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 458 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 459 | Ensure all logging output has been flushed. This version does nothing and is |
| 460 | intended to be implemented by subclasses. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 461 | |
| 462 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 463 | .. method:: Handler.close() |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 464 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 465 | Tidy up any resources used by the handler. This version does no output but |
| 466 | removes the handler from an internal list of handlers which is closed when |
| 467 | :func:`shutdown` is called. Subclasses should ensure that this gets called |
| 468 | from overridden :meth:`close` methods. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 469 | |
| 470 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 471 | .. method:: Handler.handle(record) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 472 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 473 | Conditionally emits the specified logging record, depending on filters which may |
| 474 | have been added to the handler. Wraps the actual emission of the record with |
| 475 | acquisition/release of the I/O thread lock. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 476 | |
| 477 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 478 | .. method:: Handler.handleError(record) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 479 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 480 | This method should be called from handlers when an exception is encountered |
| 481 | during an :meth:`emit` call. If the module-level attribute |
| 482 | ``raiseExceptions`` is ``False``, exceptions get silently ignored. This is |
| 483 | what is mostly wanted for a logging system - most users will not care about |
| 484 | errors in the logging system, they are more interested in application |
| 485 | errors. You could, however, replace this with a custom handler if you wish. |
| 486 | The specified record is the one which was being processed when the exception |
| 487 | occurred. (The default value of ``raiseExceptions`` is ``True``, as that is |
| 488 | more useful during development). |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 489 | |
| 490 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 491 | .. method:: Handler.format(record) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 492 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 493 | Do formatting for a record - if a formatter is set, use it. Otherwise, use the |
| 494 | default formatter for the module. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 495 | |
| 496 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 497 | .. method:: Handler.emit(record) |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 498 | |
Vinay Sajip | 82a6384 | 2017-05-12 09:38:13 +0100 | [diff] [blame] | 499 | Do whatever it takes to actually log the specified logging record. This version |
| 500 | is intended to be implemented by subclasses and so raises a |
| 501 | :exc:`NotImplementedError`. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 502 | |
| 503 | For a list of handlers included as standard, see :mod:`logging.handlers`. |
| 504 | |
| 505 | .. _formatter-objects: |
| 506 | |
| 507 | Formatter Objects |
| 508 | ----------------- |
Vinay Sajip | 121a1c4 | 2010-09-08 10:46:15 +0000 | [diff] [blame] | 509 | |
Vinay Sajip | 30bf122 | 2009-01-10 19:23:34 +0000 | [diff] [blame] | 510 | .. currentmodule:: logging |
| 511 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 512 | :class:`Formatter` objects have the following attributes and methods. They are |
| 513 | responsible for converting a :class:`LogRecord` to (usually) a string which can |
| 514 | be interpreted by either a human or an external system. The base |
| 515 | :class:`Formatter` allows a formatting string to be specified. If none is |
Vinay Sajip | bbd95a9 | 2015-05-02 09:46:05 +0100 | [diff] [blame] | 516 | supplied, the default value of ``'%(message)s'`` is used, which just includes |
| 517 | the message in the logging call. To have additional items of information in the |
| 518 | formatted output (such as a timestamp), keep reading. |
Georg Brandl | f973407 | 2008-12-07 15:30:06 +0000 | [diff] [blame] | 519 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 520 | A Formatter can be initialized with a format string which makes use of knowledge |
| 521 | of the :class:`LogRecord` attributes - such as the default value mentioned above |
| 522 | making use of the fact that the user's message and arguments are pre-formatted |
| 523 | into a :class:`LogRecord`'s *message* attribute. This format string contains |
| 524 | standard Python %-style mapping keys. See section :ref:`old-string-formatting` |
| 525 | for more information on string formatting. |
Georg Brandl | f973407 | 2008-12-07 15:30:06 +0000 | [diff] [blame] | 526 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 527 | The useful mapping keys in a :class:`LogRecord` are given in the section on |
| 528 | :ref:`logrecord-attributes`. |
Vinay Sajip | 121a1c4 | 2010-09-08 10:46:15 +0000 | [diff] [blame] | 529 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 530 | |
Vinay Sajip | c46102c | 2011-04-08 01:30:51 +0100 | [diff] [blame] | 531 | .. class:: Formatter(fmt=None, datefmt=None, style='%') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 532 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 533 | Returns a new instance of the :class:`Formatter` class. The instance is |
| 534 | initialized with a format string for the message as a whole, as well as a |
| 535 | format string for the date/time portion of a message. If no *fmt* is |
Vinay Sajip | 23cee80 | 2018-06-01 10:09:21 +0100 | [diff] [blame] | 536 | specified, ``'%(message)s'`` is used. If no *datefmt* is specified, a format |
| 537 | is used which is described in the :meth:`formatTime` documentation. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 538 | |
Vinay Sajip | c46102c | 2011-04-08 01:30:51 +0100 | [diff] [blame] | 539 | The *style* parameter can be one of '%', '{' or '$' and determines how |
| 540 | the format string will be merged with its data: using one of %-formatting, |
Vinay Sajip | cbefe3b | 2014-01-15 15:09:05 +0000 | [diff] [blame] | 541 | :meth:`str.format` or :class:`string.Template`. See :ref:`formatting-styles` |
| 542 | for more information on using {- and $-formatting for log messages. |
Vinay Sajip | c46102c | 2011-04-08 01:30:51 +0100 | [diff] [blame] | 543 | |
| 544 | .. versionchanged:: 3.2 |
| 545 | The *style* parameter was added. |
| 546 | |
| 547 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 548 | .. method:: format(record) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 549 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 550 | The record's attribute dictionary is used as the operand to a string |
| 551 | formatting operation. Returns the resulting string. Before formatting the |
| 552 | dictionary, a couple of preparatory steps are carried out. The *message* |
| 553 | attribute of the record is computed using *msg* % *args*. If the |
| 554 | formatting string contains ``'(asctime)'``, :meth:`formatTime` is called |
| 555 | to format the event time. If there is exception information, it is |
| 556 | formatted using :meth:`formatException` and appended to the message. Note |
| 557 | that the formatted exception information is cached in attribute |
| 558 | *exc_text*. This is useful because the exception information can be |
| 559 | pickled and sent across the wire, but you should be careful if you have |
| 560 | more than one :class:`Formatter` subclass which customizes the formatting |
| 561 | of exception information. In this case, you will have to clear the cached |
| 562 | value after a formatter has done its formatting, so that the next |
| 563 | formatter to handle the event doesn't use the cached value but |
| 564 | recalculates it afresh. |
| 565 | |
| 566 | If stack information is available, it's appended after the exception |
| 567 | information, using :meth:`formatStack` to transform it if necessary. |
| 568 | |
| 569 | |
| 570 | .. method:: formatTime(record, datefmt=None) |
| 571 | |
| 572 | This method should be called from :meth:`format` by a formatter which |
| 573 | wants to make use of a formatted time. This method can be overridden in |
| 574 | formatters to provide for any specific requirement, but the basic behavior |
| 575 | is as follows: if *datefmt* (a string) is specified, it is used with |
| 576 | :func:`time.strftime` to format the creation time of the |
Vinay Sajip | 23cee80 | 2018-06-01 10:09:21 +0100 | [diff] [blame] | 577 | record. Otherwise, the format '%Y-%m-%d %H:%M:%S,uuu' is used, where the |
| 578 | uuu part is a millisecond value and the other letters are as per the |
| 579 | :func:`time.strftime` documentation. An example time in this format is |
| 580 | ``2003-01-23 00:29:50,411``. The resulting string is returned. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 581 | |
Vinay Sajip | cdc7517 | 2011-06-12 11:44:28 +0100 | [diff] [blame] | 582 | This function uses a user-configurable function to convert the creation |
| 583 | time to a tuple. By default, :func:`time.localtime` is used; to change |
| 584 | this for a particular formatter instance, set the ``converter`` attribute |
| 585 | to a function with the same signature as :func:`time.localtime` or |
| 586 | :func:`time.gmtime`. To change it for all formatters, for example if you |
| 587 | want all logging times to be shown in GMT, set the ``converter`` |
| 588 | attribute in the ``Formatter`` class. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 589 | |
Vinay Sajip | 89c00ce | 2011-06-10 19:05:16 +0100 | [diff] [blame] | 590 | .. versionchanged:: 3.3 |
Vinay Sajip | 23cee80 | 2018-06-01 10:09:21 +0100 | [diff] [blame] | 591 | Previously, the default format was hard-coded as in this example: |
| 592 | ``2010-09-06 22:38:15,292`` where the part before the comma is |
Georg Brandl | e10b5e1 | 2011-06-14 21:09:55 +0200 | [diff] [blame] | 593 | handled by a strptime format string (``'%Y-%m-%d %H:%M:%S'``), and the |
| 594 | part after the comma is a millisecond value. Because strptime does not |
| 595 | have a format placeholder for milliseconds, the millisecond value is |
Serhiy Storchaka | 29b0a26 | 2016-12-04 10:20:55 +0200 | [diff] [blame] | 596 | appended using another format string, ``'%s,%03d'`` --- and both of these |
Georg Brandl | e10b5e1 | 2011-06-14 21:09:55 +0200 | [diff] [blame] | 597 | format strings have been hardcoded into this method. With the change, |
| 598 | these strings are defined as class-level attributes which can be |
| 599 | overridden at the instance level when desired. The names of the |
| 600 | attributes are ``default_time_format`` (for the strptime format string) |
| 601 | and ``default_msec_format`` (for appending the millisecond value). |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 602 | |
| 603 | .. method:: formatException(exc_info) |
| 604 | |
| 605 | Formats the specified exception information (a standard exception tuple as |
| 606 | returned by :func:`sys.exc_info`) as a string. This default implementation |
| 607 | just uses :func:`traceback.print_exception`. The resulting string is |
| 608 | returned. |
| 609 | |
| 610 | .. method:: formatStack(stack_info) |
| 611 | |
| 612 | Formats the specified stack information (a string as returned by |
| 613 | :func:`traceback.print_stack`, but with the last newline removed) as a |
| 614 | string. This default implementation just returns the input value. |
| 615 | |
| 616 | .. _filter: |
| 617 | |
| 618 | Filter Objects |
| 619 | -------------- |
| 620 | |
| 621 | ``Filters`` can be used by ``Handlers`` and ``Loggers`` for more sophisticated |
| 622 | filtering than is provided by levels. The base filter class only allows events |
| 623 | which are below a certain point in the logger hierarchy. For example, a filter |
| 624 | initialized with 'A.B' will allow events logged by loggers 'A.B', 'A.B.C', |
| 625 | 'A.B.C.D', 'A.B.D' etc. but not 'A.BB', 'B.A.B' etc. If initialized with the |
| 626 | empty string, all events are passed. |
| 627 | |
| 628 | |
| 629 | .. class:: Filter(name='') |
| 630 | |
| 631 | Returns an instance of the :class:`Filter` class. If *name* is specified, it |
| 632 | names a logger which, together with its children, will have its events allowed |
| 633 | through the filter. If *name* is the empty string, allows every event. |
| 634 | |
| 635 | |
| 636 | .. method:: filter(record) |
| 637 | |
| 638 | Is the specified record to be logged? Returns zero for no, nonzero for |
| 639 | yes. If deemed appropriate, the record may be modified in-place by this |
| 640 | method. |
| 641 | |
Vinay Sajip | 6c4c16c | 2013-01-21 19:44:28 +0000 | [diff] [blame] | 642 | Note that filters attached to handlers are consulted before an event is |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 643 | emitted by the handler, whereas filters attached to loggers are consulted |
Vinay Sajip | 6c4c16c | 2013-01-21 19:44:28 +0000 | [diff] [blame] | 644 | whenever an event is logged (using :meth:`debug`, :meth:`info`, |
| 645 | etc.), before sending an event to handlers. This means that events which have |
| 646 | been generated by descendant loggers will not be filtered by a logger's filter |
| 647 | setting, unless the filter has also been applied to those descendant loggers. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 648 | |
| 649 | You don't actually need to subclass ``Filter``: you can pass any instance |
| 650 | which has a ``filter`` method with the same semantics. |
| 651 | |
| 652 | .. versionchanged:: 3.2 |
| 653 | You don't need to create specialized ``Filter`` classes, or use other |
| 654 | classes with a ``filter`` method: you can use a function (or other |
| 655 | callable) as a filter. The filtering logic will check to see if the filter |
| 656 | object has a ``filter`` attribute: if it does, it's assumed to be a |
| 657 | ``Filter`` and its :meth:`~Filter.filter` method is called. Otherwise, it's |
| 658 | assumed to be a callable and called with the record as the single |
| 659 | parameter. The returned value should conform to that returned by |
| 660 | :meth:`~Filter.filter`. |
| 661 | |
| 662 | Although filters are used primarily to filter records based on more |
| 663 | sophisticated criteria than levels, they get to see every record which is |
| 664 | processed by the handler or logger they're attached to: this can be useful if |
| 665 | you want to do things like counting how many records were processed by a |
| 666 | particular logger or handler, or adding, changing or removing attributes in |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 667 | the :class:`LogRecord` being processed. Obviously changing the LogRecord needs |
| 668 | to be done with some care, but it does allow the injection of contextual |
| 669 | information into logs (see :ref:`filters-contextual`). |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 670 | |
| 671 | .. _log-record: |
| 672 | |
| 673 | LogRecord Objects |
| 674 | ----------------- |
| 675 | |
| 676 | :class:`LogRecord` instances are created automatically by the :class:`Logger` |
| 677 | every time something is logged, and can be created manually via |
| 678 | :func:`makeLogRecord` (for example, from a pickled event received over the |
| 679 | wire). |
| 680 | |
| 681 | |
| 682 | .. class:: LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None) |
| 683 | |
| 684 | Contains all the information pertinent to the event being logged. |
| 685 | |
| 686 | The primary information is passed in :attr:`msg` and :attr:`args`, which |
| 687 | are combined using ``msg % args`` to create the :attr:`message` field of the |
| 688 | record. |
| 689 | |
| 690 | :param name: The name of the logger used to log the event represented by |
Vinay Sajip | 6c4c16c | 2013-01-21 19:44:28 +0000 | [diff] [blame] | 691 | this LogRecord. Note that this name will always have this |
| 692 | value, even though it may be emitted by a handler attached to |
| 693 | a different (ancestor) logger. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 694 | :param level: The numeric level of the logging event (one of DEBUG, INFO etc.) |
Vinay Sajip | 0aaa9e1 | 2011-06-11 23:03:37 +0100 | [diff] [blame] | 695 | Note that this is converted to *two* attributes of the LogRecord: |
| 696 | ``levelno`` for the numeric value and ``levelname`` for the |
| 697 | corresponding level name. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 698 | :param pathname: The full pathname of the source file where the logging call |
| 699 | was made. |
| 700 | :param lineno: The line number in the source file where the logging call was |
| 701 | made. |
| 702 | :param msg: The event description message, possibly a format string with |
| 703 | placeholders for variable data. |
| 704 | :param args: Variable data to merge into the *msg* argument to obtain the |
| 705 | event description. |
| 706 | :param exc_info: An exception tuple with the current exception information, |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 707 | or ``None`` if no exception information is available. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 708 | :param func: The name of the function or method from which the logging call |
| 709 | was invoked. |
| 710 | :param sinfo: A text string representing stack information from the base of |
| 711 | the stack in the current thread, up to the logging call. |
| 712 | |
| 713 | .. method:: getMessage() |
| 714 | |
| 715 | Returns the message for this :class:`LogRecord` instance after merging any |
| 716 | user-supplied arguments with the message. If the user-supplied message |
| 717 | argument to the logging call is not a string, :func:`str` is called on it to |
| 718 | convert it to a string. This allows use of user-defined classes as |
| 719 | messages, whose ``__str__`` method can return the actual format string to |
| 720 | be used. |
| 721 | |
| 722 | .. versionchanged:: 3.2 |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 723 | The creation of a :class:`LogRecord` has been made more configurable by |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 724 | providing a factory which is used to create the record. The factory can be |
| 725 | set using :func:`getLogRecordFactory` and :func:`setLogRecordFactory` |
| 726 | (see this for the factory's signature). |
| 727 | |
| 728 | This functionality can be used to inject your own values into a |
Vinay Sajip | dde9fdb | 2018-06-05 17:24:18 +0100 | [diff] [blame] | 729 | :class:`LogRecord` at creation time. You can use the following pattern:: |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 730 | |
| 731 | old_factory = logging.getLogRecordFactory() |
| 732 | |
| 733 | def record_factory(*args, **kwargs): |
| 734 | record = old_factory(*args, **kwargs) |
| 735 | record.custom_attribute = 0xdecafbad |
| 736 | return record |
| 737 | |
| 738 | logging.setLogRecordFactory(record_factory) |
| 739 | |
| 740 | With this pattern, multiple factories could be chained, and as long |
| 741 | as they don't overwrite each other's attributes or unintentionally |
| 742 | overwrite the standard attributes listed above, there should be no |
| 743 | surprises. |
| 744 | |
| 745 | |
| 746 | .. _logrecord-attributes: |
| 747 | |
| 748 | LogRecord attributes |
| 749 | -------------------- |
| 750 | |
| 751 | The LogRecord has a number of attributes, most of which are derived from the |
| 752 | parameters to the constructor. (Note that the names do not always correspond |
| 753 | exactly between the LogRecord constructor parameters and the LogRecord |
| 754 | attributes.) These attributes can be used to merge data from the record into |
| 755 | the format string. The following table lists (in alphabetical order) the |
| 756 | attribute names, their meanings and the corresponding placeholder in a %-style |
| 757 | format string. |
| 758 | |
| 759 | If you are using {}-formatting (:func:`str.format`), you can use |
| 760 | ``{attrname}`` as the placeholder in the format string. If you are using |
| 761 | $-formatting (:class:`string.Template`), use the form ``${attrname}``. In |
| 762 | both cases, of course, replace ``attrname`` with the actual attribute name |
| 763 | you want to use. |
| 764 | |
| 765 | In the case of {}-formatting, you can specify formatting flags by placing them |
| 766 | after the attribute name, separated from it with a colon. For example: a |
| 767 | placeholder of ``{msecs:03d}`` would format a millisecond value of ``4`` as |
| 768 | ``004``. Refer to the :meth:`str.format` documentation for full details on |
| 769 | the options available to you. |
| 770 | |
| 771 | +----------------+-------------------------+-----------------------------------------------+ |
| 772 | | Attribute name | Format | Description | |
| 773 | +================+=========================+===============================================+ |
| 774 | | args | You shouldn't need to | The tuple of arguments merged into ``msg`` to | |
Vinay Sajip | 4f44d53 | 2015-11-24 23:21:15 +0000 | [diff] [blame] | 775 | | | format this yourself. | produce ``message``, or a dict whose values | |
| 776 | | | | are used for the merge (when there is only one| |
| 777 | | | | argument, and it is a dictionary). | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 778 | +----------------+-------------------------+-----------------------------------------------+ |
| 779 | | asctime | ``%(asctime)s`` | Human-readable time when the | |
| 780 | | | | :class:`LogRecord` was created. By default | |
| 781 | | | | this is of the form '2003-07-08 16:49:45,896' | |
| 782 | | | | (the numbers after the comma are millisecond | |
| 783 | | | | portion of the time). | |
| 784 | +----------------+-------------------------+-----------------------------------------------+ |
| 785 | | created | ``%(created)f`` | Time when the :class:`LogRecord` was created | |
| 786 | | | | (as returned by :func:`time.time`). | |
| 787 | +----------------+-------------------------+-----------------------------------------------+ |
| 788 | | exc_info | You shouldn't need to | Exception tuple (à la ``sys.exc_info``) or, | |
Serhiy Storchaka | 807e2f3 | 2016-10-19 19:37:20 +0300 | [diff] [blame] | 789 | | | format this yourself. | if no exception has occurred, ``None``. | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 790 | +----------------+-------------------------+-----------------------------------------------+ |
| 791 | | filename | ``%(filename)s`` | Filename portion of ``pathname``. | |
| 792 | +----------------+-------------------------+-----------------------------------------------+ |
| 793 | | funcName | ``%(funcName)s`` | Name of function containing the logging call. | |
| 794 | +----------------+-------------------------+-----------------------------------------------+ |
| 795 | | levelname | ``%(levelname)s`` | Text logging level for the message | |
| 796 | | | | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, | |
| 797 | | | | ``'ERROR'``, ``'CRITICAL'``). | |
| 798 | +----------------+-------------------------+-----------------------------------------------+ |
| 799 | | levelno | ``%(levelno)s`` | Numeric logging level for the message | |
| 800 | | | | (:const:`DEBUG`, :const:`INFO`, | |
| 801 | | | | :const:`WARNING`, :const:`ERROR`, | |
| 802 | | | | :const:`CRITICAL`). | |
| 803 | +----------------+-------------------------+-----------------------------------------------+ |
| 804 | | lineno | ``%(lineno)d`` | Source line number where the logging call was | |
| 805 | | | | issued (if available). | |
| 806 | +----------------+-------------------------+-----------------------------------------------+ |
Arthur Darcet | 2f3d699 | 2017-10-27 09:06:20 +0200 | [diff] [blame] | 807 | | message | ``%(message)s`` | The logged message, computed as ``msg % | |
| 808 | | | | args``. This is set when | |
| 809 | | | | :meth:`Formatter.format` is invoked. | |
| 810 | +----------------+-------------------------+-----------------------------------------------+ |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 811 | | module | ``%(module)s`` | Module (name portion of ``filename``). | |
| 812 | +----------------+-------------------------+-----------------------------------------------+ |
| 813 | | msecs | ``%(msecs)d`` | Millisecond portion of the time when the | |
| 814 | | | | :class:`LogRecord` was created. | |
| 815 | +----------------+-------------------------+-----------------------------------------------+ |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 816 | | msg | You shouldn't need to | The format string passed in the original | |
| 817 | | | format this yourself. | logging call. Merged with ``args`` to | |
| 818 | | | | produce ``message``, or an arbitrary object | |
| 819 | | | | (see :ref:`arbitrary-object-messages`). | |
| 820 | +----------------+-------------------------+-----------------------------------------------+ |
| 821 | | name | ``%(name)s`` | Name of the logger used to log the call. | |
| 822 | +----------------+-------------------------+-----------------------------------------------+ |
| 823 | | pathname | ``%(pathname)s`` | Full pathname of the source file where the | |
| 824 | | | | logging call was issued (if available). | |
| 825 | +----------------+-------------------------+-----------------------------------------------+ |
| 826 | | process | ``%(process)d`` | Process ID (if available). | |
| 827 | +----------------+-------------------------+-----------------------------------------------+ |
| 828 | | processName | ``%(processName)s`` | Process name (if available). | |
| 829 | +----------------+-------------------------+-----------------------------------------------+ |
| 830 | | relativeCreated| ``%(relativeCreated)d`` | Time in milliseconds when the LogRecord was | |
| 831 | | | | created, relative to the time the logging | |
| 832 | | | | module was loaded. | |
| 833 | +----------------+-------------------------+-----------------------------------------------+ |
| 834 | | stack_info | You shouldn't need to | Stack frame information (where available) | |
| 835 | | | format this yourself. | from the bottom of the stack in the current | |
| 836 | | | | thread, up to and including the stack frame | |
| 837 | | | | of the logging call which resulted in the | |
| 838 | | | | creation of this record. | |
| 839 | +----------------+-------------------------+-----------------------------------------------+ |
| 840 | | thread | ``%(thread)d`` | Thread ID (if available). | |
| 841 | +----------------+-------------------------+-----------------------------------------------+ |
| 842 | | threadName | ``%(threadName)s`` | Thread name (if available). | |
| 843 | +----------------+-------------------------+-----------------------------------------------+ |
| 844 | |
Vinay Sajip | 3be7a8b | 2012-07-20 09:50:18 +0100 | [diff] [blame] | 845 | .. versionchanged:: 3.1 |
| 846 | *processName* was added. |
| 847 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 848 | |
| 849 | .. _logger-adapter: |
| 850 | |
| 851 | LoggerAdapter Objects |
| 852 | --------------------- |
| 853 | |
| 854 | :class:`LoggerAdapter` instances are used to conveniently pass contextual |
Serhiy Storchaka | a4d170d | 2013-12-23 18:20:51 +0200 | [diff] [blame] | 855 | information into logging calls. For a usage example, see the section on |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 856 | :ref:`adding contextual information to your logging output <context-info>`. |
| 857 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 858 | .. class:: LoggerAdapter(logger, extra) |
| 859 | |
| 860 | Returns an instance of :class:`LoggerAdapter` initialized with an |
| 861 | underlying :class:`Logger` instance and a dict-like object. |
| 862 | |
| 863 | .. method:: process(msg, kwargs) |
| 864 | |
| 865 | Modifies the message and/or keyword arguments passed to a logging call in |
| 866 | order to insert contextual information. This implementation takes the object |
| 867 | passed as *extra* to the constructor and adds it to *kwargs* using key |
| 868 | 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the |
| 869 | (possibly modified) versions of the arguments passed in. |
| 870 | |
| 871 | In addition to the above, :class:`LoggerAdapter` supports the following |
Vinay Sajip | 9b83d53 | 2013-10-31 01:10:30 +0000 | [diff] [blame] | 872 | methods of :class:`Logger`: :meth:`~Logger.debug`, :meth:`~Logger.info`, |
| 873 | :meth:`~Logger.warning`, :meth:`~Logger.error`, :meth:`~Logger.exception`, |
| 874 | :meth:`~Logger.critical`, :meth:`~Logger.log`, :meth:`~Logger.isEnabledFor`, |
| 875 | :meth:`~Logger.getEffectiveLevel`, :meth:`~Logger.setLevel` and |
| 876 | :meth:`~Logger.hasHandlers`. These methods have the same signatures as their |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 877 | counterparts in :class:`Logger`, so you can use the two types of instances |
| 878 | interchangeably. |
| 879 | |
| 880 | .. versionchanged:: 3.2 |
Vinay Sajip | 9b83d53 | 2013-10-31 01:10:30 +0000 | [diff] [blame] | 881 | The :meth:`~Logger.isEnabledFor`, :meth:`~Logger.getEffectiveLevel`, |
| 882 | :meth:`~Logger.setLevel` and :meth:`~Logger.hasHandlers` methods were added |
| 883 | to :class:`LoggerAdapter`. These methods delegate to the underlying logger. |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 884 | |
| 885 | |
| 886 | Thread Safety |
| 887 | ------------- |
| 888 | |
| 889 | The logging module is intended to be thread-safe without any special work |
| 890 | needing to be done by its clients. It achieves this though using threading |
| 891 | locks; there is one lock to serialize access to the module's shared data, and |
| 892 | each handler also creates a lock to serialize access to its underlying I/O. |
| 893 | |
| 894 | If you are implementing asynchronous signal handlers using the :mod:`signal` |
| 895 | module, you may not be able to use logging from within such handlers. This is |
| 896 | because lock implementations in the :mod:`threading` module are not always |
| 897 | re-entrant, and so cannot be invoked from such signal handlers. |
| 898 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 899 | |
Benjamin Peterson | 058e31e | 2009-01-16 03:54:08 +0000 | [diff] [blame] | 900 | Module-Level Functions |
| 901 | ---------------------- |
| 902 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 903 | In addition to the classes described above, there are a number of module- level |
| 904 | functions. |
| 905 | |
| 906 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 907 | .. function:: getLogger(name=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 908 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 909 | Return a logger with the specified name or, if name is ``None``, return a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 910 | logger which is the root logger of the hierarchy. If specified, the name is |
Vinay Sajip | 9a6b400 | 2010-12-14 19:40:21 +0000 | [diff] [blame] | 911 | typically a dot-separated hierarchical name like *'a'*, *'a.b'* or *'a.b.c.d'*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 912 | Choice of these names is entirely up to the developer who is using logging. |
| 913 | |
| 914 | All calls to this function with a given name return the same logger instance. |
| 915 | This means that logger instances never need to be passed between different parts |
| 916 | of an application. |
| 917 | |
| 918 | |
| 919 | .. function:: getLoggerClass() |
| 920 | |
| 921 | Return either the standard :class:`Logger` class, or the last class passed to |
| 922 | :func:`setLoggerClass`. This function may be called from within a new class |
Vinay Sajip | 9c10d6b | 2013-11-15 20:58:13 +0000 | [diff] [blame] | 923 | definition, to ensure that installing a customized :class:`Logger` class will |
| 924 | not undo customizations already applied by other code. For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 925 | |
| 926 | class MyLogger(logging.getLoggerClass()): |
| 927 | # ... override behaviour here |
| 928 | |
| 929 | |
Vinay Sajip | 6156152 | 2010-12-03 11:50:38 +0000 | [diff] [blame] | 930 | .. function:: getLogRecordFactory() |
| 931 | |
| 932 | Return a callable which is used to create a :class:`LogRecord`. |
| 933 | |
| 934 | .. versionadded:: 3.2 |
Vinay Sajip | 6156152 | 2010-12-03 11:50:38 +0000 | [diff] [blame] | 935 | This function has been provided, along with :func:`setLogRecordFactory`, |
| 936 | to allow developers more control over how the :class:`LogRecord` |
| 937 | representing a logging event is constructed. |
| 938 | |
| 939 | See :func:`setLogRecordFactory` for more information about the how the |
| 940 | factory is called. |
| 941 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 942 | .. function:: debug(msg, *args, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 943 | |
| 944 | Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the |
| 945 | message format string, and the *args* are the arguments which are merged into |
| 946 | *msg* using the string formatting operator. (Note that this means that you can |
| 947 | use keywords in the format string, together with a single dictionary argument.) |
| 948 | |
Vinay Sajip | 8593ae6 | 2010-11-14 21:33:04 +0000 | [diff] [blame] | 949 | There are three keyword arguments in *kwargs* which are inspected: *exc_info* |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 950 | which, if it does not evaluate as false, causes exception information to be |
| 951 | added to the logging message. If an exception tuple (in the format returned by |
| 952 | :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info` |
| 953 | is called to get the exception information. |
| 954 | |
Vinay Sajip | 8593ae6 | 2010-11-14 21:33:04 +0000 | [diff] [blame] | 955 | The second optional keyword argument is *stack_info*, which defaults to |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 956 | ``False``. If true, stack information is added to the logging |
Vinay Sajip | 8593ae6 | 2010-11-14 21:33:04 +0000 | [diff] [blame] | 957 | message, including the actual logging call. Note that this is not the same |
| 958 | stack information as that displayed through specifying *exc_info*: The |
| 959 | former is stack frames from the bottom of the stack up to the logging call |
| 960 | in the current thread, whereas the latter is information about stack frames |
| 961 | which have been unwound, following an exception, while searching for |
| 962 | exception handlers. |
| 963 | |
| 964 | You can specify *stack_info* independently of *exc_info*, e.g. to just show |
| 965 | how you got to a certain point in your code, even when no exceptions were |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 966 | raised. The stack frames are printed following a header line which says: |
| 967 | |
| 968 | .. code-block:: none |
Vinay Sajip | 8593ae6 | 2010-11-14 21:33:04 +0000 | [diff] [blame] | 969 | |
| 970 | Stack (most recent call last): |
| 971 | |
Éric Araujo | 661161e | 2011-10-22 19:29:48 +0200 | [diff] [blame] | 972 | This mimics the ``Traceback (most recent call last):`` which is used when |
Vinay Sajip | 8593ae6 | 2010-11-14 21:33:04 +0000 | [diff] [blame] | 973 | displaying exception frames. |
| 974 | |
| 975 | The third optional keyword argument is *extra* which can be used to pass a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 976 | dictionary which is used to populate the __dict__ of the LogRecord created for |
| 977 | the logging event with user-defined attributes. These custom attributes can then |
| 978 | be used as you like. For example, they could be incorporated into logged |
| 979 | messages. For example:: |
| 980 | |
Vinay Sajip | 9a6b400 | 2010-12-14 19:40:21 +0000 | [diff] [blame] | 981 | FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 982 | logging.basicConfig(format=FORMAT) |
| 983 | d = {'clientip': '192.168.0.1', 'user': 'fbloggs'} |
Vinay Sajip | 9a6b400 | 2010-12-14 19:40:21 +0000 | [diff] [blame] | 984 | logging.warning('Protocol problem: %s', 'connection reset', extra=d) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 985 | |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 986 | would print something like: |
| 987 | |
| 988 | .. code-block:: none |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 989 | |
| 990 | 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset |
| 991 | |
| 992 | The keys in the dictionary passed in *extra* should not clash with the keys used |
| 993 | by the logging system. (See the :class:`Formatter` documentation for more |
| 994 | information on which keys are used by the logging system.) |
| 995 | |
| 996 | If you choose to use these attributes in logged messages, you need to exercise |
| 997 | some care. In the above example, for instance, the :class:`Formatter` has been |
| 998 | set up with a format string which expects 'clientip' and 'user' in the attribute |
| 999 | dictionary of the LogRecord. If these are missing, the message will not be |
| 1000 | logged because a string formatting exception will occur. So in this case, you |
| 1001 | always need to pass the *extra* dictionary with these keys. |
| 1002 | |
| 1003 | While this might be annoying, this feature is intended for use in specialized |
| 1004 | circumstances, such as multi-threaded servers where the same code executes in |
| 1005 | many contexts, and interesting conditions which arise are dependent on this |
| 1006 | context (such as remote client IP address and authenticated user name, in the |
| 1007 | above example). In such circumstances, it is likely that specialized |
| 1008 | :class:`Formatter`\ s would be used with particular :class:`Handler`\ s. |
| 1009 | |
Sergey Fedoseev | f120288 | 2018-07-06 05:01:16 +0500 | [diff] [blame] | 1010 | .. versionchanged:: 3.2 |
Vinay Sajip | 8593ae6 | 2010-11-14 21:33:04 +0000 | [diff] [blame] | 1011 | The *stack_info* parameter was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1012 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 1013 | .. function:: info(msg, *args, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1014 | |
| 1015 | Logs a message with level :const:`INFO` on the root logger. The arguments are |
| 1016 | interpreted as for :func:`debug`. |
| 1017 | |
| 1018 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 1019 | .. function:: warning(msg, *args, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1020 | |
Vinay Sajip | 04d5bc0 | 2011-10-21 07:33:42 +0100 | [diff] [blame] | 1021 | Logs a message with level :const:`WARNING` on the root logger. The arguments |
| 1022 | are interpreted as for :func:`debug`. |
| 1023 | |
Éric Araujo | 661161e | 2011-10-22 19:29:48 +0200 | [diff] [blame] | 1024 | .. note:: There is an obsolete function ``warn`` which is functionally |
| 1025 | identical to ``warning``. As ``warn`` is deprecated, please do not use |
| 1026 | it - use ``warning`` instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1027 | |
| 1028 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 1029 | .. function:: error(msg, *args, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1030 | |
| 1031 | Logs a message with level :const:`ERROR` on the root logger. The arguments are |
| 1032 | interpreted as for :func:`debug`. |
| 1033 | |
| 1034 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 1035 | .. function:: critical(msg, *args, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1036 | |
| 1037 | Logs a message with level :const:`CRITICAL` on the root logger. The arguments |
| 1038 | are interpreted as for :func:`debug`. |
| 1039 | |
| 1040 | |
Vinay Sajip | 65425b4 | 2014-04-15 23:13:12 +0100 | [diff] [blame] | 1041 | .. function:: exception(msg, *args, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1042 | |
| 1043 | Logs a message with level :const:`ERROR` on the root logger. The arguments are |
| 1044 | interpreted as for :func:`debug`. Exception info is added to the logging |
| 1045 | message. This function should only be called from an exception handler. |
| 1046 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 1047 | .. function:: log(level, msg, *args, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1048 | |
| 1049 | Logs a message with level *level* on the root logger. The other arguments are |
| 1050 | interpreted as for :func:`debug`. |
| 1051 | |
Vinay Sajip | 350e623 | 2014-01-15 13:28:39 +0000 | [diff] [blame] | 1052 | .. note:: The above module-level convenience functions, which delegate to the |
| 1053 | root logger, call :func:`basicConfig` to ensure that at least one handler |
| 1054 | is available. Because of this, they should *not* be used in threads, |
| 1055 | in versions of Python earlier than 2.7.1 and 3.2, unless at least one |
| 1056 | handler has been added to the root logger *before* the threads are |
| 1057 | started. In earlier versions of Python, due to a thread safety shortcoming |
| 1058 | in :func:`basicConfig`, this can (under rare circumstances) lead to |
| 1059 | handlers being added multiple times to the root logger, which can in turn |
| 1060 | lead to multiple messages for the same event. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1061 | |
Vinay Sajip | d489ac9 | 2016-12-31 11:40:11 +0000 | [diff] [blame] | 1062 | .. function:: disable(lvl=CRITICAL) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1063 | |
| 1064 | Provides an overriding level *lvl* for all loggers which takes precedence over |
| 1065 | the logger's own level. When the need arises to temporarily throttle logging |
Benjamin Peterson | 886af96 | 2010-03-21 23:13:07 +0000 | [diff] [blame] | 1066 | output down across the whole application, this function can be useful. Its |
| 1067 | effect is to disable all logging calls of severity *lvl* and below, so that |
| 1068 | if you call it with a value of INFO, then all INFO and DEBUG events would be |
| 1069 | discarded, whereas those of severity WARNING and above would be processed |
Vinay Sajip | a9c179b | 2013-11-30 22:45:29 +0000 | [diff] [blame] | 1070 | according to the logger's effective level. If |
| 1071 | ``logging.disable(logging.NOTSET)`` is called, it effectively removes this |
| 1072 | overriding level, so that logging output again depends on the effective |
| 1073 | levels of individual loggers. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1074 | |
Vinay Sajip | d489ac9 | 2016-12-31 11:40:11 +0000 | [diff] [blame] | 1075 | Note that if you have defined any custom logging level higher than |
| 1076 | ``CRITICAL`` (this is not recommended), you won't be able to rely on the |
| 1077 | default value for the *lvl* parameter, but will have to explicitly supply a |
| 1078 | suitable value. |
| 1079 | |
| 1080 | .. versionchanged:: 3.7 |
| 1081 | The *lvl* parameter was defaulted to level ``CRITICAL``. See Issue |
| 1082 | #28524 for more information about this change. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1083 | |
| 1084 | .. function:: addLevelName(lvl, levelName) |
| 1085 | |
| 1086 | Associates level *lvl* with text *levelName* in an internal dictionary, which is |
| 1087 | used to map numeric levels to a textual representation, for example when a |
| 1088 | :class:`Formatter` formats a message. This function can also be used to define |
| 1089 | your own levels. The only constraints are that all levels used must be |
| 1090 | registered using this function, levels should be positive integers and they |
| 1091 | should increase in increasing order of severity. |
| 1092 | |
Vinay Sajip | 21b3082 | 2013-01-08 11:25:42 +0000 | [diff] [blame] | 1093 | .. note:: If you are thinking of defining your own levels, please see the |
| 1094 | section on :ref:`custom-levels`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1095 | |
| 1096 | .. function:: getLevelName(lvl) |
| 1097 | |
| 1098 | Returns the textual representation of logging level *lvl*. If the level is one |
| 1099 | of the predefined levels :const:`CRITICAL`, :const:`ERROR`, :const:`WARNING`, |
| 1100 | :const:`INFO` or :const:`DEBUG` then you get the corresponding string. If you |
| 1101 | have associated levels with names using :func:`addLevelName` then the name you |
| 1102 | have associated with *lvl* is returned. If a numeric value corresponding to one |
| 1103 | of the defined levels is passed in, the corresponding string representation is |
Vinay Sajip | 9a6b400 | 2010-12-14 19:40:21 +0000 | [diff] [blame] | 1104 | returned. Otherwise, the string 'Level %s' % lvl is returned. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1105 | |
Vinay Sajip | 2f1cd8a | 2014-09-18 18:01:12 +0100 | [diff] [blame] | 1106 | .. note:: Levels are internally integers (as they need to be compared in the |
| 1107 | logging logic). This function is used to convert between an integer level |
| 1108 | and the level name displayed in the formatted log output by means of the |
| 1109 | ``%(levelname)s`` format specifier (see :ref:`logrecord-attributes`). |
| 1110 | |
Vinay Sajip | e0d324d | 2014-06-14 09:26:26 +0100 | [diff] [blame] | 1111 | .. versionchanged:: 3.4 |
| 1112 | In Python versions earlier than 3.4, this function could also be passed a |
| 1113 | text level, and would return the corresponding numeric value of the level. |
Vinay Sajip | d1d4fbf | 2014-09-11 23:06:09 +0100 | [diff] [blame] | 1114 | This undocumented behaviour was considered a mistake, and was removed in |
| 1115 | Python 3.4, but reinstated in 3.4.2 due to retain backward compatibility. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1116 | |
| 1117 | .. function:: makeLogRecord(attrdict) |
| 1118 | |
| 1119 | Creates and returns a new :class:`LogRecord` instance whose attributes are |
| 1120 | defined by *attrdict*. This function is useful for taking a pickled |
| 1121 | :class:`LogRecord` attribute dictionary, sent over a socket, and reconstituting |
| 1122 | it as a :class:`LogRecord` instance at the receiving end. |
| 1123 | |
| 1124 | |
Georg Brandl | cd7f32b | 2009-06-08 09:13:45 +0000 | [diff] [blame] | 1125 | .. function:: basicConfig(**kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1126 | |
| 1127 | Does basic configuration for the logging system by creating a |
| 1128 | :class:`StreamHandler` with a default :class:`Formatter` and adding it to the |
Vinay Sajip | cbabd7e | 2009-10-10 20:32:36 +0000 | [diff] [blame] | 1129 | root logger. The functions :func:`debug`, :func:`info`, :func:`warning`, |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1130 | :func:`error` and :func:`critical` will call :func:`basicConfig` automatically |
| 1131 | if no handlers are defined for the root logger. |
| 1132 | |
Vinay Sajip | cbabd7e | 2009-10-10 20:32:36 +0000 | [diff] [blame] | 1133 | This function does nothing if the root logger already has handlers |
Dong-hee Na | cf67d6a | 2018-06-25 13:11:09 +0900 | [diff] [blame] | 1134 | configured, unless the keyword argument *force* is set to ``True``. |
Vinay Sajip | cbabd7e | 2009-10-10 20:32:36 +0000 | [diff] [blame] | 1135 | |
Vinay Sajip | e50f4d2 | 2013-01-07 14:16:52 +0000 | [diff] [blame] | 1136 | .. note:: This function should be called from the main thread |
| 1137 | before other threads are started. In versions of Python prior to |
| 1138 | 2.7.1 and 3.2, if this function is called from multiple threads, |
| 1139 | it is possible (in rare circumstances) that a handler will be added |
| 1140 | to the root logger more than once, leading to unexpected results |
| 1141 | such as messages being duplicated in the log. |
Vinay Sajip | c8c8c69 | 2010-09-17 10:09:04 +0000 | [diff] [blame] | 1142 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1143 | The following keyword arguments are supported. |
| 1144 | |
Georg Brandl | 44ea77b | 2013-03-28 13:28:44 +0100 | [diff] [blame] | 1145 | .. tabularcolumns:: |l|L| |
| 1146 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1147 | +--------------+---------------------------------------------+ |
| 1148 | | Format | Description | |
| 1149 | +==============+=============================================+ |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1150 | | *filename* | Specifies that a FileHandler be created, | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1151 | | | using the specified filename, rather than a | |
| 1152 | | | StreamHandler. | |
| 1153 | +--------------+---------------------------------------------+ |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1154 | | *filemode* | If *filename* is specified, open the file | |
| 1155 | | | in this :ref:`mode <filemodes>`. Defaults | |
| 1156 | | | to ``'a'``. | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1157 | +--------------+---------------------------------------------+ |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1158 | | *format* | Use the specified format string for the | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1159 | | | handler. | |
| 1160 | +--------------+---------------------------------------------+ |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1161 | | *datefmt* | Use the specified date/time format, as | |
| 1162 | | | accepted by :func:`time.strftime`. | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1163 | +--------------+---------------------------------------------+ |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1164 | | *style* | If *format* is specified, use this style | |
| 1165 | | | for the format string. One of ``'%'``, | |
| 1166 | | | ``'{'`` or ``'$'`` for :ref:`printf-style | |
| 1167 | | | <old-string-formatting>`, | |
| 1168 | | | :meth:`str.format` or | |
| 1169 | | | :class:`string.Template` respectively. | |
| 1170 | | | Defaults to ``'%'``. | |
Vinay Sajip | c5b2730 | 2010-10-31 14:59:16 +0000 | [diff] [blame] | 1171 | +--------------+---------------------------------------------+ |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1172 | | *level* | Set the root logger level to the specified | |
| 1173 | | | :ref:`level <levels>`. | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1174 | +--------------+---------------------------------------------+ |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1175 | | *stream* | Use the specified stream to initialize the | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1176 | | | StreamHandler. Note that this argument is | |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1177 | | | incompatible with *filename* - if both | |
| 1178 | | | are present, a ``ValueError`` is raised. | |
Vinay Sajip | 4a0a31d | 2011-04-11 08:42:07 +0100 | [diff] [blame] | 1179 | +--------------+---------------------------------------------+ |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1180 | | *handlers* | If specified, this should be an iterable of | |
Vinay Sajip | 4a0a31d | 2011-04-11 08:42:07 +0100 | [diff] [blame] | 1181 | | | already created handlers to add to the root | |
| 1182 | | | logger. Any handlers which don't already | |
| 1183 | | | have a formatter set will be assigned the | |
| 1184 | | | default formatter created in this function. | |
| 1185 | | | Note that this argument is incompatible | |
Andrés Delfino | a8ddf85 | 2018-06-25 03:06:10 -0300 | [diff] [blame] | 1186 | | | with *filename* or *stream* - if both | |
| 1187 | | | are present, a ``ValueError`` is raised. | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1188 | +--------------+---------------------------------------------+ |
Dong-hee Na | 2800dcf | 2018-07-07 21:36:40 +0900 | [diff] [blame] | 1189 | | *force* | If this keyword argument is specified as | |
Dong-hee Na | cf67d6a | 2018-06-25 13:11:09 +0900 | [diff] [blame] | 1190 | | | true, any existing handlers attached to the | |
| 1191 | | | root logger are removed and closed, before | |
| 1192 | | | carrying out the configuration as specified | |
| 1193 | | | by the other arguments. | |
| 1194 | +--------------+---------------------------------------------+ |
| 1195 | |
Vinay Sajip | c5b2730 | 2010-10-31 14:59:16 +0000 | [diff] [blame] | 1196 | .. versionchanged:: 3.2 |
Dong-hee Na | 2800dcf | 2018-07-07 21:36:40 +0900 | [diff] [blame] | 1197 | The *style* argument was added. |
Vinay Sajip | c5b2730 | 2010-10-31 14:59:16 +0000 | [diff] [blame] | 1198 | |
Vinay Sajip | 4a0a31d | 2011-04-11 08:42:07 +0100 | [diff] [blame] | 1199 | .. versionchanged:: 3.3 |
Dong-hee Na | 2800dcf | 2018-07-07 21:36:40 +0900 | [diff] [blame] | 1200 | The *handlers* argument was added. Additional checks were added to |
Vinay Sajip | 4a0a31d | 2011-04-11 08:42:07 +0100 | [diff] [blame] | 1201 | catch situations where incompatible arguments are specified (e.g. |
Dong-hee Na | 2800dcf | 2018-07-07 21:36:40 +0900 | [diff] [blame] | 1202 | *handlers* together with *stream* or *filename*, or *stream* |
| 1203 | together with *filename*). |
Vinay Sajip | 4a0a31d | 2011-04-11 08:42:07 +0100 | [diff] [blame] | 1204 | |
Dong-hee Na | 2800dcf | 2018-07-07 21:36:40 +0900 | [diff] [blame] | 1205 | .. versionchanged:: 3.8 |
| 1206 | The *force* argument was added. |
Vinay Sajip | c5b2730 | 2010-10-31 14:59:16 +0000 | [diff] [blame] | 1207 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1208 | .. function:: shutdown() |
| 1209 | |
| 1210 | Informs the logging system to perform an orderly shutdown by flushing and |
Christian Heimes | b186d00 | 2008-03-18 15:15:01 +0000 | [diff] [blame] | 1211 | closing all handlers. This should be called at application exit and no |
| 1212 | further use of the logging system should be made after this call. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1213 | |
| 1214 | |
| 1215 | .. function:: setLoggerClass(klass) |
| 1216 | |
| 1217 | Tells the logging system to use the class *klass* when instantiating a logger. |
| 1218 | The class should define :meth:`__init__` such that only a name argument is |
| 1219 | required, and the :meth:`__init__` should call :meth:`Logger.__init__`. This |
| 1220 | function is typically called before any loggers are instantiated by applications |
| 1221 | which need to use custom logger behavior. |
| 1222 | |
Georg Brandl | 1eb40bc | 2010-12-03 15:30:09 +0000 | [diff] [blame] | 1223 | |
Vinay Sajip | 6156152 | 2010-12-03 11:50:38 +0000 | [diff] [blame] | 1224 | .. function:: setLogRecordFactory(factory) |
| 1225 | |
| 1226 | Set a callable which is used to create a :class:`LogRecord`. |
| 1227 | |
| 1228 | :param factory: The factory callable to be used to instantiate a log record. |
| 1229 | |
| 1230 | .. versionadded:: 3.2 |
Georg Brandl | 1eb40bc | 2010-12-03 15:30:09 +0000 | [diff] [blame] | 1231 | This function has been provided, along with :func:`getLogRecordFactory`, to |
| 1232 | allow developers more control over how the :class:`LogRecord` representing |
| 1233 | a logging event is constructed. |
Vinay Sajip | 6156152 | 2010-12-03 11:50:38 +0000 | [diff] [blame] | 1234 | |
Georg Brandl | 1eb40bc | 2010-12-03 15:30:09 +0000 | [diff] [blame] | 1235 | The factory has the following signature: |
Vinay Sajip | 6156152 | 2010-12-03 11:50:38 +0000 | [diff] [blame] | 1236 | |
Vinay Sajip | 9a6b400 | 2010-12-14 19:40:21 +0000 | [diff] [blame] | 1237 | ``factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)`` |
Vinay Sajip | 6156152 | 2010-12-03 11:50:38 +0000 | [diff] [blame] | 1238 | |
| 1239 | :name: The logger name. |
| 1240 | :level: The logging level (numeric). |
| 1241 | :fn: The full pathname of the file where the logging call was made. |
| 1242 | :lno: The line number in the file where the logging call was made. |
| 1243 | :msg: The logging message. |
| 1244 | :args: The arguments for the logging message. |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 1245 | :exc_info: An exception tuple, or ``None``. |
Vinay Sajip | 6156152 | 2010-12-03 11:50:38 +0000 | [diff] [blame] | 1246 | :func: The name of the function or method which invoked the logging |
| 1247 | call. |
| 1248 | :sinfo: A stack traceback such as is provided by |
| 1249 | :func:`traceback.print_stack`, showing the call hierarchy. |
| 1250 | :kwargs: Additional keyword arguments. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1251 | |
Georg Brandl | 1eb40bc | 2010-12-03 15:30:09 +0000 | [diff] [blame] | 1252 | |
Vinay Sajip | e50f4d2 | 2013-01-07 14:16:52 +0000 | [diff] [blame] | 1253 | Module-Level Attributes |
| 1254 | ----------------------- |
| 1255 | |
| 1256 | .. attribute:: lastResort |
| 1257 | |
| 1258 | A "handler of last resort" is available through this attribute. This |
| 1259 | is a :class:`StreamHandler` writing to ``sys.stderr`` with a level of |
| 1260 | ``WARNING``, and is used to handle logging events in the absence of any |
| 1261 | logging configuration. The end result is to just print the message to |
| 1262 | ``sys.stderr``. This replaces the earlier error message saying that |
| 1263 | "no handlers could be found for logger XYZ". If you need the earlier |
| 1264 | behaviour for some reason, ``lastResort`` can be set to ``None``. |
| 1265 | |
| 1266 | .. versionadded:: 3.2 |
| 1267 | |
Benjamin Peterson | 9451a1c | 2010-03-13 22:30:34 +0000 | [diff] [blame] | 1268 | Integration with the warnings module |
| 1269 | ------------------------------------ |
| 1270 | |
| 1271 | The :func:`captureWarnings` function can be used to integrate :mod:`logging` |
| 1272 | with the :mod:`warnings` module. |
| 1273 | |
| 1274 | .. function:: captureWarnings(capture) |
| 1275 | |
| 1276 | This function is used to turn the capture of warnings by logging on and |
| 1277 | off. |
| 1278 | |
Senthil Kumaran | 46a48be | 2010-10-15 13:10:10 +0000 | [diff] [blame] | 1279 | If *capture* is ``True``, warnings issued by the :mod:`warnings` module will |
| 1280 | be redirected to the logging system. Specifically, a warning will be |
Benjamin Peterson | 9451a1c | 2010-03-13 22:30:34 +0000 | [diff] [blame] | 1281 | formatted using :func:`warnings.formatwarning` and the resulting string |
Éric Araujo | a609199 | 2012-02-26 02:13:30 +0100 | [diff] [blame] | 1282 | logged to a logger named ``'py.warnings'`` with a severity of :const:`WARNING`. |
Benjamin Peterson | 9451a1c | 2010-03-13 22:30:34 +0000 | [diff] [blame] | 1283 | |
Senthil Kumaran | 46a48be | 2010-10-15 13:10:10 +0000 | [diff] [blame] | 1284 | If *capture* is ``False``, the redirection of warnings to the logging system |
Benjamin Peterson | 9451a1c | 2010-03-13 22:30:34 +0000 | [diff] [blame] | 1285 | will stop, and warnings will be redirected to their original destinations |
Éric Araujo | 661161e | 2011-10-22 19:29:48 +0200 | [diff] [blame] | 1286 | (i.e. those in effect before ``captureWarnings(True)`` was called). |
Benjamin Peterson | 9451a1c | 2010-03-13 22:30:34 +0000 | [diff] [blame] | 1287 | |
| 1288 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 1289 | .. seealso:: |
Vinay Sajip | 7504302 | 2010-12-19 06:02:31 +0000 | [diff] [blame] | 1290 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 1291 | Module :mod:`logging.config` |
| 1292 | Configuration API for the logging module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1293 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 1294 | Module :mod:`logging.handlers` |
| 1295 | Useful handlers included with the logging module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1296 | |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 1297 | :pep:`282` - A Logging System |
| 1298 | The proposal which described this feature for inclusion in the Python standard |
| 1299 | library. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1300 | |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 1301 | `Original Python logging package <https://www.red-dove.com/python_logging.html>`_ |
Vinay Sajip | c63619b | 2010-12-19 12:56:57 +0000 | [diff] [blame] | 1302 | This is the original source for the :mod:`logging` package. The version of the |
| 1303 | package available from this site is suitable for use with Python 1.5.2, 2.1.x |
| 1304 | and 2.2.x, which do not include the :mod:`logging` package in the standard |
| 1305 | library. |