Lines Matching +full:bare +full:- +full:events
5 :Author: Vinay Sajip <vinay_sajip at red-dove dot com>
7 .. _logging-basic-tutorial:
12 ----------------------
14 Logging is a means of tracking events that happen when some software runs. The
16 events have occurred. An event is described by a descriptive message which can
18 each occurrence of the event). Events also have an importance which the
30 +-------------------------------------+--------------------------------------+
36 +-------------------------------------+--------------------------------------+
37 | Report events that occur during | :func:`logging.info` (or |
41 +-------------------------------------+--------------------------------------+
51 +-------------------------------------+--------------------------------------+
54 +-------------------------------------+--------------------------------------+
57 | error handler in a long-running | :func:`logging.critical` as |
60 +-------------------------------------+--------------------------------------+
62 The logging functions are named after the level or severity of the events
68 +--------------+---------------------------------------------+
73 +--------------+---------------------------------------------+
76 +--------------+---------------------------------------------+
81 +--------------+---------------------------------------------+
84 +--------------+---------------------------------------------+
87 +--------------+---------------------------------------------+
89 The default level is ``WARNING``, which means that only events of this level
93 Events that are tracked can be handled in different ways. The simplest way of
94 handling tracked events is to print them to the console. Another common way
98 .. _howto-minimal-example:
111 .. code-block:: none
126 A very common situation is that of recording logging events in a file, so let's
131 logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
135 logging.error('And non-ASCII stuff, too, like Øresund and Malmö')
147 .. code-block:: none
152 ERROR:root:And non-ASCII stuff, too, like Øresund and Malmö
158 If you want to set the logging level from a command-line option such as:
160 .. code-block:: none
162 --log=INFO
164 and you have the value of the parameter passed for ``--log`` in some variable
175 # specify --log=DEBUG or --log=debug
184 one-off simple configuration facility, only the first call will actually do
185 anything: subsequent calls are effectively no-ops.
227 .. code-block:: none
238 to refer to the documentation beyond the tutorial level -- see
239 :ref:`logging-advanced-tutorial`.
253 .. code-block:: none
258 uses the old, %-style of string formatting. This is for backwards
259 compatibility: the logging package pre-dates newer formatting options such as
262 tutorial: see :ref:`formatting-styles` for more information.
279 .. code-block:: none
287 documentation for :ref:`logrecord-attributes`, but for simple usage, you just
305 .. code-block:: none
307 2010-12-12 11:41:42,612 is when this event was logged.
319 .. code-block:: none
343 slightly more advanced/in-depth tutorial than the basic one above. After that,
344 you can take a look at the :ref:`logging-cookbook`.
346 .. _logging-advanced-tutorial:
350 -------------------------
372 A good convention to use when naming loggers is to use a module-level logger,
378 intuitively obvious where events are logged just from the logger name.
382 :func:`error` and :func:`critical`, which just call the same-named method of
388 locations, email via SMTP, generic sockets, queues, or OS-specific logging
391 you have special requirements not met by any of the built-in handler classes.
403 .. code-block:: none
409 constructed, see :ref:`formatter-objects`.
418 :class: invert-in-dark-mode
434 * :meth:`Logger.setLevel` specifies the lowest-severity log message a logger
435 will handle, where debug is the lowest built-in severity level and critical
436 is the highest built-in severity. For example, if the severity level is
442 in :ref:`handler-basic`.
472 name if it is provided, or ``root`` if not. The names are period-separated
481 If the parent has no explicit level set, *its* parent is examined, and so on -
490 configure handlers for a top-level logger and create child loggers as needed.
495 .. _handler-basic:
511 :ref:`useful-handlers`); the tutorials use mainly :class:`StreamHandler` and
516 developers who are using the built-in handler objects (that is, not creating
544 optional arguments -- a message format string, a date format string and a style
552 .. code-block:: none
554 %Y-%m-%d %H:%M:%S
561 documented in :ref:`logrecord-attributes`. If the style is ``'{'``, the message
569 The following message format string will log the time in a human-readable
573 '%(asctime)s - %(levelname)s - %(message)s'
575 Formatters use a user-configurable function to convert the creation time of a
599 :ref:`logging-config-api`. The following example configures a very simple
613 formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
630 .. code-block:: shell-session
633 2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
634 2005-03-19 15:10:26,620 - simple_example - INFO - info message
635 2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
636 2005-03-19 15:10:26,697 - simple_example - ERROR - error message
637 2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message
660 .. code-block:: ini
688 format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
690 The output is nearly identical to that of the non-config-file-based example:
692 .. code-block:: shell-session
695 2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
696 2005-03-19 15:38:55,979 - simpleExample - INFO - info message
697 2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
698 2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
699 2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message
708 will cause any non-root loggers existing before the :func:`fileConfig`
716 ``True``. This leads to the logger-disabling behaviour described above,
717 which may not be what you want - in which case, provide the key
733 functionality of the config-file-based approach outlined above, and is the
744 the new dictionary-based approach:
746 .. code-block:: yaml
751 format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
768 :ref:`logging-config-api`.
793 done on the message - just the bare event description message is printed.
794 The handler's level is set to ``WARNING``, so all events at this and
797 To obtain the pre-3.2 behaviour, ``logging.lastResort`` can be set to ``None``.
799 .. _library-config:
805 document how the library uses logging - for example, the names of loggers
808 calls, then (as described in the previous section) events of severity
813 any logging configuration, you can attach a do-nothing handler to the top-level
815 will always be found for the library's events: it just doesn't produce any
821 A do-nothing handler is included in the logging package:
823 could be added to the top-level logger of the logging namespace used by the
824 library (*if* you want to prevent your library's logged events being output to
838 identifiable name, such as the ``__name__`` for your library's top-level package
854 --------------
862 +--------------+---------------+
866 +--------------+---------------+
868 +--------------+---------------+
870 +--------------+---------------+
872 +--------------+---------------+
874 +--------------+---------------+
876 +--------------+---------------+
906 to send the message to its destination. Most user-defined subclasses of
909 .. _custom-levels:
924 .. _useful-handlers:
927 ---------------
932 #. :class:`StreamHandler` instances send messages to streams (file-like
971 name. This handler is only useful on Unix-like systems; Windows does not
980 the library user has not configured logging. See :ref:`library-config` for
991 defined in a sub-module, :mod:`logging.handlers`. (There is also another
992 sub-module, :mod:`logging.config`, for configuration functionality.)
1015 .. _logging-exceptions:
1018 --------------------------------
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
1031 checks to see if a module-level variable, :data:`raiseExceptions`, is set. If
1042 .. _arbitrary-object-messages:
1045 -----------------------------------
1052 computing a string representation altogether - for example, the
1058 ------------
1089 +-----------------------------------------------------+--------------------------------------------…
1097 +-----------------------------------------------------+--------------------------------------------…
1099 +-----------------------------------------------------+--------------------------------------------…
1101 +-----------------------------------------------------+--------------------------------------------…
1104 +-----------------------------------------------------+--------------------------------------------…
1121 :ref:`A logging cookbook <logging-cookbook>`