1 :mod:`logging` --- Logging facility for Python 2 ============================================== 3 4 .. module:: logging 5 :synopsis: Flexible event logging system for applications. 6 7 8 .. moduleauthor:: Vinay Sajip <vinay_sajip (a] red-dove.com> 9 .. sectionauthor:: Vinay Sajip <vinay_sajip (a] red-dove.com> 10 11 12 .. index:: pair: Errors; logging 13 14 .. sidebar:: Important 15 16 This page contains the API reference information. For tutorial 17 information and discussion of more advanced topics, see 18 19 * :ref:`Basic Tutorial <logging-basic-tutorial>` 20 * :ref:`Advanced Tutorial <logging-advanced-tutorial>` 21 * :ref:`Logging Cookbook <logging-cookbook>` 22 23 **Source code:** :source:`Lib/logging/__init__.py` 24 25 -------------- 26 27 .. versionadded:: 2.3 28 29 This module defines functions and classes which implement a flexible event 30 logging system for applications and libraries. 31 32 The key benefit of having the logging API provided by a standard library module 33 is that all Python modules can participate in logging, so your application log 34 can include your own messages integrated with messages from third-party 35 modules. 36 37 The module provides a lot of functionality and flexibility. If you are 38 unfamiliar with logging, the best way to get to grips with it is to see the 39 tutorials (see the links on the right). 40 41 The basic classes defined by the module, together with their functions, are 42 listed below. 43 44 * Loggers expose the interface that application code directly uses. 45 * Handlers send the log records (created by loggers) to the appropriate 46 destination. 47 * Filters provide a finer grained facility for determining which log records 48 to output. 49 * Formatters specify the layout of log records in the final output. 50 51 52 .. _logger: 53 54 Logger Objects 55 -------------- 56 57 Loggers have the following attributes and methods. Note that Loggers are never 58 instantiated directly, but always through the module-level function 59 ``logging.getLogger(name)``. Multiple calls to :func:`getLogger` with the same 60 name will always return a reference to the same Logger object. 61 62 The ``name`` is potentially a period-separated hierarchical value, like 63 ``foo.bar.baz`` (though it could also be just plain ``foo``, for example). 64 Loggers that are further down in the hierarchical list are children of loggers 65 higher up in the list. For example, given a logger with a name of ``foo``, 66 loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all 67 descendants of ``foo``. The logger name hierarchy is analogous to the Python 68 package hierarchy, and identical to it if you organise your loggers on a 69 per-module basis using the recommended construction 70 ``logging.getLogger(__name__)``. That's because in a module, ``__name__`` 71 is the module's name in the Python package namespace. 72 73 74 .. class:: Logger 75 76 .. attribute:: Logger.propagate 77 78 If this evaluates to true, events logged to this logger will be passed to the 79 handlers of higher level (ancestor) loggers, in addition to any handlers 80 attached to this logger. Messages are passed directly to the ancestor 81 loggers' handlers - neither the level nor filters of the ancestor loggers in 82 question are considered. 83 84 If this evaluates to false, logging messages are not passed to the handlers 85 of ancestor loggers. 86 87 The constructor sets this attribute to ``True``. 88 89 .. note:: If you attach a handler to a logger *and* one or more of its 90 ancestors, it may emit the same record multiple times. In general, you 91 should not need to attach a handler to more than one logger - if you just 92 attach it to the appropriate logger which is highest in the logger 93 hierarchy, then it will see all events logged by all descendant loggers, 94 provided that their propagate setting is left set to ``True``. A common 95 scenario is to attach handlers only to the root logger, and to let 96 propagation take care of the rest. 97 98 .. method:: Logger.setLevel(lvl) 99 100 Sets the threshold for this logger to *lvl*. Logging messages which are less 101 severe than *lvl* will be ignored. When a logger is created, the level is set to 102 :const:`NOTSET` (which causes all messages to be processed when the logger is 103 the root logger, or delegation to the parent when the logger is a non-root 104 logger). Note that the root logger is created with level :const:`WARNING`. 105 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. 109 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. 113 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. 116 117 See :ref:`levels` for a list of levels. 118 119 120 .. method:: Logger.isEnabledFor(lvl) 121 122 Indicates if a message of severity *lvl* would be processed by this logger. 123 This method checks first the module-level level set by 124 ``logging.disable(lvl)`` and then the logger's effective level as determined 125 by :meth:`getEffectiveLevel`. 126 127 128 .. method:: Logger.getEffectiveLevel() 129 130 Indicates the effective level for this logger. If a value other than 131 :const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise, 132 the hierarchy is traversed towards the root until a value other than 133 :const:`NOTSET` is found, and that value is returned. The value returned is 134 an integer, typically one of :const:`logging.DEBUG`, :const:`logging.INFO` 135 etc. 136 137 138 .. method:: Logger.getChild(suffix) 139 140 Returns a logger which is a descendant to this logger, as determined by the suffix. 141 Thus, ``logging.getLogger('abc').getChild('def.ghi')`` would return the same 142 logger as would be returned by ``logging.getLogger('abc.def.ghi')``. This is a 143 convenience method, useful when the parent logger is named using e.g. ``__name__`` 144 rather than a literal string. 145 146 .. versionadded:: 2.7 147 148 149 .. method:: Logger.debug(msg, *args, **kwargs) 150 151 Logs a message with level :const:`DEBUG` on this logger. The *msg* is the 152 message format string, and the *args* are the arguments which are merged into 153 *msg* using the string formatting operator. (Note that this means that you can 154 use keywords in the format string, together with a single dictionary argument.) 155 156 There are two keyword arguments in *kwargs* which are inspected: *exc_info* 157 which, if it does not evaluate as false, causes exception information to be 158 added to the logging message. If an exception tuple (in the format returned by 159 :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info` 160 is called to get the exception information. 161 162 The second keyword argument is *extra* which can be used to pass a 163 dictionary which is used to populate the __dict__ of the LogRecord created for 164 the logging event with user-defined attributes. These custom attributes can then 165 be used as you like. For example, they could be incorporated into logged 166 messages. For example:: 167 168 FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s' 169 logging.basicConfig(format=FORMAT) 170 d = {'clientip': '192.168.0.1', 'user': 'fbloggs'} 171 logger = logging.getLogger('tcpserver') 172 logger.warning('Protocol problem: %s', 'connection reset', extra=d) 173 174 would print something like :: 175 176 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset 177 178 The keys in the dictionary passed in *extra* should not clash with the keys used 179 by the logging system. (See the :class:`Formatter` documentation for more 180 information on which keys are used by the logging system.) 181 182 If you choose to use these attributes in logged messages, you need to exercise 183 some care. In the above example, for instance, the :class:`Formatter` has been 184 set up with a format string which expects 'clientip' and 'user' in the attribute 185 dictionary of the LogRecord. If these are missing, the message will not be 186 logged because a string formatting exception will occur. So in this case, you 187 always need to pass the *extra* dictionary with these keys. 188 189 While this might be annoying, this feature is intended for use in specialized 190 circumstances, such as multi-threaded servers where the same code executes in 191 many contexts, and interesting conditions which arise are dependent on this 192 context (such as remote client IP address and authenticated user name, in the 193 above example). In such circumstances, it is likely that specialized 194 :class:`Formatter`\ s would be used with particular :class:`Handler`\ s. 195 196 197 .. method:: Logger.info(msg, *args, **kwargs) 198 199 Logs a message with level :const:`INFO` on this logger. The arguments are 200 interpreted as for :meth:`debug`. 201 202 203 .. method:: Logger.warning(msg, *args, **kwargs) 204 205 Logs a message with level :const:`WARNING` on this logger. The arguments are 206 interpreted as for :meth:`debug`. 207 208 209 .. method:: Logger.error(msg, *args, **kwargs) 210 211 Logs a message with level :const:`ERROR` on this logger. The arguments are 212 interpreted as for :meth:`debug`. 213 214 215 .. method:: Logger.critical(msg, *args, **kwargs) 216 217 Logs a message with level :const:`CRITICAL` on this logger. The arguments are 218 interpreted as for :meth:`debug`. 219 220 221 .. method:: Logger.log(lvl, msg, *args, **kwargs) 222 223 Logs a message with integer level *lvl* on this logger. The other arguments are 224 interpreted as for :meth:`debug`. 225 226 227 .. method:: Logger.exception(msg, *args, **kwargs) 228 229 Logs a message with level :const:`ERROR` on this logger. The arguments are 230 interpreted as for :meth:`debug`, except that any passed *exc_info* is not 231 inspected. Exception info is always added to the logging message. This method 232 should only be called from an exception handler. 233 234 235 .. method:: Logger.addFilter(filt) 236 237 Adds the specified filter *filt* to this logger. 238 239 240 .. method:: Logger.removeFilter(filt) 241 242 Removes the specified filter *filt* from this logger. 243 244 245 .. method:: Logger.filter(record) 246 247 Applies this logger's filters to the record and returns a true value if the 248 record is to be processed. The filters are consulted in turn, until one of 249 them returns a false value. If none of them return a false value, the record 250 will be processed (passed to handlers). If one returns a false value, no 251 further processing of the record occurs. 252 253 254 .. method:: Logger.addHandler(hdlr) 255 256 Adds the specified handler *hdlr* to this logger. 257 258 259 .. method:: Logger.removeHandler(hdlr) 260 261 Removes the specified handler *hdlr* from this logger. 262 263 264 .. method:: Logger.findCaller() 265 266 Finds the caller's source filename and line number. Returns the filename, line 267 number and function name as a 3-element tuple. 268 269 .. versionchanged:: 2.4 270 The function name was added. In earlier versions, the filename and line 271 number were returned as a 2-element tuple. 272 273 .. method:: Logger.handle(record) 274 275 Handles a record by passing it to all handlers associated with this logger and 276 its ancestors (until a false value of *propagate* is found). This method is used 277 for unpickled records received from a socket, as well as those created locally. 278 Logger-level filtering is applied using :meth:`~Logger.filter`. 279 280 281 .. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None) 282 283 This is a factory method which can be overridden in subclasses to create 284 specialized :class:`LogRecord` instances. 285 286 .. versionchanged:: 2.5 287 *func* and *extra* were added. 288 289 290 .. _levels: 291 292 Logging Levels 293 -------------- 294 295 The numeric values of logging levels are given in the following table. These are 296 primarily of interest if you want to define your own levels, and need them to 297 have specific values relative to the predefined levels. If you define a level 298 with the same numeric value, it overwrites the predefined value; the predefined 299 name is lost. 300 301 +--------------+---------------+ 302 | Level | Numeric value | 303 +==============+===============+ 304 | ``CRITICAL`` | 50 | 305 +--------------+---------------+ 306 | ``ERROR`` | 40 | 307 +--------------+---------------+ 308 | ``WARNING`` | 30 | 309 +--------------+---------------+ 310 | ``INFO`` | 20 | 311 +--------------+---------------+ 312 | ``DEBUG`` | 10 | 313 +--------------+---------------+ 314 | ``NOTSET`` | 0 | 315 +--------------+---------------+ 316 317 318 .. _handler: 319 320 Handler Objects 321 --------------- 322 323 Handlers have the following attributes and methods. Note that :class:`Handler` 324 is never instantiated directly; this class acts as a base for more useful 325 subclasses. However, the :meth:`__init__` method in subclasses needs to call 326 :meth:`Handler.__init__`. 327 328 329 .. method:: Handler.__init__(level=NOTSET) 330 331 Initializes the :class:`Handler` instance by setting its level, setting the list 332 of filters to the empty list and creating a lock (using :meth:`createLock`) for 333 serializing access to an I/O mechanism. 334 335 336 .. method:: Handler.createLock() 337 338 Initializes a thread lock which can be used to serialize access to underlying 339 I/O functionality which may not be threadsafe. 340 341 342 .. method:: Handler.acquire() 343 344 Acquires the thread lock created with :meth:`createLock`. 345 346 347 .. method:: Handler.release() 348 349 Releases the thread lock acquired with :meth:`acquire`. 350 351 352 .. method:: Handler.setLevel(lvl) 353 354 Sets the threshold for this handler to *lvl*. Logging messages which are less 355 severe than *lvl* will be ignored. When a handler is created, the level is set 356 to :const:`NOTSET` (which causes all messages to be processed). 357 358 See :ref:`levels` for a list of levels. 359 360 .. method:: Handler.setFormatter(form) 361 362 Sets the :class:`Formatter` for this handler to *form*. 363 364 365 .. method:: Handler.addFilter(filt) 366 367 Adds the specified filter *filt* to this handler. 368 369 370 .. method:: Handler.removeFilter(filt) 371 372 Removes the specified filter *filt* from this handler. 373 374 375 .. method:: Handler.filter(record) 376 377 Applies this handler's filters to the record and returns a true value if the 378 record is to be processed. The filters are consulted in turn, until one of 379 them returns a false value. If none of them return a false value, the record 380 will be emitted. If one returns a false value, the handler will not emit the 381 record. 382 383 384 .. method:: Handler.flush() 385 386 Ensure all logging output has been flushed. This version does nothing and is 387 intended to be implemented by subclasses. 388 389 390 .. method:: Handler.close() 391 392 Tidy up any resources used by the handler. This version does no output but 393 removes the handler from an internal list of handlers which is closed when 394 :func:`shutdown` is called. Subclasses should ensure that this gets called 395 from overridden :meth:`close` methods. 396 397 398 .. method:: Handler.handle(record) 399 400 Conditionally emits the specified logging record, depending on filters which may 401 have been added to the handler. Wraps the actual emission of the record with 402 acquisition/release of the I/O thread lock. 403 404 405 .. method:: Handler.handleError(record) 406 407 This method should be called from handlers when an exception is encountered 408 during an :meth:`emit` call. If the module-level attribute 409 ``raiseExceptions`` is ``False``, exceptions get silently ignored. This is 410 what is mostly wanted for a logging system - most users will not care about 411 errors in the logging system, they are more interested in application 412 errors. You could, however, replace this with a custom handler if you wish. 413 The specified record is the one which was being processed when the exception 414 occurred. (The default value of ``raiseExceptions`` is ``True``, as that is 415 more useful during development). 416 417 418 .. method:: Handler.format(record) 419 420 Do formatting for a record - if a formatter is set, use it. Otherwise, use the 421 default formatter for the module. 422 423 424 .. method:: Handler.emit(record) 425 426 Do whatever it takes to actually log the specified logging record. This version 427 is intended to be implemented by subclasses and so raises a 428 :exc:`NotImplementedError`. 429 430 For a list of handlers included as standard, see :mod:`logging.handlers`. 431 432 .. _formatter-objects: 433 434 Formatter Objects 435 ----------------- 436 437 .. currentmodule:: logging 438 439 :class:`Formatter` objects have the following attributes and methods. They are 440 responsible for converting a :class:`LogRecord` to (usually) a string which can 441 be interpreted by either a human or an external system. The base 442 :class:`Formatter` allows a formatting string to be specified. If none is 443 supplied, the default value of ``'%(message)s'`` is used, which just includes 444 the message in the logging call. To have additional items of information in the 445 formatted output (such as a timestamp), keep reading. 446 447 A Formatter can be initialized with a format string which makes use of knowledge 448 of the :class:`LogRecord` attributes - such as the default value mentioned above 449 making use of the fact that the user's message and arguments are pre-formatted 450 into a :class:`LogRecord`'s *message* attribute. This format string contains 451 standard Python %-style mapping keys. See section :ref:`string-formatting` 452 for more information on string formatting. 453 454 The useful mapping keys in a :class:`LogRecord` are given in the section on 455 :ref:`logrecord-attributes`. 456 457 458 .. class:: Formatter(fmt=None, datefmt=None) 459 460 Returns a new instance of the :class:`Formatter` class. The instance is 461 initialized with a format string for the message as a whole, as well as a 462 format string for the date/time portion of a message. If no *fmt* is 463 specified, ``'%(message)s'`` is used. If no *datefmt* is specified, the 464 ISO8601 date format is used. 465 466 .. method:: format(record) 467 468 The record's attribute dictionary is used as the operand to a string 469 formatting operation. Returns the resulting string. Before formatting the 470 dictionary, a couple of preparatory steps are carried out. The *message* 471 attribute of the record is computed using *msg* % *args*. If the 472 formatting string contains ``'(asctime)'``, :meth:`formatTime` is called 473 to format the event time. If there is exception information, it is 474 formatted using :meth:`formatException` and appended to the message. Note 475 that the formatted exception information is cached in attribute 476 *exc_text*. This is useful because the exception information can be 477 pickled and sent across the wire, but you should be careful if you have 478 more than one :class:`Formatter` subclass which customizes the formatting 479 of exception information. In this case, you will have to clear the cached 480 value after a formatter has done its formatting, so that the next 481 formatter to handle the event doesn't use the cached value but 482 recalculates it afresh. 483 484 485 .. method:: formatTime(record, datefmt=None) 486 487 This method should be called from :meth:`format` by a formatter which 488 wants to make use of a formatted time. This method can be overridden in 489 formatters to provide for any specific requirement, but the basic behavior 490 is as follows: if *datefmt* (a string) is specified, it is used with 491 :func:`time.strftime` to format the creation time of the 492 record. Otherwise, the ISO8601 format is used. The resulting string is 493 returned. 494 495 This function uses a user-configurable function to convert the creation 496 time to a tuple. By default, :func:`time.localtime` is used; to change 497 this for a particular formatter instance, set the ``converter`` attribute 498 to a function with the same signature as :func:`time.localtime` or 499 :func:`time.gmtime`. To change it for all formatters, for example if you 500 want all logging times to be shown in GMT, set the ``converter`` 501 attribute in the ``Formatter`` class. 502 503 .. method:: formatException(exc_info) 504 505 Formats the specified exception information (a standard exception tuple as 506 returned by :func:`sys.exc_info`) as a string. This default implementation 507 just uses :func:`traceback.print_exception`. The resulting string is 508 returned. 509 510 .. _filter: 511 512 Filter Objects 513 -------------- 514 515 ``Filters`` can be used by ``Handlers`` and ``Loggers`` for more sophisticated 516 filtering than is provided by levels. The base filter class only allows events 517 which are below a certain point in the logger hierarchy. For example, a filter 518 initialized with 'A.B' will allow events logged by loggers 'A.B', 'A.B.C', 519 'A.B.C.D', 'A.B.D' etc. but not 'A.BB', 'B.A.B' etc. If initialized with the 520 empty string, all events are passed. 521 522 523 .. class:: Filter(name='') 524 525 Returns an instance of the :class:`Filter` class. If *name* is specified, it 526 names a logger which, together with its children, will have its events allowed 527 through the filter. If *name* is the empty string, allows every event. 528 529 530 .. method:: filter(record) 531 532 Is the specified record to be logged? Returns zero for no, nonzero for 533 yes. If deemed appropriate, the record may be modified in-place by this 534 method. 535 536 Note that filters attached to handlers are consulted before an event is 537 emitted by the handler, whereas filters attached to loggers are consulted 538 whenever an event is logged (using :meth:`debug`, :meth:`info`, 539 etc.), before sending an event to handlers. This means that events which have 540 been generated by descendant loggers will not be filtered by a logger's filter 541 setting, unless the filter has also been applied to those descendant loggers. 542 543 You don't actually need to subclass ``Filter``: you can pass any instance 544 which has a ``filter`` method with the same semantics. 545 546 Although filters are used primarily to filter records based on more 547 sophisticated criteria than levels, they get to see every record which is 548 processed by the handler or logger they're attached to: this can be useful if 549 you want to do things like counting how many records were processed by a 550 particular logger or handler, or adding, changing or removing attributes in 551 the LogRecord being processed. Obviously changing the LogRecord needs to be 552 done with some care, but it does allow the injection of contextual information 553 into logs (see :ref:`filters-contextual`). 554 555 .. _log-record: 556 557 LogRecord Objects 558 ----------------- 559 560 :class:`LogRecord` instances are created automatically by the :class:`Logger` 561 every time something is logged, and can be created manually via 562 :func:`makeLogRecord` (for example, from a pickled event received over the 563 wire). 564 565 566 .. class:: LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None) 567 568 Contains all the information pertinent to the event being logged. 569 570 The primary information is passed in :attr:`msg` and :attr:`args`, which 571 are combined using ``msg % args`` to create the :attr:`message` field of the 572 record. 573 574 :param name: The name of the logger used to log the event represented by 575 this LogRecord. Note that this name will always have this 576 value, even though it may be emitted by a handler attached to 577 a different (ancestor) logger. 578 :param level: The numeric level of the logging event (one of DEBUG, INFO etc.) 579 Note that this is converted to *two* attributes of the LogRecord: 580 ``levelno`` for the numeric value and ``levelname`` for the 581 corresponding level name. 582 :param pathname: The full pathname of the source file where the logging call 583 was made. 584 :param lineno: The line number in the source file where the logging call was 585 made. 586 :param msg: The event description message, possibly a format string with 587 placeholders for variable data. 588 :param args: Variable data to merge into the *msg* argument to obtain the 589 event description. 590 :param exc_info: An exception tuple with the current exception information, 591 or ``None`` if no exception information is available. 592 :param func: The name of the function or method from which the logging call 593 was invoked. 594 595 .. versionchanged:: 2.5 596 *func* was added. 597 598 .. method:: getMessage() 599 600 Returns the message for this :class:`LogRecord` instance after merging any 601 user-supplied arguments with the message. If the user-supplied message 602 argument to the logging call is not a string, :func:`str` is called on it to 603 convert it to a string. This allows use of user-defined classes as 604 messages, whose ``__str__`` method can return the actual format string to 605 be used. 606 607 608 .. _logrecord-attributes: 609 610 LogRecord attributes 611 -------------------- 612 613 The LogRecord has a number of attributes, most of which are derived from the 614 parameters to the constructor. (Note that the names do not always correspond 615 exactly between the LogRecord constructor parameters and the LogRecord 616 attributes.) These attributes can be used to merge data from the record into 617 the format string. The following table lists (in alphabetical order) the 618 attribute names, their meanings and the corresponding placeholder in a %-style 619 format string. 620 621 +----------------+-------------------------+-----------------------------------------------+ 622 | Attribute name | Format | Description | 623 +================+=========================+===============================================+ 624 | args | You shouldn't need to | The tuple of arguments merged into ``msg`` to | 625 | | format this yourself. | produce ``message``, or a dict whose values | 626 | | | are used for the merge (when there is only one| 627 | | | argument, and it is a dictionary). | 628 +----------------+-------------------------+-----------------------------------------------+ 629 | asctime | ``%(asctime)s`` | Human-readable time when the | 630 | | | :class:`LogRecord` was created. By default | 631 | | | this is of the form '2003-07-08 16:49:45,896' | 632 | | | (the numbers after the comma are millisecond | 633 | | | portion of the time). | 634 +----------------+-------------------------+-----------------------------------------------+ 635 | created | ``%(created)f`` | Time when the :class:`LogRecord` was created | 636 | | | (as returned by :func:`time.time`). | 637 +----------------+-------------------------+-----------------------------------------------+ 638 | exc_info | You shouldn't need to | Exception tuple ( la ``sys.exc_info``) or, | 639 | | format this yourself. | if no exception has occurred, ``None``. | 640 +----------------+-------------------------+-----------------------------------------------+ 641 | filename | ``%(filename)s`` | Filename portion of ``pathname``. | 642 +----------------+-------------------------+-----------------------------------------------+ 643 | funcName | ``%(funcName)s`` | Name of function containing the logging call. | 644 +----------------+-------------------------+-----------------------------------------------+ 645 | levelname | ``%(levelname)s`` | Text logging level for the message | 646 | | | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, | 647 | | | ``'ERROR'``, ``'CRITICAL'``). | 648 +----------------+-------------------------+-----------------------------------------------+ 649 | levelno | ``%(levelno)s`` | Numeric logging level for the message | 650 | | | (:const:`DEBUG`, :const:`INFO`, | 651 | | | :const:`WARNING`, :const:`ERROR`, | 652 | | | :const:`CRITICAL`). | 653 +----------------+-------------------------+-----------------------------------------------+ 654 | lineno | ``%(lineno)d`` | Source line number where the logging call was | 655 | | | issued (if available). | 656 +----------------+-------------------------+-----------------------------------------------+ 657 | module | ``%(module)s`` | Module (name portion of ``filename``). | 658 +----------------+-------------------------+-----------------------------------------------+ 659 | msecs | ``%(msecs)d`` | Millisecond portion of the time when the | 660 | | | :class:`LogRecord` was created. | 661 +----------------+-------------------------+-----------------------------------------------+ 662 | message | ``%(message)s`` | The logged message, computed as ``msg % | 663 | | | args``. This is set when | 664 | | | :meth:`Formatter.format` is invoked. | 665 +----------------+-------------------------+-----------------------------------------------+ 666 | msg | You shouldn't need to | The format string passed in the original | 667 | | format this yourself. | logging call. Merged with ``args`` to | 668 | | | produce ``message``, or an arbitrary object | 669 | | | (see :ref:`arbitrary-object-messages`). | 670 +----------------+-------------------------+-----------------------------------------------+ 671 | name | ``%(name)s`` | Name of the logger used to log the call. | 672 +----------------+-------------------------+-----------------------------------------------+ 673 | pathname | ``%(pathname)s`` | Full pathname of the source file where the | 674 | | | logging call was issued (if available). | 675 +----------------+-------------------------+-----------------------------------------------+ 676 | process | ``%(process)d`` | Process ID (if available). | 677 +----------------+-------------------------+-----------------------------------------------+ 678 | processName | ``%(processName)s`` | Process name (if available). | 679 +----------------+-------------------------+-----------------------------------------------+ 680 | relativeCreated| ``%(relativeCreated)d`` | Time in milliseconds when the LogRecord was | 681 | | | created, relative to the time the logging | 682 | | | module was loaded. | 683 +----------------+-------------------------+-----------------------------------------------+ 684 | thread | ``%(thread)d`` | Thread ID (if available). | 685 +----------------+-------------------------+-----------------------------------------------+ 686 | threadName | ``%(threadName)s`` | Thread name (if available). | 687 +----------------+-------------------------+-----------------------------------------------+ 688 689 .. versionchanged:: 2.5 690 *funcName* was added. 691 692 .. versionchanged:: 2.6 693 *processName* was added. 694 695 .. _logger-adapter: 696 697 LoggerAdapter Objects 698 --------------------- 699 700 :class:`LoggerAdapter` instances are used to conveniently pass contextual 701 information into logging calls. For a usage example, see the section on 702 :ref:`adding contextual information to your logging output <context-info>`. 703 704 .. versionadded:: 2.6 705 706 707 .. class:: LoggerAdapter(logger, extra) 708 709 Returns an instance of :class:`LoggerAdapter` initialized with an 710 underlying :class:`Logger` instance and a dict-like object. 711 712 .. method:: process(msg, kwargs) 713 714 Modifies the message and/or keyword arguments passed to a logging call in 715 order to insert contextual information. This implementation takes the object 716 passed as *extra* to the constructor and adds it to *kwargs* using key 717 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the 718 (possibly modified) versions of the arguments passed in. 719 720 In addition to the above, :class:`LoggerAdapter` supports the following 721 methods of :class:`Logger`: :meth:`~Logger.debug`, :meth:`~Logger.info`, 722 :meth:`~Logger.warning`, :meth:`~Logger.error`, :meth:`~Logger.exception`, 723 :meth:`~Logger.critical`, :meth:`~Logger.log` and :meth:`~Logger.isEnabledFor`. 724 These methods have the same signatures as their counterparts in :class:`Logger`, 725 so you can use the two types of instances interchangeably for these calls. 726 727 .. versionchanged:: 2.7 728 The :meth:`~Logger.isEnabledFor` method was added to :class:`LoggerAdapter`. 729 This method delegates to the underlying logger. 730 731 732 Thread Safety 733 ------------- 734 735 The logging module is intended to be thread-safe without any special work 736 needing to be done by its clients. It achieves this though using threading 737 locks; there is one lock to serialize access to the module's shared data, and 738 each handler also creates a lock to serialize access to its underlying I/O. 739 740 If you are implementing asynchronous signal handlers using the :mod:`signal` 741 module, you may not be able to use logging from within such handlers. This is 742 because lock implementations in the :mod:`threading` module are not always 743 re-entrant, and so cannot be invoked from such signal handlers. 744 745 746 Module-Level Functions 747 ---------------------- 748 749 In addition to the classes described above, there are a number of module- level 750 functions. 751 752 753 .. function:: getLogger([name]) 754 755 Return a logger with the specified name or, if no name is specified, return a 756 logger which is the root logger of the hierarchy. If specified, the name is 757 typically a dot-separated hierarchical name like *"a"*, *"a.b"* or *"a.b.c.d"*. 758 Choice of these names is entirely up to the developer who is using logging. 759 760 All calls to this function with a given name return the same logger instance. 761 This means that logger instances never need to be passed between different parts 762 of an application. 763 764 765 .. function:: getLoggerClass() 766 767 Return either the standard :class:`Logger` class, or the last class passed to 768 :func:`setLoggerClass`. This function may be called from within a new class 769 definition, to ensure that installing a customized :class:`Logger` class will 770 not undo customizations already applied by other code. For example:: 771 772 class MyLogger(logging.getLoggerClass()): 773 # ... override behaviour here 774 775 776 .. function:: debug(msg[, *args[, **kwargs]]) 777 778 Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the 779 message format string, and the *args* are the arguments which are merged into 780 *msg* using the string formatting operator. (Note that this means that you can 781 use keywords in the format string, together with a single dictionary argument.) 782 783 There are two keyword arguments in *kwargs* which are inspected: *exc_info* 784 which, if it does not evaluate as false, causes exception information to be 785 added to the logging message. If an exception tuple (in the format returned by 786 :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info` 787 is called to get the exception information. 788 789 The other optional keyword argument is *extra* which can be used to pass a 790 dictionary which is used to populate the __dict__ of the LogRecord created for 791 the logging event with user-defined attributes. These custom attributes can then 792 be used as you like. For example, they could be incorporated into logged 793 messages. For example:: 794 795 FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" 796 logging.basicConfig(format=FORMAT) 797 d = {'clientip': '192.168.0.1', 'user': 'fbloggs'} 798 logging.warning("Protocol problem: %s", "connection reset", extra=d) 799 800 would print something like:: 801 802 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset 803 804 The keys in the dictionary passed in *extra* should not clash with the keys used 805 by the logging system. (See the :class:`Formatter` documentation for more 806 information on which keys are used by the logging system.) 807 808 If you choose to use these attributes in logged messages, you need to exercise 809 some care. In the above example, for instance, the :class:`Formatter` has been 810 set up with a format string which expects 'clientip' and 'user' in the attribute 811 dictionary of the LogRecord. If these are missing, the message will not be 812 logged because a string formatting exception will occur. So in this case, you 813 always need to pass the *extra* dictionary with these keys. 814 815 While this might be annoying, this feature is intended for use in specialized 816 circumstances, such as multi-threaded servers where the same code executes in 817 many contexts, and interesting conditions which arise are dependent on this 818 context (such as remote client IP address and authenticated user name, in the 819 above example). In such circumstances, it is likely that specialized 820 :class:`Formatter`\ s would be used with particular :class:`Handler`\ s. 821 822 .. versionchanged:: 2.5 823 *extra* was added. 824 825 826 .. function:: info(msg[, *args[, **kwargs]]) 827 828 Logs a message with level :const:`INFO` on the root logger. The arguments are 829 interpreted as for :func:`debug`. 830 831 832 .. function:: warning(msg[, *args[, **kwargs]]) 833 834 Logs a message with level :const:`WARNING` on the root logger. The arguments are 835 interpreted as for :func:`debug`. 836 837 838 .. function:: error(msg[, *args[, **kwargs]]) 839 840 Logs a message with level :const:`ERROR` on the root logger. The arguments are 841 interpreted as for :func:`debug`. 842 843 844 .. function:: critical(msg[, *args[, **kwargs]]) 845 846 Logs a message with level :const:`CRITICAL` on the root logger. The arguments 847 are interpreted as for :func:`debug`. 848 849 850 .. function:: exception(msg[, *args[, **kwargs]]) 851 852 Logs a message with level :const:`ERROR` on the root logger. The arguments are 853 interpreted as for :func:`debug`, except that any passed *exc_info* is not 854 inspected. Exception info is always added to the logging message. This 855 function should only be called from an exception handler. 856 857 858 .. function:: log(level, msg[, *args[, **kwargs]]) 859 860 Logs a message with level *level* on the root logger. The other arguments are 861 interpreted as for :func:`debug`. 862 863 .. note:: The above module-level convenience functions, which delegate to the 864 root logger, call :func:`basicConfig` to ensure that at least one handler 865 is available. Because of this, they should *not* be used in threads, 866 in versions of Python earlier than 2.7.1 and 3.2, unless at least one 867 handler has been added to the root logger *before* the threads are 868 started. In earlier versions of Python, due to a thread safety shortcoming 869 in :func:`basicConfig`, this can (under rare circumstances) lead to 870 handlers being added multiple times to the root logger, which can in turn 871 lead to multiple messages for the same event. 872 873 .. function:: disable(lvl) 874 875 Provides an overriding level *lvl* for all loggers which takes precedence over 876 the logger's own level. When the need arises to temporarily throttle logging 877 output down across the whole application, this function can be useful. Its 878 effect is to disable all logging calls of severity *lvl* and below, so that 879 if you call it with a value of INFO, then all INFO and DEBUG events would be 880 discarded, whereas those of severity WARNING and above would be processed 881 according to the logger's effective level. If 882 ``logging.disable(logging.NOTSET)`` is called, it effectively removes this 883 overriding level, so that logging output again depends on the effective 884 levels of individual loggers. 885 886 887 .. function:: addLevelName(lvl, levelName) 888 889 Associates level *lvl* with text *levelName* in an internal dictionary, which is 890 used to map numeric levels to a textual representation, for example when a 891 :class:`Formatter` formats a message. This function can also be used to define 892 your own levels. The only constraints are that all levels used must be 893 registered using this function, levels should be positive integers and they 894 should increase in increasing order of severity. 895 896 .. note:: If you are thinking of defining your own levels, please see the 897 section on :ref:`custom-levels`. 898 899 .. function:: getLevelName(lvl) 900 901 Returns the textual representation of logging level *lvl*. If the level is one 902 of the predefined levels :const:`CRITICAL`, :const:`ERROR`, :const:`WARNING`, 903 :const:`INFO` or :const:`DEBUG` then you get the corresponding string. If you 904 have associated levels with names using :func:`addLevelName` then the name you 905 have associated with *lvl* is returned. If a numeric value corresponding to one 906 of the defined levels is passed in, the corresponding string representation is 907 returned. Otherwise, the string "Level %s" % lvl is returned. 908 909 .. note:: Integer levels should be used when e.g. setting levels on instances 910 of :class:`Logger` and handlers. This function is used to convert between 911 an integer level and the level name displayed in the formatted log output 912 by means of the ``%(levelname)s`` format specifier (see 913 :ref:`logrecord-attributes`). 914 915 916 .. function:: makeLogRecord(attrdict) 917 918 Creates and returns a new :class:`LogRecord` instance whose attributes are 919 defined by *attrdict*. This function is useful for taking a pickled 920 :class:`LogRecord` attribute dictionary, sent over a socket, and reconstituting 921 it as a :class:`LogRecord` instance at the receiving end. 922 923 924 .. function:: basicConfig([**kwargs]) 925 926 Does basic configuration for the logging system by creating a 927 :class:`StreamHandler` with a default :class:`Formatter` and adding it to the 928 root logger. The functions :func:`debug`, :func:`info`, :func:`warning`, 929 :func:`error` and :func:`critical` will call :func:`basicConfig` automatically 930 if no handlers are defined for the root logger. 931 932 This function does nothing if the root logger already has handlers 933 configured for it. 934 935 .. versionchanged:: 2.4 936 Formerly, :func:`basicConfig` did not take any keyword arguments. 937 938 .. note:: This function should be called from the main thread before other 939 threads are started. In versions of Python prior to 2.7.1 and 3.2, if 940 this function is called from multiple threads, it is possible (in rare 941 circumstances) that a handler will be added to the root logger more than 942 once, leading to unexpected results such as messages being duplicated in 943 the log. 944 945 The following keyword arguments are supported. 946 947 .. tabularcolumns:: |l|L| 948 949 +--------------+---------------------------------------------+ 950 | Format | Description | 951 +==============+=============================================+ 952 | ``filename`` | Specifies that a FileHandler be created, | 953 | | using the specified filename, rather than a | 954 | | StreamHandler. | 955 +--------------+---------------------------------------------+ 956 | ``filemode`` | Specifies the mode to open the file, if | 957 | | filename is specified (if filemode is | 958 | | unspecified, it defaults to 'a'). | 959 +--------------+---------------------------------------------+ 960 | ``format`` | Use the specified format string for the | 961 | | handler. | 962 +--------------+---------------------------------------------+ 963 | ``datefmt`` | Use the specified date/time format. | 964 +--------------+---------------------------------------------+ 965 | ``level`` | Set the root logger level to the specified | 966 | | level. | 967 +--------------+---------------------------------------------+ 968 | ``stream`` | Use the specified stream to initialize the | 969 | | StreamHandler. Note that this argument is | 970 | | incompatible with 'filename' - if both are | 971 | | present, 'stream' is ignored. | 972 +--------------+---------------------------------------------+ 973 974 975 .. function:: shutdown() 976 977 Informs the logging system to perform an orderly shutdown by flushing and 978 closing all handlers. This should be called at application exit and no 979 further use of the logging system should be made after this call. 980 981 982 .. function:: setLoggerClass(klass) 983 984 Tells the logging system to use the class *klass* when instantiating a logger. 985 The class should define :meth:`__init__` such that only a name argument is 986 required, and the :meth:`__init__` should call :meth:`Logger.__init__`. This 987 function is typically called before any loggers are instantiated by applications 988 which need to use custom logger behavior. 989 990 991 Integration with the warnings module 992 ------------------------------------ 993 994 The :func:`captureWarnings` function can be used to integrate :mod:`logging` 995 with the :mod:`warnings` module. 996 997 .. function:: captureWarnings(capture) 998 999 This function is used to turn the capture of warnings by logging on and 1000 off. 1001 1002 If *capture* is ``True``, warnings issued by the :mod:`warnings` module will 1003 be redirected to the logging system. Specifically, a warning will be 1004 formatted using :func:`warnings.formatwarning` and the resulting string 1005 logged to a logger named ``'py.warnings'`` with a severity of :const:`WARNING`. 1006 1007 If *capture* is ``False``, the redirection of warnings to the logging system 1008 will stop, and warnings will be redirected to their original destinations 1009 (i.e. those in effect before ``captureWarnings(True)`` was called). 1010 1011 1012 .. seealso:: 1013 1014 Module :mod:`logging.config` 1015 Configuration API for the logging module. 1016 1017 Module :mod:`logging.handlers` 1018 Useful handlers included with the logging module. 1019 1020 :pep:`282` - A Logging System 1021 The proposal which described this feature for inclusion in the Python standard 1022 library. 1023 1024 `Original Python logging package <https://www.red-dove.com/python_logging.html>`_ 1025 This is the original source for the :mod:`logging` package. The version of the 1026 package available from this site is suitable for use with Python 1.5.2, 2.1.x 1027 and 2.2.x, which do not include the :mod:`logging` package in the standard 1028 library. 1029 1030
