Lines Matching +full:- +full:- +full:log +full:- +full:level
5 :Author: Vinay Sajip <vinay_sajip at red-dove dot com>
7 .. _logging-basic-tutorial:
12 ----------------------
19 developer ascribes to the event; the importance can also be called the *level*
30 +-------------------------------------+--------------------------------------+
36 +-------------------------------------+--------------------------------------+
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 +--------------+---------------------------------------------+
69 | Level | When it's used |
73 +--------------+---------------------------------------------+
76 +--------------+---------------------------------------------+
81 +--------------+---------------------------------------------+
84 +--------------+---------------------------------------------+
87 +--------------+---------------------------------------------+
89 The default level is ``WARNING``, which means that only events of this level
98 .. _howto-minimal-example:
111 .. code-block:: none
116 default level is ``WARNING``. The printed message includes the indication of
117 the level and the description of the event provided in the logging call, i.e.
131 logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
132 logging.debug('This message should go to the log file')
135 logging.error('And non-ASCII stuff, too, like Øresund and Malmö')
144 And now if we open the file and look at what we have, we should find the log
147 .. code-block:: none
149 DEBUG:root:This message should go to the log file
152 ERROR:root: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:
160 .. code-block:: none
162 --log=INFO
164 and you have the value of the parameter passed for ``--log`` in some variable
169 to get the value which you'll pass to :func:`basicConfig` via the *level*
175 # specify --log=DEBUG or --log=debug
178 raise ValueError('Invalid log level: %s' % loglevel)
179 logging.basicConfig(level=numeric_level, ...)
184 one-off simple configuration facility, only the first call will actually do
185 anything: subsequent calls are effectively no-ops.
188 are appended to the file *example.log*. If you want each run to start afresh,
192 logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
194 The output will be the same as before, but the log file is no longer appended
209 logging.basicConfig(filename='myapp.log', level=logging.INFO)
225 If you run *myapp.py*, you should see this in *myapp.log*:
227 .. code-block:: none
235 usage pattern, you won't know, by looking in the log file, *where* in your
238 to refer to the documentation beyond the tutorial level -- see
239 :ref:`logging-advanced-tutorial`.
245 To log variable data, use a format string for the event description message and
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.
272 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
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 -------------------------
356 * Handlers send the log records (created by loggers) to the appropriate
358 * Filters provide a finer grained facility for determining which log records
360 * Formatters specify the layout of log records in the final output.
362 Log event information is passed between loggers, handlers, filters and
372 A good convention to use when naming loggers is to use a module-level logger,
382 :func:`error` and :func:`critical`, which just call the same-named method of
386 It is, of course, possible to log messages to different destinations. Support
387 is included in the package for writing log messages to files, HTTP GET/POST
388 locations, email via SMTP, generic sockets, queues, or OS-specific logging
389 mechanisms such as syslog or the Windows NT event log. Destinations are served
390 by :dfn:`handler` classes. You can create your own log destination class if
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`.
414 The flow of log event information in loggers and handlers is illustrated in the
418 :class: invert-in-dark-mode
424 methods to application code so that applications can log messages at runtime.
425 Second, logger objects determine which log messages to act upon based upon
427 objects pass along relevant log messages to all interested log handlers.
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`.
451 With the logger object configured, the following methods create log messages:
454 :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with
455 a message and a level that corresponds to their respective method names. The
461 determine whether to log exception information.
463 * :meth:`Logger.exception` creates a log message similar to
467 * :meth:`Logger.log` takes a log level as an explicit argument. This is a
468 little more verbose for logging messages than using the log level convenience
469 methods listed above, but this is how to log at custom log levels.
472 name if it is provided, or ``root`` if not. The names are period-separated
479 Loggers have a concept of *effective level*. If a level is not explicitly set
480 on a logger, the level of its parent is used instead as its effective level.
481 If the parent has no explicit level set, *its* parent is examined, and so on -
482 all ancestors are searched until an explicitly set level is found. The root
483 logger always has an explicit level set (``WARNING`` by default). When deciding
484 whether to process an event, the effective level of the logger is used to
490 configure handlers for a top-level logger and create child loggers as needed.
495 .. _handler-basic:
501 appropriate log messages (based on the log messages' severity) to the handler's
504 scenario, an application may want to send all log messages to a log file, all
505 log messages of error or higher to stdout, and all messages of critical to an
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
521 are there two :func:`setLevel` methods? The level set in the logger
522 determines which severity of messages it will pass to its handlers. The level
540 Formatter objects configure the final order, structure, and contents of the log
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
608 # create console handler and set level to debug
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
672 level=DEBUG
676 level=DEBUG
683 level=DEBUG
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'
755 level: DEBUG
760 level: DEBUG
764 level: DEBUG
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
813 any logging configuration, you can attach a do-nothing handler to the top-level
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
836 .. note:: It is strongly advised that you *do not log to the root logger*
838 identifiable name, such as the ``__name__`` for your library's top-level package
854 --------------
858 have specific values relative to the predefined levels. If you define a level
862 +--------------+---------------+
863 | Level | Numeric value |
866 +--------------+---------------+
868 +--------------+---------------+
870 +--------------+---------------+
872 +--------------+---------------+
874 +--------------+---------------+
876 +--------------+---------------+
880 on a logger, the logger compares its own level with the level associated with
881 the method call. If the logger's level is higher than the method call's, no
886 class. When a logger decides to actually log an event, a
904 level acts as a filter in the same way as a logger's level does. If a handler
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
938 rotate log files at a certain point. It is not meant to be instantiated
943 files, with support for maximum log file sizes and log file rotation.
946 disk files, rotating the log file at certain timed intervals.
961 Windows NT/2000/XP event log.
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.)
1003 When filtering based on logger level and/or handler level is not enough,
1015 .. _logging-exceptions:
1018 --------------------------------
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 ------------
1064 :meth:`~Logger.isEnabledFor` method which takes a level argument and returns
1065 true if the event would be created by the Logger for that level of call.
1077 level is only set high up in the logger hierarchy). In such cases (or if you
1089 +-----------------------------------------------------+--------------------------------------------…
1097 +-----------------------------------------------------+--------------------------------------------…
1099 +-----------------------------------------------------+--------------------------------------------…
1101 +-----------------------------------------------------+--------------------------------------------…
1104 +-----------------------------------------------------+--------------------------------------------…
1121 :ref:`A logging cookbook <logging-cookbook>`