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:
702 noncoders to easily modify the logging properties.
720 .. currentmodule:: logging
723 to the logging module, or absolute values which can be resolved using normal
725 :class:`~logging.handlers.WatchedFileHandler` (relative to the logging module) or
730 In Python 3.2, a new means of configuring logging has been introduced, using
753 class: logging.StreamHandler
766 For more information about logging using a dictionary, see
767 :ref:`logging-config-api`.
772 If no logging configuration is provided, it is possible to have a situation
773 where a logging event needs to be output, but no handlers can be found to
774 output the event. The behaviour of the logging package in these
779 * If *logging.raiseExceptions* is ``False`` (production mode), the event is
782 * If *logging.raiseExceptions* is ``True`` (development mode), a message
788 ``logging.lastResort``. This internal handler is not associated with any
789 logger, and acts like a :class:`~logging.StreamHandler` which writes the
796 To obtain the pre-3.2 behaviour, ``logging.lastResort`` can be set to ``None``.
800 Configuring Logging for a Library
803 When developing a library which uses logging, you should take care to
804 document how the library uses logging - for example, the names of loggers
805 used. Some consideration also needs to be given to its logging configuration.
806 If the using application does not use logging, and library code makes logging
812 any logging configuration, you can attach a do-nothing handler to the top-level
815 output. If the library user configures logging for application use, presumably
817 configured then logging calls made in library code will send output to those
820 A do-nothing handler is included in the logging package:
821 :class:`~logging.NullHandler` (since Python 3.1). An instance of this handler
822 could be added to the top-level logger of the logging namespace used by the
824 ``sys.stderr`` in the absence of logging configuration). If all logging by a
828 import logging
829 logging.getLogger('foo').addHandler(logging.NullHandler())
836 than* :class:`~logging.NullHandler` *to your library's loggers*. This is
845 Logging Levels
848 The numeric values of logging levels are given in the following table. These are
871 through loading a saved logging configuration. When a logging method is called
874 logging message is actually generated. This is the basic mechanism controlling
875 the verbosity of logging output.
877 Logging messages are encoded as instances of the :class:`~logging.LogRecord`
879 :class:`~logging.LogRecord` instance is created from the logging message.
881 Logging messages are subjected to a dispatch mechanism through the use of
912 the logging output from such multiple libraries used together will be
962 logging to. If the file changes, it is closed and reopened using the file
970 by library developers who want to use logging, but want to avoid the 'No
972 the library user has not configured logging. See :ref:`library-config` for
982 classes are defined in the core logging package. The other handlers are
983 defined in a sub-module, :mod:`logging.handlers`. (There is also another
984 sub-module, :mod:`logging.config`, for configuration functionality.)
1009 Exceptions raised during logging
1012 The logging package is designed to swallow exceptions which occur while logging
1013 in production. This is so that errors which occur while handling logging events
1014 - such as logging misconfiguration, network or other similar errors - do not
1015 cause the application using logging to terminate prematurely.
1032 .. currentmodule:: logging
1040 passed when logging the event is a string. However, this is not the only
1042 :meth:`~object.__str__` method will be called when the logging system needs to
1053 However, computing the arguments passed to the logging method can also be
1060 if logger.isEnabledFor(logging.DEBUG):
1073 need to be recomputed when the logging configuration changes dynamically
1077 need more precise control over what logging information is collected. Here's a
1078 list of things you can do to avoid processing during logging which you don't
1084 | Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
1091 | Threading information. | Set ``logging.logThreads`` to ``0``. |
1093 | Process information. | Set ``logging.logProcesses`` to ``0``. |
1096 Also note that the core logging module only includes the basic handlers. If
1097 you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
1102 Module :mod:`logging`
1103 API reference for the logging module.
1105 Module :mod:`logging.config`
1106 Configuration API for the logging module.
1108 Module :mod:`logging.handlers`
1109 Useful handlers included with the logging module.
1111 :ref:`A logging cookbook <logging-cookbook>`