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.
127 look at that next. Be sure to try the following in a newly-started Python
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, ...)
182 :func:`info` etc. As it's intended as a one-off simple configuration facility,
184 no-ops.
187 are appended to the file *example.log*. If you want each run to start afresh,
191 logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
193 The output will be the same as before, but the log file is no longer appended
208 logging.basicConfig(filename='myapp.log', level=logging.INFO)
224 If you run *myapp.py*, you should see this in *myapp.log*:
226 .. code-block:: none
234 usage pattern, you won't know, by looking in the log file, *where* in your
237 to refer to the documentation beyond the tutorial level -- see
238 :ref:`logging-advanced-tutorial`.
244 To log variable data, use a format string for the event description message and
252 .. code-block:: none
257 uses the old, %-style of string formatting. This is for backwards
258 compatibility: the logging package pre-dates newer formatting options such as
261 tutorial: see :ref:`formatting-styles` for more information.
271 logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
278 .. code-block:: none
286 documentation for :ref:`logrecord-attributes`, but for simple usage, you just
304 .. code-block:: none
306 2010-12-12 11:41:42,612 is when this event was logged.
318 .. code-block:: none
342 slightly more advanced/in-depth tutorial than the basic one above. After that,
343 you can take a look at the :ref:`logging-cookbook`.
345 .. _logging-advanced-tutorial:
349 -------------------------
355 * Handlers send the log records (created by loggers) to the appropriate
357 * Filters provide a finer grained facility for determining which log records
359 * Formatters specify the layout of log records in the final output.
361 Log event information is passed between loggers, handlers, filters and
371 A good convention to use when naming loggers is to use a module-level logger,
381 :func:`error` and :func:`critical`, which just call the same-named method of
385 It is, of course, possible to log messages to different destinations. Support
386 is included in the package for writing log messages to files, HTTP GET/POST
387 locations, email via SMTP, generic sockets, queues, or OS-specific logging
388 mechanisms such as syslog or the Windows NT event log. Destinations are served
389 by :dfn:`handler` classes. You can create your own log destination class if
390 you have special requirements not met by any of the built-in handler classes.
402 .. code-block:: none
408 constructed, see :ref:`formatter-objects`.
413 The flow of log event information in loggers and handlers is illustrated in the
422 methods to application code so that applications can log messages at runtime.
423 Second, logger objects determine which log messages to act upon based upon
425 objects pass along relevant log messages to all interested log handlers.
432 * :meth:`Logger.setLevel` specifies the lowest-severity log message a logger
433 will handle, where debug is the lowest built-in severity level and critical
434 is the highest built-in severity. For example, if the severity level is
440 in :ref:`handler-basic`.
449 With the logger object configured, the following methods create log messages:
452 :meth:`Logger.error`, and :meth:`Logger.critical` all create log records with
453 a message and a level that corresponds to their respective method names. The
459 determine whether to log exception information.
461 * :meth:`Logger.exception` creates a log message similar to
465 * :meth:`Logger.log` takes a log level as an explicit argument. This is a
466 little more verbose for logging messages than using the log level convenience
467 methods listed above, but this is how to log at custom log levels.
470 name if it is provided, or ``root`` if not. The names are period-separated
477 Loggers have a concept of *effective level*. If a level is not explicitly set
478 on a logger, the level of its parent is used instead as its effective level.
479 If the parent has no explicit level set, *its* parent is examined, and so on -
480 all ancestors are searched until an explicitly set level is found. The root
481 logger always has an explicit level set (``WARNING`` by default). When deciding
482 whether to process an event, the effective level of the logger is used to
488 configure handlers for a top-level logger and create child loggers as needed.
493 .. _handler-basic:
499 appropriate log messages (based on the log messages' severity) to the handler's
502 scenario, an application may want to send all log messages to a log file, all
503 log messages of error or higher to stdout, and all messages of critical to an
509 :ref:`useful-handlers`); the tutorials use mainly :class:`StreamHandler` and
514 developers who are using the built-in handler objects (that is, not creating
519 are there two :func:`setLevel` methods? The level set in the logger
520 determines which severity of messages it will pass to its handlers. The level
538 Formatter objects configure the final order, structure, and contents of the log
542 optional arguments -- a message format string, a date format string and a style
550 .. code-block:: none
552 %Y-%m-%d %H:%M:%S
559 documented in :ref:`logrecord-attributes`. If the style is '{', the message
567 The following message format string will log the time in a human-readable
571 '%(asctime)s - %(levelname)s - %(message)s'
573 Formatters use a user-configurable function to convert the creation time of a
597 :ref:`logging-config-api`. The following example configures a very simple
606 # create console handler and set level to debug
611 formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
628 .. code-block:: shell-session
631 2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
632 2005-03-19 15:10:26,620 - simple_example - INFO - info message
633 2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
634 2005-03-19 15:10:26,697 - simple_example - ERROR - error message
635 2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message
658 .. code-block:: ini
670 level=DEBUG
674 level=DEBUG
681 level=DEBUG
686 format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
688 The output is nearly identical to that of the non-config-file-based example:
690 .. code-block:: shell-session
693 2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
694 2005-03-19 15:38:55,979 - simpleExample - INFO - info message
695 2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
696 2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
697 2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message
706 will cause any non-root loggers existing before the :func:`fileConfig`
714 ``True``. This leads to the logger-disabling behaviour described above,
715 which may not be what you want - in which case, provide the key
731 functionality of the config-file-based approach outlined above, and is the
742 the new dictionary-based approach:
744 .. code-block:: yaml
749 format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
753 level: DEBUG
758 level: DEBUG
762 level: DEBUG
766 :ref:`logging-config-api`.
791 done on the message - just the bare event description message is printed.
792 The handler's level is set to ``WARNING``, so all events at this and
795 To obtain the pre-3.2 behaviour, ``logging.lastResort`` can be set to ``None``.
797 .. _library-config:
803 document how the library uses logging - for example, the names of loggers
811 any logging configuration, you can attach a do-nothing handler to the top-level
819 A do-nothing handler is included in the logging package:
821 could be added to the top-level logger of the logging namespace used by the
845 --------------
849 have specific values relative to the predefined levels. If you define a level
853 +--------------+---------------+
854 | Level | Numeric value |
857 +--------------+---------------+
859 +--------------+---------------+
861 +--------------+---------------+
863 +--------------+---------------+
865 +--------------+---------------+
867 +--------------+---------------+
871 on a logger, the logger compares its own level with the level associated with
872 the method call. If the logger's level is higher than the method call's, no
877 class. When a logger decides to actually log an event, a
895 level acts as a filter in the same way as a logger's level does. If a handler
897 to send the message to its destination. Most user-defined subclasses of
900 .. _custom-levels:
915 .. _useful-handlers:
918 ---------------
923 #. :class:`StreamHandler` instances send messages to streams (file-like
929 rotate log files at a certain point. It is not meant to be instantiated
934 files, with support for maximum log file sizes and log file rotation.
937 disk files, rotating the log file at certain timed intervals.
952 Windows NT/2000/XP event log.
962 name. This handler is only useful on Unix-like systems; Windows does not
971 the library user has not configured logging. See :ref:`library-config` for
982 defined in a sub-module, :mod:`logging.handlers`. (There is also another
983 sub-module, :mod:`logging.config`, for configuration functionality.)
994 When filtering based on logger level and/or handler level is not enough,
1006 .. _logging-exceptions:
1009 --------------------------------
1013 - such as logging misconfiguration, network or other similar errors - do not
1022 checks to see if a module-level variable, :data:`raiseExceptions`, is set. If
1033 .. _arbitrary-object-messages:
1036 -----------------------------------
1043 computing a string representation altogether - for example, the
1049 ------------
1055 :meth:`~Logger.isEnabledFor` method which takes a level argument and returns
1056 true if the event would be created by the Logger for that level of call.
1068 level is only set high up in the logger hierarchy). In such cases (or if you
1080 +-----------------------------------------------------+--------------------------------------------…
1088 +-----------------------------------------------------+--------------------------------------------…
1090 +-----------------------------------------------------+--------------------------------------------…
1092 +-----------------------------------------------------+--------------------------------------------…
1095 +-----------------------------------------------------+--------------------------------------------…
1112 :ref:`A logging cookbook <logging-cookbook>`