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',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')
143 This example also shows how you can set the logging level which acts as the
147 If you want to set the logging level from a command-line option such as::
154 getattr(logging, loglevel.upper())
163 numeric_level = getattr(logging, loglevel.upper(), None)
166 logging.basicConfig(level=numeric_level, ...)
178 logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
184 Logging from multiple modules
188 could organize logging in it::
191 import logging
195 logging.basicConfig(filename='myapp.log', level=logging.INFO)
196 logging.info('Started')
198 logging.info('Finished')
206 import logging
209 logging.info('Doing something')
223 :ref:`logging-advanced-tutorial`.
226 Logging variable data
232 import logging
233 logging.warning('%s before you %s', 'Look', 'leap!')
243 compatibility: the logging package pre-dates newer formatting options such as
255 import logging
256 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
257 logging.debug('This message should appear on the console')
258 logging.info('So should this')
259 logging.warning('And this, too')
281 import logging
282 logging.basicConfig(format='%(asctime)s %(message)s')
283 logging.warning('is when this event was logged.')
293 import logging
294 logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
295 logging.warning('is when this event was logged.')
309 running with logging. There's a lot more that the logging package offers, but
314 If your logging needs are simple, then use the above examples to incorporate
315 logging into your own scripts, and if you run into problems or don't
322 you can take a look at the :ref:`logging-cookbook`.
327 Advanced Logging Tutorial
330 The logging library takes a modular approach and offers several categories
343 Logging is performed by calling methods on instances of the :class:`Logger`
351 in each module which uses logging, named as follows::
353 logger = logging.getLogger(__name__)
366 locations, email via SMTP, generic sockets, or OS-specific logging mechanisms
371 By default, no destination is set for any logging messages. You can specify
387 Logging Flow
435 logging methods care only about a keyword of :const:`exc_info` and use it to
443 little more verbose for logging messages than using the log level convenience
475 :class:`~logging.Handler` objects are responsible for dispatching the
516 message. Unlike the base :class:`logging.Handler` class, application code may
521 .. method:: logging.Formatter.__init__(fmt=None, datefmt=None)
544 all logging times to be shown in GMT, set the ``converter`` attribute in the
548 Configuring Logging
551 .. currentmodule:: logging.config
553 Programmers can configure logging in three ways:
557 2. Creating a logging config file and reading it using the :func:`fileConfig`
563 :ref:`logging-config-api`. The following example configures a very simple
566 import logging
569 logger = logging.getLogger('simple_example')
570 logger.setLevel(logging.DEBUG)
573 ch = logging.StreamHandler()
574 ch.setLevel(logging.DEBUG)
577 formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
607 import logging
608 import logging.config
610 logging.config.fileConfig('logging.conf')
613 logger = logging.getLogger('simpleExample')
622 Here is the logging.conf file::
666 noncoders to easily modify the logging properties.
683 .. currentmodule:: logging
686 to the logging module, or absolute values which can be resolved using normal
688 :class:`~logging.handlers.WatchedFileHandler` (relative to the logging module) or
693 In Python 2.7, a new means of configuring logging has been introduced, using
714 class: logging.StreamHandler
727 For more information about logging using a dictionary, see
728 :ref:`logging-config-api`.
733 If no logging configuration is provided, it is possible to have a situation
734 where a logging event needs to be output, but no handlers can be found to
735 output the event. The behaviour of the logging package in these
740 * If *logging.raiseExceptions* is ``False`` (production mode), the event is
743 * If *logging.raiseExceptions* is ``True`` (development mode), a message
748 Configuring Logging for a Library
751 When developing a library which uses logging, you should take care to
752 document how the library uses logging - for example, the names of loggers
753 used. Some consideration also needs to be given to its logging configuration.
754 If the using application does not configure logging, and library code makes
755 logging calls, then (as described in the previous section) an error message
759 any logging configuration, you can attach a do-nothing handler to the top-level
762 output. If the library user configures logging for application use, presumably
764 configured then logging calls made in library code will send output to those
767 A do-nothing handler is included in the logging package:
768 :class:`~logging.NullHandler` (since Python 2.7). An instance of this handler
769 could be added to the top-level logger of the logging namespace used by the
771 ``sys.stderr`` in the absence of logging configuration). If all logging by a
775 import logging
776 logging.getLogger('foo').addHandler(logging.NullHandler())
783 than* :class:`~logging.NullHandler` *to your library's loggers*. This is
792 Logging Levels
795 The numeric values of logging levels are given in the following table. These are
818 through loading a saved logging configuration. When a logging method is called
821 logging message is actually generated. This is the basic mechanism controlling
822 the verbosity of logging output.
824 Logging messages are encoded as instances of the :class:`~logging.LogRecord`
826 :class:`~logging.LogRecord` instance is created from the logging message.
828 Logging messages are subjected to a dispatch mechanism through the use of
859 the logging output from such multiple libraries used together will be
909 logging to. If the file changes, it is closed and reopened using the file
914 by library developers who want to use logging, but want to avoid the 'No
916 the library user has not configured logging. See :ref:`library-config` for
923 classes are defined in the core logging package. The other handlers are
924 defined in a sub- module, :mod:`logging.handlers`. (There is also another
925 sub-module, :mod:`logging.config`, for configuration functionality.)
950 Exceptions raised during logging
953 The logging package is designed to swallow exceptions which occur while logging
954 in production. This is so that errors which occur while handling logging events
955 - such as logging misconfiguration, network or other similar errors - do not
956 cause the application using logging to terminate prematurely.
980 passed when logging the event is a string. However, this is not the only
982 :meth:`~object.__str__` method will be called when the logging system needs to
993 However, computing the arguments passed to the logging method can also be
1000 if logger.isEnabledFor(logging.DEBUG):
1013 need to be recomputed when the logging configuration changes dynamically
1017 need more precise control over what logging information is collected. Here's a
1018 list of things you can do to avoid processing during logging which you don't
1024 | Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
1031 | Threading information. | Set ``logging.logThreads`` to ``0``. |
1033 | Process information. | Set ``logging.logProcesses`` to ``0``. |
1036 Also note that the core logging module only includes the basic handlers. If
1037 you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
1042 Module :mod:`logging`
1043 API reference for the logging module.
1045 Module :mod:`logging.config`
1046 Configuration API for the logging module.
1048 Module :mod:`logging.handlers`
1049 Useful handlers included with the logging module.
1051 :ref:`A logging cookbook <logging-cookbook>`