Lines Matching +full:formatting +full:- +full:error +full:- +full:messages
1 .. _logging-howto:
7 :Author: Vinay Sajip <vinay_sajip at red-dove dot com>
9 .. _logging-basic-tutorial:
14 logging cookbook, please see :ref:`tutorial-ref-links`.
17 ----------------------
32 :meth:`~Logger.info`, :meth:`~Logger.warning`, :meth:`~Logger.error` and
37 +-------------------------------------+--------------------------------------+
43 +-------------------------------------+--------------------------------------+
48 +-------------------------------------+--------------------------------------+
59 +-------------------------------------+--------------------------------------+
60 | Report an error regarding a | Raise an exception |
62 +-------------------------------------+--------------------------------------+
63 | Report suppression of an error | A logger's :meth:`~Logger.error`, |
65 | error handler in a long-running | :meth:`~Logger.critical` method as |
66 | server process) | appropriate for the specific error |
68 +-------------------------------------+--------------------------------------+
76 +--------------+---------------------------------------------+
81 +--------------+---------------------------------------------+
84 +--------------+---------------------------------------------+
89 +--------------+---------------------------------------------+
90 | ``ERROR`` | Due to a more serious problem, the software |
92 +--------------+---------------------------------------------+
93 | ``CRITICAL`` | A serious error, indicating that the program|
95 +--------------+---------------------------------------------+
105 .. _howto-minimal-example:
118 .. code-block:: none
126 that; formatting options will also be explained later.
133 configuration explicitly however - so for that reason as well as others, it's
145 logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
149 logger.error('And non-ASCII stuff, too, like Øresund and Malmö')
159 messages:
161 .. code-block:: none
166 ERROR:__main__:And non-ASCII stuff, too, like Øresund and Malmö
170 ``DEBUG``, all of the messages were printed.
172 If you want to set the logging level from a command-line option such as:
174 .. code-block:: none
176 --log=INFO
178 and you have the value of the parameter passed for ``--log`` in some variable
184 argument. You may want to error check any user input value, perhaps as in the
189 # specify --log=DEBUG or --log=debug
199 If you run the above script several times, the messages from successive runs
201 not remembering the messages from earlier runs, you can specify the *filemode*
207 to, so the messages from earlier runs are lost.
221 .. code-block:: none
226 uses the old, %-style of string formatting. This is for backwards
227 compatibility: the logging package pre-dates newer formatting options such as
228 :meth:`str.format` and :class:`string.Template`. These newer formatting
230 tutorial: see :ref:`formatting-styles` for more information.
233 Changing the format of displayed messages
236 To change the format which is used to display messages, you need to
247 .. code-block:: none
255 documentation for :ref:`logrecord-attributes`, but for simple usage, you just
261 Displaying the date/time in messages
273 .. code-block:: none
275 2010-12-12 11:41:42,612 is when this event was logged.
278 :rfc:`3339`. If you need more control over the formatting of the date/time, provide
287 .. code-block:: none
311 slightly more advanced/in-depth tutorial than the basic one above. After that,
312 you can take a look at the :ref:`logging-cookbook`.
314 .. _logging-advanced-tutorial:
318 -------------------------
340 A good convention to use when naming loggers is to use a module-level logger,
350 :func:`error` and :func:`critical`, which just call the same-named method of
354 It is, of course, possible to log messages to different destinations. Support
355 is included in the package for writing log messages to files, HTTP GET/POST
356 locations, email via SMTP, generic sockets, queues, or OS-specific logging
359 you have special requirements not met by any of the built-in handler classes.
361 By default, no destination is set for any logging messages. You can specify
364 :func:`warning`, :func:`error` and :func:`critical`, they will check to see
369 The default format set by :func:`basicConfig` for messages is:
371 .. code-block:: none
377 constructed, see :ref:`formatter-objects`.
398 * and then add a dark-theme class to the body when the dark theme is selected.
401 * If the pydoc theme is updated to set the dark-theme class, this snippet
410 elem.classList.remove('dark-theme');
411 elem.classList.remove('light-theme');
413 elem.classList.add('dark-theme');
416 elem.classList.add('light-theme');
425 * If the page is refreshed, make sure we update the body - the overriding
436 methods to application code so that applications can log messages at runtime.
437 Second, logger objects determine which log messages to act upon based upon
439 objects pass along relevant log messages to all interested log handlers.
446 * :meth:`Logger.setLevel` specifies the lowest-severity log message a logger
447 will handle, where debug is the lowest built-in severity level and critical
448 is the highest built-in severity. For example, if the severity level is
449 INFO, the logger will handle only INFO, WARNING, ERROR, and CRITICAL messages
450 and will ignore DEBUG messages.
454 in :ref:`handler-basic`.
463 With the logger object configured, the following methods create log messages:
466 :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with
476 :meth:`Logger.error`. The difference is that :meth:`Logger.exception` dumps a
480 little more verbose for logging messages than using the log level convenience
484 name if it is provided, or ``root`` if not. The names are period-separated
493 If the parent has no explicit level set, *its* parent is examined, and so on -
499 Child loggers propagate messages up to the handlers associated with their
502 configure handlers for a top-level logger and create child loggers as needed.
507 .. _handler-basic:
513 appropriate log messages (based on the log messages' severity) to the handler's
516 scenario, an application may want to send all log messages to a log file, all
517 log messages of error or higher to stdout, and all messages of critical to an
519 handler is responsible for sending messages of a specific severity to a specific
523 :ref:`useful-handlers`); the tutorials use mainly :class:`StreamHandler` and
528 developers who are using the built-in handler objects (that is, not creating
534 determines which severity of messages it will pass to its handlers. The level
535 set in each handler determines which messages that handler will send on.
556 optional arguments -- a message format string, a date format string and a style
564 .. code-block:: none
566 %Y-%m-%d %H:%M:%S
573 documented in :ref:`logrecord-attributes`. If the style is ``'{'``, the message
581 The following message format string will log the time in a human-readable
585 '%(asctime)s - %(levelname)s - %(message)s'
587 Formatters use a user-configurable function to convert the creation time of a
611 :ref:`logging-config-api`. The following example configures a very simple
625 formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
637 logger.error('error message')
642 .. code-block:: shell-session
645 2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
646 2005-03-19 15:10:26,620 - simple_example - INFO - info message
647 2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
648 2005-03-19 15:10:26,697 - simple_example - ERROR - error message
649 2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message
667 logger.error('error message')
672 .. code-block:: ini
700 format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
702 The output is nearly identical to that of the non-config-file-based example:
704 .. code-block:: shell-session
707 2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
708 2005-03-19 15:38:55,979 - simpleExample - INFO - info message
709 2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
710 2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
711 2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message
720 will cause any non-root loggers existing before the :func:`fileConfig`
728 ``True``. This leads to the logger-disabling behaviour described above,
729 which may not be what you want - in which case, provide the key
745 functionality of the config-file-based approach outlined above, and is the
756 the new dictionary-based approach:
758 .. code-block:: yaml
763 format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
780 :ref:`logging-config-api`.
793 respecting any redirections which may be in effect). No formatting is
794 done on the message - just the bare event description message is printed.
808 To obtain the pre-3.2 behaviour,
811 .. _library-config:
817 document how the library uses logging - for example, the names of loggers
824 If for some reason you *don't* want these messages printed in the absence of
825 any logging configuration, you can attach a do-nothing handler to the top-level
833 A do-nothing handler is included in the logging package:
835 could be added to the top-level logger of the logging namespace used by the
850 identifiable name, such as the ``__name__`` for your library's top-level package
866 --------------
874 +--------------+---------------+
878 +--------------+---------------+
879 | ``ERROR`` | 40 |
880 +--------------+---------------+
882 +--------------+---------------+
884 +--------------+---------------+
886 +--------------+---------------+
888 +--------------+---------------+
897 Logging messages are encoded as instances of the :class:`~logging.LogRecord`
901 Logging messages are subjected to a dispatch mechanism through the use of
918 to send the message to its destination. Most user-defined subclasses of
921 .. _custom-levels:
936 .. _useful-handlers:
939 ---------------
944 #. :class:`StreamHandler` instances send messages to streams (file-like
947 #. :class:`FileHandler` instances send messages to disk files.
954 #. :class:`~handlers.RotatingFileHandler` instances send messages to disk
957 #. :class:`~handlers.TimedRotatingFileHandler` instances send messages to
960 #. :class:`~handlers.SocketHandler` instances send messages to TCP/IP
963 #. :class:`~handlers.DatagramHandler` instances send messages to UDP
966 #. :class:`~handlers.SMTPHandler` instances send messages to a designated
969 #. :class:`~handlers.SysLogHandler` instances send messages to a Unix
972 #. :class:`~handlers.NTEventLogHandler` instances send messages to a
975 #. :class:`~handlers.MemoryHandler` instances send messages to a buffer
978 #. :class:`~handlers.HTTPHandler` instances send messages to an HTTP
983 name. This handler is only useful on Unix-like systems; Windows does not
986 #. :class:`~handlers.QueueHandler` instances send messages to a queue, such as
989 #. :class:`NullHandler` instances do nothing with error messages. They are used
992 the library user has not configured logging. See :ref:`library-config` for
1003 defined in a sub-module, :mod:`logging.handlers`. (There is also another
1004 sub-module, :mod:`logging.config`, for configuration functionality.)
1006 Logged messages are formatted for presentation through instances of the
1010 For formatting multiple messages in a batch, instances of
1023 name. If this feature is used, messages sent to the named logger and its
1027 .. _logging-exceptions:
1030 --------------------------------
1034 - such as logging misconfiguration, network or other similar errors - do not
1043 checks to see if a module-level variable, :data:`raiseExceptions`, is set. If
1055 .. _arbitrary-object-messages:
1057 Using arbitrary objects as messages
1058 -----------------------------------
1065 computing a string representation altogether - for example, the
1071 ------------
1073 Formatting of message arguments is deferred until it cannot be avoided.
1102 +-----------------------------------------------------+--------------------------------------------…
1110 +-----------------------------------------------------+--------------------------------------------…
1112 +-----------------------------------------------------+--------------------------------------------…
1114 +-----------------------------------------------------+--------------------------------------------…
1117 +-----------------------------------------------------+--------------------------------------------…
1120 +-----------------------------------------------------+--------------------------------------------…
1126 .. _tutorial-ref-links:
1129 ---------------
1142 :ref:`A logging cookbook <logging-cookbook>`