<commit_before>=============
Logging HOWTO
=============

:Author: <NAME> <vinay_sajip at red-dove dot com>

.. _logging-basic-tutorial:

.. currentmodule:: logging

Basic Logging Tutorial
----------------------

Logging is a means of tracking events that happen when some software runs. The
software's developer adds logging calls to their code to indicate that certain
events have occurred. An event is described by a descriptive message which can
optionally contain variable data (i.e. data that is potentially different for
each occurrence of the event). Events also have an importance which the
developer ascribes to the event; the importance can also be called the *level*
or *severity*.

When to use logging
^^^^^^^^^^^^^^^^^^^

Logging provides a set of convenience functions for simple logging usage. These
are :func:`debug`, :func:`info`, :func:`warning`, :func:`error` and
:func:`critical`. To determine when to use logging, see the table below, which
states, for each of a set of common tasks, the best tool to use for it.

+-------------------------------------+--------------------------------------+
| Task you want to perform            | The best tool for the task           |
+=====================================+======================================+
| Display console output for ordinary | :func:`print`                        |
| usage of a command line script or   |                                      |
| program                             |                                      |
+-------------------------------------+--------------------------------------+
| Report events that occur during     | :func:`logging.info` (or             |
| normal operation of a program (e.g. | :func:`logging.debug` for very       |
| for status monitoring or fault      | detailed output for diagnostic       |
| investigation)                      | purposes)                            |
+-------------------------------------+--------------------------------------+
| Issue a warning regarding a         | :func:`warnings.warn` in library     |
| particular runtime event            | code if the issue is avoidable and   |
|                                     | the client application should be     |
|                                     | modified to eliminate the warning    |
|                                     |                                      |
|                                     | :func:`logging.warning` if there is  |
|                                     | nothing the client application can do|
|                                     | about the situation, but the event   |
|                                     | should still be noted                |
+-------------------------------------+--------------------------------------+
| Report an error regarding a         | Raise an exception                   |
| particular runtime event            |                                      |
+-------------------------------------+--------------------------------------+
| Report suppression of an error      | :func:`logging.error`,               |
| without raising an exception (e.g.  | :func:`logging.exception` or         |
| error handler in a long-running     | :func:`logging.critical` as          |
| server process)                     | appropriate for the specific error   |
|                                     | and application domain               |
+-------------------------------------+--------------------------------------+

The logging functions are named after the level or severity of the events
they are used to track. The standard levels and their applicability are
described below (in increasing order of severity):

.. tabularcolumns:: |l|L|

+--------------+---------------------------------------------+
| Level        | When it's used                              |
+==============+=============================================+
| ``DEBUG``    | Detailed information, typically of interest |
|              | only when diagnosing problems.              |
+--------------+---------------------------------------------+
| ``INFO``     | Confirmation that things are working as     |
|              | expected.                                   |
+--------------+---------------------------------------------+
| ``WARNING``  | An indication that something unexpected     |
|              | happened, or indicative of some problem in  |
|              | the near future (e.g. 'disk space low').    |
|              | The software is still working as expected.  |
+--------------+---------------------------------------------+
| ``ERROR``    | Due to a more serious problem, the software |
|              | has not been able to perform some function. |
+--------------+---------------------------------------------+
| ``CRITICAL`` | A serious error, indicating that the program|
|              | itself may be unable to continue running.   |
+--------------+---------------------------------------------+

The default level is ``WARNING``, which means that only events of this level
and above will be tracked, unless the logging package is configured to do
otherwise.

Events that are tracked can be handled in different ways. The simplest way of
handling tracked events is to print them to the console. Another common way
is to write them to a disk file.


.. _howto-minimal-example:

A simple example
^^^^^^^^^^^^^^^^

A very simple example is::

   import logging
   logging.warning('Watch out!') # will print a message to the console
   logging.info('I told you so') # will not print anything

If you type these lines into a script and run it, you'll see::

   WARNING:root:Watch out!

printed out on the console. The ``INFO`` message doesn't appear because the
default level is ``WARNING``. The printed message includes the indication of
the level and the description of the event provided in the logging call, i.e.
'Watch out!'. Don't worry about the 'root' part for now: it will be explained
later. The actual output can be formatted quite flexibly if you need that;
formatting options will also be explained later.


Logging to a file
^^^^^^^^^^^^^^^^^

A very common situation is that of recording logging events in a file, so let's
look at that next::

   import logging
   logging.basicConfig(filename='example.log',level=logging.DEBUG)
   logging.debug('This message should go to the log file')
   logging.info('So should this')
   logging.warning('And this, too')

And now if we open the file and look at what we have, we should find the log
messages::

   DEBUG:root:This message should go to the log file
   INFO:root:So should this
   WARNING:root:And this, too<commit_msg>Added minor clarification in logging HOWTO.<commit_after>=============
Logging HOWTO
=============

:Author: <NAME> <vinay_sajip at red-dove dot com>

.. _logging-basic-tutorial:

.. currentmodule:: logging

Basic Logging Tutorial
----------------------

Logging is a means of tracking events that happen when some software runs. The
software's developer adds logging calls to their code to indicate that certain
events have occurred. An event is described by a descriptive message which can
optionally contain variable data (i.e. data that is potentially different for
each occurrence of the event). Events also have an importance which the
developer ascribes to the event; the importance can also be called the *level*
or *severity*.

When to use logging
^^^^^^^^^^^^^^^^^^^

Logging provides a set of convenience functions for simple logging usage. These
are :func:`debug`, :func:`info`, :func:`warning`, :func:`error` and
:func:`critical`. To determine when to use logging, see the table below, which
states, for each of a set of common tasks, the best tool to use for it.

+-------------------------------------+--------------------------------------+
| Task you want to perform            | The best tool for the task           |
+=====================================+======================================+
| Display console output for ordinary | :func:`print`                        |
| usage of a command line script or   |                                      |
| program                             |                                      |
+-------------------------------------+--------------------------------------+
| Report events that occur during     | :func:`logging.info` (or             |
| normal operation of a program (e.g. | :func:`logging.debug` for very       |
| for status monitoring or fault      | detailed output for diagnostic       |
| investigation)                      | purposes)                            |
+-------------------------------------+--------------------------------------+
| Issue a warning regarding a         | :func:`warnings.warn` in library     |
| particular runtime event            | code if the issue is avoidable and   |
|                                     | the client application should be     |
|                                     | modified to eliminate the warning    |
|                                     |                                      |
|                                     | :func:`logging.warning` if there is  |
|                                     | nothing the client application can do|
|                                     | about the situation, but the event   |
|                                     | should still be noted                |
+-------------------------------------+--------------------------------------+
| Report an error regarding a         | Raise an exception                   |
| particular runtime event            |                                      |
+-------------------------------------+--------------------------------------+
| Report suppression of an error      | :func:`logging.error`,               |
| without raising an exception (e.g.  | :func:`logging.exception` or         |
| error handler in a long-running     | :func:`logging.critical` as          |
| server process)                     | appropriate for the specific error   |
|                                     | and application domain               |
+-------------------------------------+--------------------------------------+

The logging functions are named after the level or severity of the events
they are used to track. The standard levels and their applicability are
described below (in increasing order of severity):

.. tabularcolumns:: |l|L|

+--------------+---------------------------------------------+
| Level        | When it's used                              |
+==============+=============================================+
| ``DEBUG``    | Detailed information, typically of interest |
|              | only when diagnosing problems.              |
+--------------+---------------------------------------------+
| ``INFO``     | Confirmation that things are working as     |
|              | expected.                                   |
+--------------+---------------------------------------------+
| ``WARNING``  | An indication that something unexpected     |
|              | happened, or indicative of some problem in  |
|              | the near future (e.g. 'disk space low').    |
|              | The software is still working as expected.  |
+--------------+---------------------------------------------+
| ``ERROR``    | Due to a more serious problem, the software |
|              | has not been able to perform some function. |
+--------------+---------------------------------------------+
| ``CRITICAL`` | A serious error, indicating that the program|
|              | itself may be unable to continue running.   |
+--------------+---------------------------------------------+

The default level is ``WARNING``, which means that only events of this level
and above will be tracked, unless the logging package is configured to do
otherwise.

Events that are tracked can be handled in different ways. The simplest way of
handling tracked events is to print them to the console. Another common way
is to write them to a disk file.


.. _howto-minimal-example:

A simple example
^^^^^^^^^^^^^^^^

A very simple example is::

   import logging
   logging.warning('Watch out!') # will print a message to the console
   logging.info('I told you so') # will not print anything

If you type these lines into a script and run it, you'll see::

   WARNING:root:Watch out!

printed out on the console. The ``INFO`` message doesn't appear because the
default level is ``WARNING``. The printed message includes the indication of
the level and the description of the event provided in the logging call, i.e.
'Watch out!'. Don't worry about the 'root' part for now: it will be explained
later. The actual output can be formatted quite flexibly if you need that;
formatting options will also be explained later.


Logging to a file
^^^^^^^^^^^^^^^^^

A very common situation is that of recording logging events in a file, so let's
look at that next. Be sure to try the following in a newly-started Python
interpreter, and don't just continue from the session described above::

   import logging
   logging.basicConfig(filename='example.log',level=logging.DEBUG)
   logging.debug('This message should go to the log file')
   logging.info('So should this')
   logging.warning('And this, too')

And now if we open the file and look at what we have, we should find the log
messages::

   DEBUG:root:This message should go to the log file
   INFO:root:So should this
   WARNING:root:And this, too
{'fraction_non_alphanumeric': 0.21661963463537798, 'fraction_numerical': 0.0, 'mean_word_length': 1.4925041643531372, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 36, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1317319', 'n_tokens_mistral': 2874, 'n_tokens_neox': 2708, 'n_words': 1320}