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, ...)
192 logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
198 Logging from multiple modules
202 could organize logging in it::
205 import logging
209 logging.basicConfig(filename='myapp.log', level=logging.INFO)
210 logging.info('Started')
212 logging.info('Finished')
220 import logging
223 logging.info('Doing something')
239 :ref:`logging-advanced-tutorial`.
242 Logging variable data
248 import logging
249 logging.warning('%s before you %s', 'Look', 'leap!')
259 compatibility: the logging package pre-dates newer formatting options such as
271 import logging
272 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
273 logging.debug('This message should appear on the console')
274 logging.info('So should this')
275 logging.warning('And this, too')
299 import logging
300 logging.basicConfig(format='%(asctime)s %(message)s')
301 logging.warning('is when this event was logged.')
313 import logging
314 logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
315 logging.warning('is when this event was logged.')
331 running with logging. There's a lot more that the logging package offers, but
336 If your logging needs are simple, then use the above examples to incorporate
337 logging into your own scripts, and if you run into problems or don't
344 you can take a look at the :ref:`logging-cookbook`.
349 Advanced Logging Tutorial
352 The logging library takes a modular approach and offers several categories
365 Logging is performed by calling methods on instances of the :class:`Logger`
373 in each module which uses logging, named as follows::
375 logger = logging.getLogger(__name__)
388 locations, email via SMTP, generic sockets, queues, or OS-specific logging
393 By default, no destination is set for any logging messages. You can specify
411 Logging Flow
460 logging methods care only about a keyword of ``exc_info`` and use it to
468 little more verbose for logging messages than using the log level convenience
500 :class:`~logging.Handler` objects are responsible for dispatching the
541 message. Unlike the base :class:`logging.Handler` class, application code may
547 .. method:: logging.Formatter.__init__(fmt=None, datefmt=None, style='%')
580 all logging times to be shown in GMT, set the ``converter`` attribute in the
584 Configuring Logging
587 .. currentmodule:: logging.config
589 Programmers can configure logging in three ways:
593 2. Creating a logging config file and reading it using the :func:`fileConfig`
599 :ref:`logging-config-api`. The following example configures a very simple
602 import logging
605 logger = logging.getLogger('simple_example')
606 logger.setLevel(logging.DEBUG)
609 ch = logging.StreamHandler()
610 ch.setLevel(logging.DEBUG)
613 formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
643 import logging
644 import logging.config
646 logging.config.fileConfig('logging.conf')
649 logger = logging.getLogger('simpleExample')
658 Here is the logging.conf file:
703 noncoders to easily modify the logging properties.
721 .. currentmodule:: logging
724 to the logging module, or absolute values which can be resolved using normal
726 :class:`~logging.handlers.WatchedFileHandler` (relative to the logging module) or
731 In Python 3.2, a new means of configuring logging has been introduced, using
754 class: logging.StreamHandler
767 For more information about logging using a dictionary, see
768 :ref:`logging-config-api`.
773 If no logging configuration is provided, it is possible to have a situation
774 where a logging event needs to be output, but no handlers can be found to
775 output the event. The behaviour of the logging package in these
780 * If *logging.raiseExceptions* is ``False`` (production mode), the event is
783 * If *logging.raiseExceptions* is ``True`` (development mode), a message
789 ``logging.lastResort``. This internal handler is not associated with any
790 logger, and acts like a :class:`~logging.StreamHandler` which writes the
797 To obtain the pre-3.2 behaviour, ``logging.lastResort`` can be set to ``None``.
801 Configuring Logging for a Library
804 When developing a library which uses logging, you should take care to
805 document how the library uses logging - for example, the names of loggers
806 used. Some consideration also needs to be given to its logging configuration.
807 If the using application does not use logging, and library code makes logging
813 any logging configuration, you can attach a do-nothing handler to the top-level
816 output. If the library user configures logging for application use, presumably
818 configured then logging calls made in library code will send output to those
821 A do-nothing handler is included in the logging package:
822 :class:`~logging.NullHandler` (since Python 3.1). An instance of this handler
823 could be added to the top-level logger of the logging namespace used by the
825 ``sys.stderr`` in the absence of logging configuration). If all logging by a
829 import logging
830 logging.getLogger('foo').addHandler(logging.NullHandler())
839 or module. Logging to the root logger will make it difficult or impossible for
840 the application developer to configure the logging verbosity or handlers of
844 than* :class:`~logging.NullHandler` *to your library's loggers*. This is
853 Logging Levels
856 The numeric values of logging levels are given in the following table. These are
879 through loading a saved logging configuration. When a logging method is called
882 logging message is actually generated. This is the basic mechanism controlling
883 the verbosity of logging output.
885 Logging messages are encoded as instances of the :class:`~logging.LogRecord`
887 :class:`~logging.LogRecord` instance is created from the logging message.
889 Logging messages are subjected to a dispatch mechanism through the use of
920 the logging output from such multiple libraries used together will be
970 logging to. If the file changes, it is closed and reopened using the file
978 by library developers who want to use logging, but want to avoid the 'No
980 the library user has not configured logging. See :ref:`library-config` for
990 classes are defined in the core logging package. The other handlers are
991 defined in a sub-module, :mod:`logging.handlers`. (There is also another
992 sub-module, :mod:`logging.config`, for configuration functionality.)
1017 Exceptions raised during logging
1020 The logging package is designed to swallow exceptions which occur while logging
1021 in production. This is so that errors which occur while handling logging events
1022 - such as logging misconfiguration, network or other similar errors - do not
1023 cause the application using logging to terminate prematurely.
1040 .. currentmodule:: logging
1048 passed when logging the event is a string. However, this is not the only
1050 :meth:`~object.__str__` method will be called when the logging system needs to
1061 However, computing the arguments passed to the logging method can also be
1068 if logger.isEnabledFor(logging.DEBUG):
1081 need to be recomputed when the logging configuration changes dynamically
1085 need more precise control over what logging information is collected. Here's a
1086 list of things you can do to avoid processing during logging which you don't
1092 | Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. …
1098 | Threading information. | Set ``logging.logThreads`` to ``False``. …
1100 | Current process ID (:func:`os.getpid`) | Set ``logging.logProcesses`` to ``False``. …
1102 | Current process name when using ``multiprocessing`` | Set ``logging.logMultiprocessing`` to ``Fal…
1106 Also note that the core logging module only includes the basic handlers. If
1107 you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
1112 Module :mod:`logging`
1113 API reference for the logging module.
1115 Module :mod:`logging.config`
1116 Configuration API for the logging module.
1118 Module :mod:`logging.handlers`
1119 Useful handlers included with the logging module.
1121 :ref:`A logging cookbook <logging-cookbook>`