1 :mod:`logging` --- Logging facility for Python

     2 ==============================================

     3 

     4 .. module:: logging

     5    :synopsis: Flexible error logging system for applications.

     6 

     7 

     8 .. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>

     9 .. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>

    10 

    11 

    12 .. index:: pair: Errors; logging

    13 

    14 .. versionadded:: 2.3

    15 

    16 This module defines functions and classes which implement a flexible error

    17 logging system for applications.

    18 

    19 Logging is performed by calling methods on instances of the :class:`Logger`

    20 class (hereafter called :dfn:`loggers`). Each instance has a name, and they are

    21 conceptually arranged in a namespace hierarchy using dots (periods) as

    22 separators. For example, a logger named "scan" is the parent of loggers

    23 "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want,

    24 and indicate the area of an application in which a logged message originates.

    25 

    26 Logged messages also have levels of importance associated with them. The default

    27 levels provided are :const:`DEBUG`, :const:`INFO`, :const:`WARNING`,

    28 :const:`ERROR` and :const:`CRITICAL`. As a convenience, you indicate the

    29 importance of a logged message by calling an appropriate method of

    30 :class:`Logger`. The methods are :meth:`debug`, :meth:`info`, :meth:`warning`,

    31 :meth:`error` and :meth:`critical`, which mirror the default levels. You are not

    32 constrained to use these levels: you can specify your own and use a more general

    33 :class:`Logger` method, :meth:`log`, which takes an explicit level argument.

    34 

    35 

    36 Logging tutorial

    37 ----------------

    38 

    39 The key benefit of having the logging API provided by a standard library module

    40 is that all Python modules can participate in logging, so your application log

    41 can include messages from third-party modules.

    42 

    43 It is, of course, possible to log messages with different verbosity levels or to

    44 different destinations.  Support for writing log messages to files, HTTP

    45 GET/POST locations, email via SMTP, generic sockets, or OS-specific logging

    46 mechanisms are all supported by the standard module.  You can also create your

    47 own log destination class if you have special requirements not met by any of the

    48 built-in classes.

    49 

    50 Simple examples

    51 ^^^^^^^^^^^^^^^

    52 

    53 .. sectionauthor:: Doug Hellmann

    54 .. (see <http://blog.doughellmann.com/2007/05/pymotw-logging.html>)

    55 

    56 Most applications are probably going to want to log to a file, so let's start

    57 with that case. Using the :func:`basicConfig` function, we can set up the

    58 default handler so that debug messages are written to a file::

    59 

    60    import logging

    61    LOG_FILENAME = '/tmp/logging_example.out'

    62    logging.basicConfig(filename=LOG_FILENAME,level=logging.DEBUG,)

    63 

    64    logging.debug('This message should go to the log file')

    65 

    66 And now if we open the file and look at what we have, we should find the log

    67 message::

    68 

    69    DEBUG:root:This message should go to the log file

    70 

    71 If you run the script repeatedly, the additional log messages are appended to

    72 the file.  To create a new file each time, you can pass a filemode argument to

    73 :func:`basicConfig` with a value of ``'w'``.  Rather than managing the file size

    74 yourself, though, it is simpler to use a :class:`RotatingFileHandler`::

    75 

    76    import glob

    77    import logging

    78    import logging.handlers

    79 

    80    LOG_FILENAME = '/tmp/logging_rotatingfile_example.out'

    81 

    82    # Set up a specific logger with our desired output level

    83    my_logger = logging.getLogger('MyLogger')

    84    my_logger.setLevel(logging.DEBUG)

    85 

    86    # Add the log message handler to the logger

    87    handler = logging.handlers.RotatingFileHandler(

    88                  LOG_FILENAME, maxBytes=20, backupCount=5)

    89 

    90    my_logger.addHandler(handler)

    91 

    92    # Log some messages

    93    for i in range(20):

    94        my_logger.debug('i = %d' % i)

    95 

    96    # See what files are created

    97    logfiles = glob.glob('%s*' % LOG_FILENAME)

    98 

    99    for filename in logfiles:

   100        print filename

   101 

   102 The result should be 6 separate files, each with part of the log history for the

   103 application::

   104 

   105    /tmp/logging_rotatingfile_example.out

   106    /tmp/logging_rotatingfile_example.out.1

   107    /tmp/logging_rotatingfile_example.out.2

   108    /tmp/logging_rotatingfile_example.out.3

   109    /tmp/logging_rotatingfile_example.out.4

   110    /tmp/logging_rotatingfile_example.out.5

   111 

   112 The most current file is always :file:`/tmp/logging_rotatingfile_example.out`,

   113 and each time it reaches the size limit it is renamed with the suffix

   114 ``.1``. Each of the existing backup files is renamed to increment the suffix

   115 (``.1`` becomes ``.2``, etc.)  and the ``.5`` file is erased.

   116 

   117 Obviously this example sets the log length much much too small as an extreme

   118 example.  You would want to set *maxBytes* to an appropriate value.

   119 

   120 Another useful feature of the logging API is the ability to produce different

   121 messages at different log levels.  This allows you to instrument your code with

   122 debug messages, for example, but turning the log level down so that those debug

   123 messages are not written for your production system.  The default levels are

   124 ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, ``DEBUG`` and ``UNSET``.

   125 

   126 The logger, handler, and log message call each specify a level.  The log message

   127 is only emitted if the handler and logger are configured to emit messages of

   128 that level or lower.  For example, if a message is ``CRITICAL``, and the logger

   129 is set to ``ERROR``, the message is emitted.  If a message is a ``WARNING``, and

   130 the logger is set to produce only ``ERROR``\s, the message is not emitted::

   131 

   132    import logging

   133    import sys

   134 

   135    LEVELS = {'debug': logging.DEBUG,

   136              'info': logging.INFO,

   137              'warning': logging.WARNING,

   138              'error': logging.ERROR,

   139              'critical': logging.CRITICAL}

   140 

   141    if len(sys.argv) > 1:

   142        level_name = sys.argv[1]

   143        level = LEVELS.get(level_name, logging.NOTSET)

   144        logging.basicConfig(level=level)

   145 

   146    logging.debug('This is a debug message')

   147    logging.info('This is an info message')

   148    logging.warning('This is a warning message')

   149    logging.error('This is an error message')

   150    logging.critical('This is a critical error message')

   151 

   152 Run the script with an argument like 'debug' or 'warning' to see which messages

   153 show up at different levels::

   154 

   155    $ python logging_level_example.py debug

   156    DEBUG:root:This is a debug message

   157    INFO:root:This is an info message

   158    WARNING:root:This is a warning message

   159    ERROR:root:This is an error message

   160    CRITICAL:root:This is a critical error message

   161 

   162    $ python logging_level_example.py info

   163    INFO:root:This is an info message

   164    WARNING:root:This is a warning message

   165    ERROR:root:This is an error message

   166    CRITICAL:root:This is a critical error message

   167 

   168 You will notice that these log messages all have ``root`` embedded in them.  The

   169 logging module supports a hierarchy of loggers with different names.  An easy

   170 way to tell where a specific log message comes from is to use a separate logger

   171 object for each of your modules.  Each new logger "inherits" the configuration

   172 of its parent, and log messages sent to a logger include the name of that

   173 logger.  Optionally, each logger can be configured differently, so that messages

   174 from different modules are handled in different ways.  Let's look at a simple

   175 example of how to log from different modules so it is easy to trace the source

   176 of the message::

   177 

   178    import logging

   179 

   180    logging.basicConfig(level=logging.WARNING)

   181 

   182    logger1 = logging.getLogger('package1.module1')

   183    logger2 = logging.getLogger('package2.module2')

   184 

   185    logger1.warning('This message comes from one module')

   186    logger2.warning('And this message comes from another module')

   187 

   188 And the output::

   189 

   190    $ python logging_modules_example.py

   191    WARNING:package1.module1:This message comes from one module

   192    WARNING:package2.module2:And this message comes from another module

   193 

   194 There are many more options for configuring logging, including different log

   195 message formatting options, having messages delivered to multiple destinations,

   196 and changing the configuration of a long-running application on the fly using a

   197 socket interface.  All of these options are covered in depth in the library

   198 module documentation.

   199 

   200 Loggers

   201 ^^^^^^^

   202 

   203 The logging library takes a modular approach and offers the several categories

   204 of components: loggers, handlers, filters, and formatters.  Loggers expose the

   205 interface that application code directly uses.  Handlers send the log records to

   206 the appropriate destination. Filters provide a finer grained facility for

   207 determining which log records to send on to a handler.  Formatters specify the

   208 layout of the resultant log record.

   209 

   210 :class:`Logger` objects have a threefold job.  First, they expose several

   211 methods to application code so that applications can log messages at runtime.

   212 Second, logger objects determine which log messages to act upon based upon

   213 severity (the default filtering facility) or filter objects.  Third, logger

   214 objects pass along relevant log messages to all interested log handlers.

   215 

   216 The most widely used methods on logger objects fall into two categories:

   217 configuration and message sending.

   218 

   219 * :meth:`Logger.setLevel` specifies the lowest-severity log message a logger

   220   will handle, where debug is the lowest built-in severity level and critical is

   221   the highest built-in severity.  For example, if the severity level is info,

   222   the logger will handle only info, warning, error, and critical messages and

   223   will ignore debug messages.

   224 

   225 * :meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove filter

   226   objects from the logger object.  This tutorial does not address filters.

   227 

   228 With the logger object configured, the following methods create log messages:

   229 

   230 * :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`,

   231   :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with

   232   a message and a level that corresponds to their respective method names. The

   233   message is actually a format string, which may contain the standard string

   234   substitution syntax of :const:`%s`, :const:`%d`, :const:`%f`, and so on.  The

   235   rest of their arguments is a list of objects that correspond with the

   236   substitution fields in the message.  With regard to :const:`**kwargs`, the

   237   logging methods care only about a keyword of :const:`exc_info` and use it to

   238   determine whether to log exception information.

   239 

   240 * :meth:`Logger.exception` creates a log message similar to

   241   :meth:`Logger.error`.  The difference is that :meth:`Logger.exception` dumps a

   242   stack trace along with it.  Call this method only from an exception handler.

   243 

   244 * :meth:`Logger.log` takes a log level as an explicit argument.  This is a

   245   little more verbose for logging messages than using the log level convenience

   246   methods listed above, but this is how to log at custom log levels.

   247 

   248 :func:`getLogger` returns a reference to a logger instance with the specified

   249 if it it is provided, or ``root`` if not.  The names are period-separated

   250 hierarchical structures.  Multiple calls to :func:`getLogger` with the same name

   251 will return a reference to the same logger object.  Loggers that are further

   252 down in the hierarchical list are children of loggers higher up in the list.

   253 For example, given a logger with a name of ``foo``, loggers with names of

   254 ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all children of ``foo``.

   255 Child loggers propagate messages up to their parent loggers.  Because of this,

   256 it is unnecessary to define and configure all the loggers an application uses.

   257 It is sufficient to configure a top-level logger and create child loggers as

   258 needed.

   259 

   260 

   261 Handlers

   262 ^^^^^^^^

   263 

   264 :class:`Handler` objects are responsible for dispatching the appropriate log

   265 messages (based on the log messages' severity) to the handler's specified

   266 destination.  Logger objects can add zero or more handler objects to themselves

   267 with an :func:`addHandler` method.  As an example scenario, an application may

   268 want to send all log messages to a log file, all log messages of error or higher

   269 to stdout, and all messages of critical to an email address.  This scenario

   270 requires three individual handlers where each handler is responsible for sending

   271 messages of a specific severity to a specific location.

   272 

   273 The standard library includes quite a few handler types; this tutorial uses only

   274 :class:`StreamHandler` and :class:`FileHandler` in its examples.

   275 

   276 There are very few methods in a handler for application developers to concern

   277 themselves with.  The only handler methods that seem relevant for application

   278 developers who are using the built-in handler objects (that is, not creating

   279 custom handlers) are the following configuration methods:

   280 

   281 * The :meth:`Handler.setLevel` method, just as in logger objects, specifies the

   282   lowest severity that will be dispatched to the appropriate destination.  Why

   283   are there two :func:`setLevel` methods?  The level set in the logger

   284   determines which severity of messages it will pass to its handlers.  The level

   285   set in each handler determines which messages that handler will send on.

   286   :func:`setFormatter` selects a Formatter object for this handler to use.

   287 

   288 * :func:`addFilter` and :func:`removeFilter` respectively configure and

   289   deconfigure filter objects on handlers.

   290 

   291 Application code should not directly instantiate and use handlers.  Instead, the

   292 :class:`Handler` class is a base class that defines the interface that all

   293 Handlers should have and establishes some default behavior that child classes

   294 can use (or override).

   295 

   296 

   297 Formatters

   298 ^^^^^^^^^^

   299 

   300 Formatter objects configure the final order, structure, and contents of the log

   301 message.  Unlike the base :class:`logging.Handler` class, application code may

   302 instantiate formatter classes, although you could likely subclass the formatter

   303 if your application needs special behavior.  The constructor takes two optional

   304 arguments: a message format string and a date format string.  If there is no

   305 message format string, the default is to use the raw message.  If there is no

   306 date format string, the default date format is::

   307 

   308     %Y-%m-%d %H:%M:%S

   309 

   310 with the milliseconds tacked on at the end.

   311 

   312 The message format string uses ``%(<dictionary key>)s`` styled string

   313 substitution; the possible keys are documented in :ref:`formatter-objects`.

   314 

   315 The following message format string will log the time in a human-readable

   316 format, the severity of the message, and the contents of the message, in that

   317 order::

   318 

   319     "%(asctime)s - %(levelname)s - %(message)s"

   320 

   321 

   322 Configuring Logging

   323 ^^^^^^^^^^^^^^^^^^^

   324 

   325 Programmers can configure logging either by creating loggers, handlers, and

   326 formatters explicitly in a main module with the configuration methods listed

   327 above (using Python code), or by creating a logging config file.  The following

   328 code is an example of configuring a very simple logger, a console handler, and a

   329 simple formatter in a Python module::

   330 

   331     import logging

   332 

   333     # create logger

   334     logger = logging.getLogger("simple_example")

   335     logger.setLevel(logging.DEBUG)

   336     # create console handler and set level to debug

   337     ch = logging.StreamHandler()

   338     ch.setLevel(logging.DEBUG)

   339     # create formatter

   340     formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")

   341     # add formatter to ch

   342     ch.setFormatter(formatter)

   343     # add ch to logger

   344     logger.addHandler(ch)

   345 

   346     # "application" code

   347     logger.debug("debug message")

   348     logger.info("info message")

   349     logger.warn("warn message")

   350     logger.error("error message")

   351     logger.critical("critical message")

   352 

   353 Running this module from the command line produces the following output::

   354 

   355     $ python simple_logging_module.py

   356     2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message

   357     2005-03-19 15:10:26,620 - simple_example - INFO - info message

   358     2005-03-19 15:10:26,695 - simple_example - WARNING - warn message

   359     2005-03-19 15:10:26,697 - simple_example - ERROR - error message

   360     2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message

   361 

   362 The following Python module creates a logger, handler, and formatter nearly

   363 identical to those in the example listed above, with the only difference being

   364 the names of the objects::

   365 

   366     import logging

   367     import logging.config

   368 

   369     logging.config.fileConfig("logging.conf")

   370 

   371     # create logger

   372     logger = logging.getLogger("simpleExample")

   373 

   374     # "application" code

   375     logger.debug("debug message")

   376     logger.info("info message")

   377     logger.warn("warn message")

   378     logger.error("error message")

   379     logger.critical("critical message")

   380 

   381 Here is the logging.conf file::

   382 

   383     [loggers]

   384     keys=root,simpleExample

   385 

   386     [handlers]

   387     keys=consoleHandler

   388 

   389     [formatters]

   390     keys=simpleFormatter

   391 

   392     [logger_root]

   393     level=DEBUG

   394     handlers=consoleHandler

   395 

   396     [logger_simpleExample]

   397     level=DEBUG

   398     handlers=consoleHandler

   399     qualname=simpleExample

   400     propagate=0

   401 

   402     [handler_consoleHandler]

   403     class=StreamHandler

   404     level=DEBUG

   405     formatter=simpleFormatter

   406     args=(sys.stdout,)

   407 

   408     [formatter_simpleFormatter]

   409     format=%(asctime)s - %(name)s - %(levelname)s - %(message)s

   410     datefmt=

   411 

   412 The output is nearly identical to that of the non-config-file-based example::

   413 

   414     $ python simple_logging_config.py

   415     2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message

   416     2005-03-19 15:38:55,979 - simpleExample - INFO - info message

   417     2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message

   418     2005-03-19 15:38:56,055 - simpleExample - ERROR - error message

   419     2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message

   420 

   421 You can see that the config file approach has a few advantages over the Python

   422 code approach, mainly separation of configuration and code and the ability of

   423 noncoders to easily modify the logging properties.

   424 

   425 Configuring Logging for a Library

   426 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   427 

   428 When developing a library which uses logging, some consideration needs to be

   429 given to its configuration. If the using application does not use logging, and

   430 library code makes logging calls, then a one-off message "No handlers could be

   431 found for logger X.Y.Z" is printed to the console. This message is intended

   432 to catch mistakes in logging configuration, but will confuse an application

   433 developer who is not aware of logging by the library.

   434 

   435 In addition to documenting how a library uses logging, a good way to configure

   436 library logging so that it does not cause a spurious message is to add a

   437 handler which does nothing. This avoids the message being printed, since a

   438 handler will be found: it just doesn't produce any output. If the library user

   439 configures logging for application use, presumably that configuration will add

   440 some handlers, and if levels are suitably configured then logging calls made

   441 in library code will send output to those handlers, as normal.

   442 

   443 A do-nothing handler can be simply defined as follows::

   444 

   445     import logging

   446 

   447     class NullHandler(logging.Handler):

   448         def emit(self, record):

   449             pass

   450 

   451 An instance of this handler should be added to the top-level logger of the

   452 logging namespace used by the library. If all logging by a library *foo* is

   453 done using loggers with names matching "foo.x.y", then the code::

   454 

   455     import logging

   456 

   457     h = NullHandler()

   458     logging.getLogger("foo").addHandler(h)

   459 

   460 should have the desired effect. If an organisation produces a number of

   461 libraries, then the logger name specified can be "orgname.foo" rather than

   462 just "foo".

   463 

   464 

   465 Logging Levels

   466 --------------

   467 

   468 The numeric values of logging levels are given in the following table. These are

   469 primarily of interest if you want to define your own levels, and need them to

   470 have specific values relative to the predefined levels. If you define a level

   471 with the same numeric value, it overwrites the predefined value; the predefined

   472 name is lost.

   473 

   474 +--------------+---------------+

   475 | Level        | Numeric value |

   476 +==============+===============+

   477 | ``CRITICAL`` | 50            |

   478 +--------------+---------------+

   479 | ``ERROR``    | 40            |

   480 +--------------+---------------+

   481 | ``WARNING``  | 30            |

   482 +--------------+---------------+

   483 | ``INFO``     | 20            |

   484 +--------------+---------------+

   485 | ``DEBUG``    | 10            |

   486 +--------------+---------------+

   487 | ``NOTSET``   | 0             |

   488 +--------------+---------------+

   489 

   490 Levels can also be associated with loggers, being set either by the developer or

   491 through loading a saved logging configuration. When a logging method is called

   492 on a logger, the logger compares its own level with the level associated with

   493 the method call. If the logger's level is higher than the method call's, no

   494 logging message is actually generated. This is the basic mechanism controlling

   495 the verbosity of logging output.

   496 

   497 Logging messages are encoded as instances of the :class:`LogRecord` class. When

   498 a logger decides to actually log an event, a :class:`LogRecord` instance is

   499 created from the logging message.

   500 

   501 Logging messages are subjected to a dispatch mechanism through the use of

   502 :dfn:`handlers`, which are instances of subclasses of the :class:`Handler`

   503 class. Handlers are responsible for ensuring that a logged message (in the form

   504 of a :class:`LogRecord`) ends up in a particular location (or set of locations)

   505 which is useful for the target audience for that message (such as end users,

   506 support desk staff, system administrators, developers). Handlers are passed

   507 :class:`LogRecord` instances intended for particular destinations. Each logger

   508 can have zero, one or more handlers associated with it (via the

   509 :meth:`addHandler` method of :class:`Logger`). In addition to any handlers

   510 directly associated with a logger, *all handlers associated with all ancestors

   511 of the logger* are called to dispatch the message.

   512 

   513 Just as for loggers, handlers can have levels associated with them. A handler's

   514 level acts as a filter in the same way as a logger's level does. If a handler

   515 decides to actually dispatch an event, the :meth:`emit` method is used to send

   516 the message to its destination. Most user-defined subclasses of :class:`Handler`

   517 will need to override this :meth:`emit`.

   518 

   519 In addition to the base :class:`Handler` class, many useful subclasses are

   520 provided:

   521 

   522 #. :class:`StreamHandler` instances send error messages to streams (file-like

   523    objects).

   524 

   525 #. :class:`FileHandler` instances send error messages to disk files.

   526 

   527 #. :class:`BaseRotatingHandler` is the base class for handlers that rotate log

   528    files at a certain point. It is not meant to be  instantiated directly. Instead,

   529    use :class:`RotatingFileHandler` or :class:`TimedRotatingFileHandler`.

   530 

   531 #. :class:`RotatingFileHandler` instances send error messages to disk files,

   532    with support for maximum log file sizes and log file rotation.

   533 

   534 #. :class:`TimedRotatingFileHandler` instances send error messages to disk files

   535    rotating the log file at certain timed intervals.

   536 

   537 #. :class:`SocketHandler` instances send error messages to TCP/IP sockets.

   538 

   539 #. :class:`DatagramHandler` instances send error messages to UDP sockets.

   540 

   541 #. :class:`SMTPHandler` instances send error messages to a designated email

   542    address.

   543 

   544 #. :class:`SysLogHandler` instances send error messages to a Unix syslog daemon,

   545    possibly on a remote machine.

   546 

   547 #. :class:`NTEventLogHandler` instances send error messages to a Windows

   548    NT/2000/XP event log.

   549 

   550 #. :class:`MemoryHandler` instances send error messages to a buffer in memory,

   551    which is flushed whenever specific criteria are met.

   552 

   553 #. :class:`HTTPHandler` instances send error messages to an HTTP server using

   554    either ``GET`` or ``POST`` semantics.

   555 

   556 The :class:`StreamHandler` and :class:`FileHandler` classes are defined in the

   557 core logging package. The other handlers are defined in a sub- module,

   558 :mod:`logging.handlers`. (There is also another sub-module,

   559 :mod:`logging.config`, for configuration functionality.)

   560 

   561 Logged messages are formatted for presentation through instances of the

   562 :class:`Formatter` class. They are initialized with a format string suitable for

   563 use with the % operator and a dictionary.

   564 

   565 For formatting multiple messages in a batch, instances of

   566 :class:`BufferingFormatter` can be used. In addition to the format string (which

   567 is applied to each message in the batch), there is provision for header and

   568 trailer format strings.

   569 

   570 When filtering based on logger level and/or handler level is not enough,

   571 instances of :class:`Filter` can be added to both :class:`Logger` and

   572 :class:`Handler` instances (through their :meth:`addFilter` method). Before

   573 deciding to process a message further, both loggers and handlers consult all

   574 their filters for permission. If any filter returns a false value, the message

   575 is not processed further.

   576 

   577 The basic :class:`Filter` functionality allows filtering by specific logger

   578 name. If this feature is used, messages sent to the named logger and its

   579 children are allowed through the filter, and all others dropped.

   580 

   581 In addition to the classes described above, there are a number of module- level

   582 functions.

   583 

   584 

   585 .. function:: getLogger([name])

   586 

   587    Return a logger with the specified name or, if no name is specified, return a

   588    logger which is the root logger of the hierarchy. If specified, the name is

   589    typically a dot-separated hierarchical name like *"a"*, *"a.b"* or *"a.b.c.d"*.

   590    Choice of these names is entirely up to the developer who is using logging.

   591 

   592    All calls to this function with a given name return the same logger instance.

   593    This means that logger instances never need to be passed between different parts

   594    of an application.

   595 

   596 

   597 .. function:: getLoggerClass()

   598 

   599    Return either the standard :class:`Logger` class, or the last class passed to

   600    :func:`setLoggerClass`. This function may be called from within a new class

   601    definition, to ensure that installing a customised :class:`Logger` class will

   602    not undo customisations already applied by other code. For example::

   603 

   604       class MyLogger(logging.getLoggerClass()):

   605           # ... override behaviour here

   606 

   607 

   608 .. function:: debug(msg[, *args[, **kwargs]])

   609 

   610    Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the

   611    message format string, and the *args* are the arguments which are merged into

   612    *msg* using the string formatting operator. (Note that this means that you can

   613    use keywords in the format string, together with a single dictionary argument.)

   614 

   615    There are two keyword arguments in *kwargs* which are inspected: *exc_info*

   616    which, if it does not evaluate as false, causes exception information to be

   617    added to the logging message. If an exception tuple (in the format returned by

   618    :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`

   619    is called to get the exception information.

   620 

   621    The other optional keyword argument is *extra* which can be used to pass a

   622    dictionary which is used to populate the __dict__ of the LogRecord created for

   623    the logging event with user-defined attributes. These custom attributes can then

   624    be used as you like. For example, they could be incorporated into logged

   625    messages. For example::

   626 

   627       FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"

   628       logging.basicConfig(format=FORMAT)

   629       d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}

   630       logging.warning("Protocol problem: %s", "connection reset", extra=d)

   631 

   632    would print something like  ::

   633 

   634       2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

   635 

   636    The keys in the dictionary passed in *extra* should not clash with the keys used

   637    by the logging system. (See the :class:`Formatter` documentation for more

   638    information on which keys are used by the logging system.)

   639 

   640    If you choose to use these attributes in logged messages, you need to exercise

   641    some care. In the above example, for instance, the :class:`Formatter` has been

   642    set up with a format string which expects 'clientip' and 'user' in the attribute

   643    dictionary of the LogRecord. If these are missing, the message will not be

   644    logged because a string formatting exception will occur. So in this case, you

   645    always need to pass the *extra* dictionary with these keys.

   646 

   647    While this might be annoying, this feature is intended for use in specialized

   648    circumstances, such as multi-threaded servers where the same code executes in

   649    many contexts, and interesting conditions which arise are dependent on this

   650    context (such as remote client IP address and authenticated user name, in the

   651    above example). In such circumstances, it is likely that specialized

   652    :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.

   653 

   654    .. versionchanged:: 2.5

   655       *extra* was added.

   656 

   657 

   658 .. function:: info(msg[, *args[, **kwargs]])

   659 

   660    Logs a message with level :const:`INFO` on the root logger. The arguments are

   661    interpreted as for :func:`debug`.

   662 

   663 

   664 .. function:: warning(msg[, *args[, **kwargs]])

   665 

   666    Logs a message with level :const:`WARNING` on the root logger. The arguments are

   667    interpreted as for :func:`debug`.

   668 

   669 

   670 .. function:: error(msg[, *args[, **kwargs]])

   671 

   672    Logs a message with level :const:`ERROR` on the root logger. The arguments are

   673    interpreted as for :func:`debug`.

   674 

   675 

   676 .. function:: critical(msg[, *args[, **kwargs]])

   677 

   678    Logs a message with level :const:`CRITICAL` on the root logger. The arguments

   679    are interpreted as for :func:`debug`.

   680 

   681 

   682 .. function:: exception(msg[, *args])

   683 

   684    Logs a message with level :const:`ERROR` on the root logger. The arguments are

   685    interpreted as for :func:`debug`. Exception info is added to the logging

   686    message. This function should only be called from an exception handler.

   687 

   688 

   689 .. function:: log(level, msg[, *args[, **kwargs]])

   690 

   691    Logs a message with level *level* on the root logger. The other arguments are

   692    interpreted as for :func:`debug`.

   693 

   694 

   695 .. function:: disable(lvl)

   696 

   697    Provides an overriding level *lvl* for all loggers which takes precedence over

   698    the logger's own level. When the need arises to temporarily throttle logging

   699    output down across the whole application, this function can be useful.

   700 

   701 

   702 .. function:: addLevelName(lvl, levelName)

   703 

   704    Associates level *lvl* with text *levelName* in an internal dictionary, which is

   705    used to map numeric levels to a textual representation, for example when a

   706    :class:`Formatter` formats a message. This function can also be used to define

   707    your own levels. The only constraints are that all levels used must be

   708    registered using this function, levels should be positive integers and they

   709    should increase in increasing order of severity.

   710 

   711 

   712 .. function:: getLevelName(lvl)

   713 

   714    Returns the textual representation of logging level *lvl*. If the level is one

   715    of the predefined levels :const:`CRITICAL`, :const:`ERROR`, :const:`WARNING`,

   716    :const:`INFO` or :const:`DEBUG` then you get the corresponding string. If you

   717    have associated levels with names using :func:`addLevelName` then the name you

   718    have associated with *lvl* is returned. If a numeric value corresponding to one

   719    of the defined levels is passed in, the corresponding string representation is

   720    returned. Otherwise, the string "Level %s" % lvl is returned.

   721 

   722 

   723 .. function:: makeLogRecord(attrdict)

   724 

   725    Creates and returns a new :class:`LogRecord` instance whose attributes are

   726    defined by *attrdict*. This function is useful for taking a pickled

   727    :class:`LogRecord` attribute dictionary, sent over a socket, and reconstituting

   728    it as a :class:`LogRecord` instance at the receiving end.

   729 

   730 

   731 .. function:: basicConfig([**kwargs])

   732 

   733    Does basic configuration for the logging system by creating a

   734    :class:`StreamHandler` with a default :class:`Formatter` and adding it to the

   735    root logger. The function does nothing if any handlers have been defined for

   736    the root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,

   737    :func:`error` and :func:`critical` will call :func:`basicConfig` automatically

   738    if no handlers are defined for the root logger.

   739 

   740    This function does nothing if the root logger already has handlers configured.

   741 

   742    .. versionchanged:: 2.4

   743       Formerly, :func:`basicConfig` did not take any keyword arguments.

   744 

   745    The following keyword arguments are supported.

   746 

   747    +--------------+---------------------------------------------+

   748    | Format       | Description                                 |

   749    +==============+=============================================+

   750    | ``filename`` | Specifies that a FileHandler be created,    |

   751    |              | using the specified filename, rather than a |

   752    |              | StreamHandler.                              |

   753    +--------------+---------------------------------------------+

   754    | ``filemode`` | Specifies the mode to open the file, if     |

   755    |              | filename is specified (if filemode is       |

   756    |              | unspecified, it defaults to 'a').           |

   757    +--------------+---------------------------------------------+

   758    | ``format``   | Use the specified format string for the     |

   759    |              | handler.                                    |

   760    +--------------+---------------------------------------------+

   761    | ``datefmt``  | Use the specified date/time format.         |

   762    +--------------+---------------------------------------------+

   763    | ``level``    | Set the root logger level to the specified  |

   764    |              | level.                                      |

   765    +--------------+---------------------------------------------+

   766    | ``stream``   | Use the specified stream to initialize the  |

   767    |              | StreamHandler. Note that this argument is   |

   768    |              | incompatible with 'filename' - if both are  |

   769    |              | present, 'stream' is ignored.               |

   770    +--------------+---------------------------------------------+

   771 

   772 

   773 .. function:: shutdown()

   774 

   775    Informs the logging system to perform an orderly shutdown by flushing and

   776    closing all handlers. This should be called at application exit and no

   777    further use of the logging system should be made after this call.

   778 

   779 

   780 .. function:: setLoggerClass(klass)

   781 

   782    Tells the logging system to use the class *klass* when instantiating a logger.

   783    The class should define :meth:`__init__` such that only a name argument is

   784    required, and the :meth:`__init__` should call :meth:`Logger.__init__`. This

   785    function is typically called before any loggers are instantiated by applications

   786    which need to use custom logger behavior.

   787 

   788 

   789 .. seealso::

   790 

   791    :pep:`282` - A Logging System

   792       The proposal which described this feature for inclusion in the Python standard

   793       library.

   794 

   795    `Original Python logging package <http://www.red-dove.com/python_logging.html>`_

   796       This is the original source for the :mod:`logging` package.  The version of the

   797       package available from this site is suitable for use with Python 1.5.2, 2.1.x

   798       and 2.2.x, which do not include the :mod:`logging` package in the standard

   799       library.

   800 

   801 

   802 Logger Objects

   803 --------------

   804 

   805 Loggers have the following attributes and methods. Note that Loggers are never

   806 instantiated directly, but always through the module-level function

   807 ``logging.getLogger(name)``.

   808 

   809 

   810 .. attribute:: Logger.propagate

   811 

   812    If this evaluates to false, logging messages are not passed by this logger or by

   813    child loggers to higher level (ancestor) loggers. The constructor sets this

   814    attribute to 1.

   815 

   816 

   817 .. method:: Logger.setLevel(lvl)

   818 

   819    Sets the threshold for this logger to *lvl*. Logging messages which are less

   820    severe than *lvl* will be ignored. When a logger is created, the level is set to

   821    :const:`NOTSET` (which causes all messages to be processed when the logger is

   822    the root logger, or delegation to the parent when the logger is a non-root

   823    logger). Note that the root logger is created with level :const:`WARNING`.

   824 

   825    The term "delegation to the parent" means that if a logger has a level of

   826    NOTSET, its chain of ancestor loggers is traversed until either an ancestor with

   827    a level other than NOTSET is found, or the root is reached.

   828 

   829    If an ancestor is found with a level other than NOTSET, then that ancestor's

   830    level is treated as the effective level of the logger where the ancestor search

   831    began, and is used to determine how a logging event is handled.

   832 

   833    If the root is reached, and it has a level of NOTSET, then all messages will be

   834    processed. Otherwise, the root's level will be used as the effective level.

   835 

   836 

   837 .. method:: Logger.isEnabledFor(lvl)

   838 

   839    Indicates if a message of severity *lvl* would be processed by this logger.

   840    This method checks first the module-level level set by

   841    ``logging.disable(lvl)`` and then the logger's effective level as determined

   842    by :meth:`getEffectiveLevel`.

   843 

   844 

   845 .. method:: Logger.getEffectiveLevel()

   846 

   847    Indicates the effective level for this logger. If a value other than

   848    :const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise,

   849    the hierarchy is traversed towards the root until a value other than

   850    :const:`NOTSET` is found, and that value is returned.

   851 

   852 

   853 .. method:: Logger.debug(msg[, *args[, **kwargs]])

   854 

   855    Logs a message with level :const:`DEBUG` on this logger. The *msg* is the

   856    message format string, and the *args* are the arguments which are merged into

   857    *msg* using the string formatting operator. (Note that this means that you can

   858    use keywords in the format string, together with a single dictionary argument.)

   859 

   860    There are two keyword arguments in *kwargs* which are inspected: *exc_info*

   861    which, if it does not evaluate as false, causes exception information to be

   862    added to the logging message. If an exception tuple (in the format returned by

   863    :func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`

   864    is called to get the exception information.

   865 

   866    The other optional keyword argument is *extra* which can be used to pass a

   867    dictionary which is used to populate the __dict__ of the LogRecord created for

   868    the logging event with user-defined attributes. These custom attributes can then

   869    be used as you like. For example, they could be incorporated into logged

   870    messages. For example::

   871 

   872       FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"

   873       logging.basicConfig(format=FORMAT)

   874       d = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' }

   875       logger = logging.getLogger("tcpserver")

   876       logger.warning("Protocol problem: %s", "connection reset", extra=d)

   877 

   878    would print something like  ::

   879 

   880       2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

   881 

   882    The keys in the dictionary passed in *extra* should not clash with the keys used

   883    by the logging system. (See the :class:`Formatter` documentation for more

   884    information on which keys are used by the logging system.)

   885 

   886    If you choose to use these attributes in logged messages, you need to exercise

   887    some care. In the above example, for instance, the :class:`Formatter` has been

   888    set up with a format string which expects 'clientip' and 'user' in the attribute

   889    dictionary of the LogRecord. If these are missing, the message will not be

   890    logged because a string formatting exception will occur. So in this case, you

   891    always need to pass the *extra* dictionary with these keys.

   892 

   893    While this might be annoying, this feature is intended for use in specialized

   894    circumstances, such as multi-threaded servers where the same code executes in

   895    many contexts, and interesting conditions which arise are dependent on this

   896    context (such as remote client IP address and authenticated user name, in the

   897    above example). In such circumstances, it is likely that specialized

   898    :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.

   899 

   900    .. versionchanged:: 2.5

   901       *extra* was added.

   902 

   903 

   904 .. method:: Logger.info(msg[, *args[, **kwargs]])

   905 

   906    Logs a message with level :const:`INFO` on this logger. The arguments are

   907    interpreted as for :meth:`debug`.

   908 

   909 

   910 .. method:: Logger.warning(msg[, *args[, **kwargs]])

   911 

   912    Logs a message with level :const:`WARNING` on this logger. The arguments are

   913    interpreted as for :meth:`debug`.

   914 

   915 

   916 .. method:: Logger.error(msg[, *args[, **kwargs]])

   917 

   918    Logs a message with level :const:`ERROR` on this logger. The arguments are

   919    interpreted as for :meth:`debug`.

   920 

   921 

   922 .. method:: Logger.critical(msg[, *args[, **kwargs]])

   923 

   924    Logs a message with level :const:`CRITICAL` on this logger. The arguments are

   925    interpreted as for :meth:`debug`.

   926 

   927 

   928 .. method:: Logger.log(lvl, msg[, *args[, **kwargs]])

   929 

   930    Logs a message with integer level *lvl* on this logger. The other arguments are

   931    interpreted as for :meth:`debug`.

   932 

   933 

   934 .. method:: Logger.exception(msg[, *args])

   935 

   936    Logs a message with level :const:`ERROR` on this logger. The arguments are

   937    interpreted as for :meth:`debug`. Exception info is added to the logging

   938    message. This method should only be called from an exception handler.

   939 

   940 

   941 .. method:: Logger.addFilter(filt)

   942 

   943    Adds the specified filter *filt* to this logger.

   944 

   945 

   946 .. method:: Logger.removeFilter(filt)

   947 

   948    Removes the specified filter *filt* from this logger.

   949 

   950 

   951 .. method:: Logger.filter(record)

   952 

   953    Applies this logger's filters to the record and returns a true value if the

   954    record is to be processed.

   955 

   956 

   957 .. method:: Logger.addHandler(hdlr)

   958 

   959    Adds the specified handler *hdlr* to this logger.

   960 

   961 

   962 .. method:: Logger.removeHandler(hdlr)

   963 

   964    Removes the specified handler *hdlr* from this logger.

   965 

   966 

   967 .. method:: Logger.findCaller()

   968 

   969    Finds the caller's source filename and line number. Returns the filename, line

   970    number and function name as a 3-element tuple.

   971 

   972    .. versionchanged:: 2.4

   973       The function name was added. In earlier versions, the filename and line number

   974       were returned as a 2-element tuple..

   975 

   976 

   977 .. method:: Logger.handle(record)

   978 

   979    Handles a record by passing it to all handlers associated with this logger and

   980    its ancestors (until a false value of *propagate* is found). This method is used

   981    for unpickled records received from a socket, as well as those created locally.

   982    Logger-level filtering is applied using :meth:`filter`.

   983 

   984 

   985 .. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info [, func, extra])

   986 

   987    This is a factory method which can be overridden in subclasses to create

   988    specialized :class:`LogRecord` instances.

   989 

   990    .. versionchanged:: 2.5

   991       *func* and *extra* were added.

   992 

   993 

   994 .. _minimal-example:

   995 

   996 Basic example

   997 -------------

   998 

   999 .. versionchanged:: 2.4

  1000    formerly :func:`basicConfig` did not take any keyword arguments.

  1001 

  1002 The :mod:`logging` package provides a lot of flexibility, and its configuration

  1003 can appear daunting.  This section demonstrates that simple use of the logging

  1004 package is possible.

  1005 

  1006 The simplest example shows logging to the console::

  1007 

  1008    import logging

  1009 

  1010    logging.debug('A debug message')

  1011    logging.info('Some information')

  1012    logging.warning('A shot across the bows')

  1013 

  1014 If you run the above script, you'll see this::

  1015 

  1016    WARNING:root:A shot across the bows

  1017 

  1018 Because no particular logger was specified, the system used the root logger. The

  1019 debug and info messages didn't appear because by default, the root logger is

  1020 configured to only handle messages with a severity of WARNING or above. The

  1021 message format is also a configuration default, as is the output destination of

  1022 the messages - ``sys.stderr``. The severity level, the message format and

  1023 destination can be easily changed, as shown in the example below::

  1024 

  1025    import logging

  1026 

  1027    logging.basicConfig(level=logging.DEBUG,

  1028                        format='%(asctime)s %(levelname)s %(message)s',

  1029                        filename='/tmp/myapp.log',

  1030                        filemode='w')

  1031    logging.debug('A debug message')

  1032    logging.info('Some information')

  1033    logging.warning('A shot across the bows')

  1034 

  1035 The :meth:`basicConfig` method is used to change the configuration defaults,

  1036 which results in output (written to ``/tmp/myapp.log``) which should look

  1037 something like the following::

  1038 

  1039    2004-07-02 13:00:08,743 DEBUG A debug message

  1040    2004-07-02 13:00:08,743 INFO Some information

  1041    2004-07-02 13:00:08,743 WARNING A shot across the bows

  1042 

  1043 This time, all messages with a severity of DEBUG or above were handled, and the

  1044 format of the messages was also changed, and output went to the specified file

  1045 rather than the console.

  1046 

  1047 Formatting uses standard Python string formatting - see section

  1048 :ref:`string-formatting`. The format string takes the following common

  1049 specifiers. For a complete list of specifiers, consult the :class:`Formatter`

  1050 documentation.

  1051 

  1052 +-------------------+-----------------------------------------------+

  1053 | Format            | Description                                   |

  1054 +===================+===============================================+

  1055 | ``%(name)s``      | Name of the logger (logging channel).         |

  1056 +-------------------+-----------------------------------------------+

  1057 | ``%(levelname)s`` | Text logging level for the message            |

  1058 |                   | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``,      |

  1059 |                   | ``'ERROR'``, ``'CRITICAL'``).                 |

  1060 +-------------------+-----------------------------------------------+

  1061 | ``%(asctime)s``   | Human-readable time when the                  |

  1062 |                   | :class:`LogRecord` was created.  By default   |

  1063 |                   | this is of the form "2003-07-08 16:49:45,896" |

  1064 |                   | (the numbers after the comma are millisecond  |

  1065 |                   | portion of the time).                         |

  1066 +-------------------+-----------------------------------------------+

  1067 | ``%(message)s``   | The logged message.                           |

  1068 +-------------------+-----------------------------------------------+

  1069 

  1070 To change the date/time format, you can pass an additional keyword parameter,

  1071 *datefmt*, as in the following::

  1072 

  1073    import logging

  1074 

  1075    logging.basicConfig(level=logging.DEBUG,

  1076                        format='%(asctime)s %(levelname)-8s %(message)s',

  1077                        datefmt='%a, %d %b %Y %H:%M:%S',

  1078                        filename='/temp/myapp.log',

  1079                        filemode='w')

  1080    logging.debug('A debug message')

  1081    logging.info('Some information')

  1082    logging.warning('A shot across the bows')

  1083 

  1084 which would result in output like ::

  1085 

  1086    Fri, 02 Jul 2004 13:06:18 DEBUG    A debug message

  1087    Fri, 02 Jul 2004 13:06:18 INFO     Some information

  1088    Fri, 02 Jul 2004 13:06:18 WARNING  A shot across the bows

  1089 

  1090 The date format string follows the requirements of :func:`strftime` - see the

  1091 documentation for the :mod:`time` module.

  1092 

  1093 If, instead of sending logging output to the console or a file, you'd rather use

  1094 a file-like object which you have created separately, you can pass it to

  1095 :func:`basicConfig` using the *stream* keyword argument. Note that if both

  1096 *stream* and *filename* keyword arguments are passed, the *stream* argument is

  1097 ignored.

  1098 

  1099 Of course, you can put variable information in your output. To do this, simply

  1100 have the message be a format string and pass in additional arguments containing

  1101 the variable information, as in the following example::

  1102 

  1103    import logging

  1104 

  1105    logging.basicConfig(level=logging.DEBUG,

  1106                        format='%(asctime)s %(levelname)-8s %(message)s',

  1107                        datefmt='%a, %d %b %Y %H:%M:%S',

  1108                        filename='/temp/myapp.log',

  1109                        filemode='w')

  1110    logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs')

  1111 

  1112 which would result in ::

  1113 

  1114    Wed, 21 Jul 2004 15:35:16 ERROR    Pack my box with 5 dozen liquor jugs

  1115 

  1116 

  1117 .. _multiple-destinations:

  1118 

  1119 Logging to multiple destinations

  1120 --------------------------------

  1121 

  1122 Let's say you want to log to console and file with different message formats and

  1123 in differing circumstances. Say you want to log messages with levels of DEBUG

  1124 and higher to file, and those messages at level INFO and higher to the console.

  1125 Let's also assume that the file should contain timestamps, but the console

  1126 messages should not. Here's how you can achieve this::

  1127 

  1128    import logging

  1129 

  1130    # set up logging to file - see previous section for more details

  1131    logging.basicConfig(level=logging.DEBUG,

  1132                        format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',

  1133                        datefmt='%m-%d %H:%M',

  1134                        filename='/temp/myapp.log',

  1135                        filemode='w')