Lines Matching full:logging
2 Logging HOWTO
9 .. currentmodule:: logging
11 Basic Logging Tutorial
14 Logging is a means of tracking events that happen when some software runs. The
15 software's developer adds logging calls to their code to indicate that certain
22 When to use logging
25 Logging provides a set of convenience functions for simple logging usage. These
27 :func:`critical`. To determine when to use logging, see the table below, which
37 | Report events that occur during | :func:`logging.info` (or |
38 | normal operation of a program (e.g. | :func:`logging.debug` for very |
47 | | :func:`logging.warning` if there is |
55 | Report suppression of an error | :func:`logging.error`, |
56 | without raising an exception (e.g. | :func:`logging.exception` or |
57 | error handler in a long-running | :func:`logging.critical` as |
62 The logging functions are named after the level or severity of the events
90 and above will be tracked, unless the logging package is configured to do
105 import logging
106 logging.warning('Watch out!') # will print a message to the console
107 logging.info('I told you so') # will not print anything
117 the level and the description of the event provided in the logging call, i.e.
123 Logging to a file
126 A very common situation is that of recording logging events in a file, so let's
130 import logging
131 logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
132 logging.debug('This message should go to the log file')
133 logging.info('So should this')
134 logging.warning('And this, too')
135 logging.error('And non-ASCII stuff, too, like Øresund and Malmö')
154 This example also shows how you can set the logging level which acts as the
158 If you want to set the logging level from a command-line option such as:
167 getattr(logging, loglevel.upper())
176 numeric_level = getattr(logging, loglevel.upper(), None)
179 logging.basicConfig(level=numeric_level, ...)
191 logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
197 Logging from multiple modules
201 could organize logging in it::
204 import logging
208 logging.basicConfig(filename='myapp.log', level=logging.INFO)
209 logging.info('Started')
211 logging.info('Finished')
219 import logging
222 logging.info('Doing something')
238 :ref:`logging-advanced-tutorial`.
241 Logging variable data
247 import logging
248 logging.warning('%s before you %s', 'Look', 'leap!')
258 compatibility: the logging package pre-dates newer formatting options such as
270 import logging
271 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
272 logging.debug('This message should appear on the console')
273 logging.info('So should this')
274 logging.warning('And this, too')
298 import logging
299 logging.basicConfig(format='%(asctime)s %(message)s')
300 logging.warning('is when this event was logged.')
312 import logging
313 logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
314 logging.warning('is when this event was logged.')
330 running with logging. There's a lot more that the logging package offers, but
335 If your logging needs are simple, then use the above examples to incorporate
336 logging into your own scripts, and if you run into problems or don't
343 you can take a look at the :ref:`logging-cookbook`.
348 Advanced Logging Tutorial
351 The logging library takes a modular approach and offers several categories
364 Logging is performed by calling methods on instances of the :class:`Logger`
372 in each module which uses logging, named as follows::
374 logger = logging.getLogger(__name__)
387 locations, email via SMTP, generic sockets, queues, or OS-specific logging
392 By default, no destination is set for any logging messages. You can specify
410 Logging Flow
458 logging methods care only about a keyword of ``exc_info`` and use it to
466 little more verbose for logging messages than using the log level convenience
498 :class:`~logging.Handler` objects are responsible for dispatching the
539 message. Unlike the base :class:`logging.Handler` class, application code may
545 .. method:: logging.Formatter.__init__(fmt=None, datefmt=None, style='%')
578 all logging times to be shown in GMT, set the ``converter`` attribute in the
582 Configuring Logging
585 .. currentmodule:: logging.config
587 Programmers can configure logging in three ways:
591 2. Creating a logging config file and reading it using the :func:`fileConfig`
597 :ref:`logging-config-api`. The following example configures a very simple
600 import logging
603 logger = logging.getLogger('simple_example')
604 logger.setLevel(logging.DEBUG)
607 ch = logging.StreamHandler()
608 ch.setLevel(logging.DEBUG)
611 formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
641 import logging
642 import logging.config
644 logging.config.fileConfig('logging.conf')
647 logger = logging.getLogger('simpleExample')
656 Here is the logging.conf file:
701 noncoders to easily modify the logging properties.
719 .. currentmodule:: logging
722 to the logging module, or absolute values which can be resolved using normal
724 :class:`~logging.handlers.WatchedFileHandler` (relative to the logging module) or
729 In Python 3.2, a new means of configuring logging has been introduced, using
752 class: logging.StreamHandler
765 For more information about logging using a dictionary, see
766 :ref:`logging-config-api`.
771 If no logging configuration is provided, it is possible to have a situation
772 where a logging event needs to be output, but no handlers can be found to
773 output the event. The behaviour of the logging package in these
778 * If *logging.raiseExceptions* is ``False`` (production mode), the event is
781 * If *logging.raiseExceptions* is ``True`` (development mode), a message
787 ``logging.lastResort``. This internal handler is not associated with any
788 logger, and acts like a :class:`~logging.StreamHandler` which writes the
795 To obtain the pre-3.2 behaviour, ``logging.lastResort`` can be set to ``None``.
799 Configuring Logging for a Library
802 When developing a library which uses logging, you should take care to
803 document how the library uses logging - for example, the names of loggers
804 used. Some consideration also needs to be given to its logging configuration.
805 If the using application does not use logging, and library code makes logging
811 any logging configuration, you can attach a do-nothing handler to the top-level
814 output. If the library user configures logging for application use, presumably
816 configured then logging calls made in library code will send output to those
819 A do-nothing handler is included in the logging package:
820 :class:`~logging.NullHandler` (since Python 3.1). An instance of this handler
821 could be added to the top-level logger of the logging namespace used by the
823 ``sys.stderr`` in the absence of logging configuration). If all logging by a
827 import logging
828 logging.getLogger('foo').addHandler(logging.NullHandler())
835 than* :class:`~logging.NullHandler` *to your library's loggers*. This is
844 Logging Levels
847 The numeric values of logging levels are given in the following table. These are
870 through loading a saved logging configuration. When a logging method is called
873 logging message is actually generated. This is the basic mechanism controlling
874 the verbosity of logging output.
876 Logging messages are encoded as instances of the :class:`~logging.LogRecord`
878 :class:`~logging.LogRecord` instance is created from the logging message.
880 Logging messages are subjected to a dispatch mechanism through the use of
911 the logging output from such multiple libraries used together will be
961 logging to. If the file changes, it is closed and reopened using the file
969 by library developers who want to use logging, but want to avoid the 'No
971 the library user has not configured logging. See :ref:`library-config` for
981 classes are defined in the core logging package. The other handlers are
982 defined in a sub-module, :mod:`logging.handlers`. (There is also another
983 sub-module, :mod:`logging.config`, for configuration functionality.)
1008 Exceptions raised during logging
1011 The logging package is designed to swallow exceptions which occur while logging
1012 in production. This is so that errors which occur while handling logging events
1013 - such as logging misconfiguration, network or other similar errors - do not
1014 cause the application using logging to terminate prematurely.
1031 .. currentmodule:: logging
1039 passed when logging the event is a string. However, this is not the only
1041 :meth:`~object.__str__` method will be called when the logging system needs to
1052 However, computing the arguments passed to the logging method can also be
1059 if logger.isEnabledFor(logging.DEBUG):
1072 need to be recomputed when the logging configuration changes dynamically
1076 need more precise control over what logging information is collected. Here's a
1077 list of things you can do to avoid processing during logging which you don't
1083 | Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. …
1089 | Threading information. | Set ``logging.logThreads`` to ``False``. …
1091 | Current process ID (:func:`os.getpid`) | Set ``logging.logProcesses`` to ``False``. …
1093 | Current process name when using ``multiprocessing`` | Set ``logging.logMultiprocessing`` to ``Fal…
1097 Also note that the core logging module only includes the basic handlers. If
1098 you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
1103 Module :mod:`logging`
1104 API reference for the logging module.
1106 Module :mod:`logging.config`
1107 Configuration API for the logging module.
1109 Module :mod:`logging.handlers`
1110 Useful handlers included with the logging module.
1112 :ref:`A logging cookbook <logging-cookbook>`