Commit d4e63784 authored by Kloss's avatar Kloss
Browse files

update logging

parent de460130
......@@ -3,11 +3,16 @@
Logging
=======
Tkwant provides a logger which, by default, is switched of.
Tkwant provides a logger which, by default, is switched off.
Enabling the logger can help to find errors in the user code and also facilitate
debugging tkwant.
debugging tkwant. Note that this is no general introduction to logging and we refer
to the
`Logging HOWTO
<https://docs.python.org/3/howto/logging.html#logging-basic-tutorial>`__
tutorial for more information.
Tkwant's logger is based on logging module of the Python standard library.
To activate logging, a logging handler must be set. Tkwant has predifined
To activate logging, a logging handler must be set. Tkwant has predefined
handlers (see below) and logging warning messages is enabled by the following
lines of code:
......@@ -16,32 +21,32 @@ lines of code:
import tkwant
import logging
tkwant._logging.handler = tkwant._logging.debug_handler
tkwant.logging.handler = tkwant.logging.debug_handler
Note that logging handler must be set after importing the tkwant module and
Note that logging handler must be set *after* importing the tkwant module and
*before* executing any tkwant code.
Handlers
~~~~~~~~
The handlers contains the format of the logging output.
Tkwant has implemented two predifined stream handlers:
``tkwant._logging.debug_handler`` and ``tkwant._logging.simple_handler``.
The handler contains the format of the logging output.
Tkwant has implemented two predefined stream handlers:
``tkwant.logging.debug_handler`` and ``tkwant.logging.simple_handler``.
The debug handler, which was already used in above example,
prints the logging message in the format:
*level*: *module-name*: *line-number*: *MPI-rank*: *log message*
Note that the MPI rank corresponds to the rank of tkwants global MPI communicator
Note that the MPI rank corresponds to the rank of tkwant's global MPI communicator
that might be different to the rank of sub-communicators.
The simple handler is less verbose and prints only the log message.
To use a handler, one has to set ``tkwant._logging.handler`` to it.
To use a handler, one has to set ``tkwant.logging.handler`` to it.
As an example, the line
.. jupyter-execute::
tkwant._logging.handler = tkwant._logging.simple_handler
tkwant.logging.handler = tkwant.logging.simple_handler
would use the simple handler for logging.
Alternative handlers whose API matches the logging module of the
......@@ -54,16 +59,16 @@ Level
Logging has several severity levels to control which level of log messages are
recorded. By default, tkwant is logging only warning messages
(corresponding to ``logging.WARNING``).
To change the log level, one has set ``tkwant._logging.level`` to a level,
To change the log level, one has set ``tkwant.logging.level`` to a level,
as defined in the Python logging module.
As an example, to log also progress information, the additional line of code
must be added:
.. jupyter-execute::
tkwant._logging.level = logging.INFO
tkwant.logging.level = logging.INFO
Again, the logging level must be set after importing the tkwant module and
Again, the logging level must be set *after* importing the tkwant module and
*before* executing any tkwant code. The most verbose output is generated by setting
the level to ``logging.DEBUG``.
......@@ -72,12 +77,12 @@ Filters
~~~~~~~
The logging output can be filtered to reduce the output to specific parts.
To log only logging events triggerted by a certain module, as e.g. ``tkwant.leads``,
To log only logging events triggered by a certain module, as e.g. ``tkwant.leads``,
on can set
.. jupyter-execute::
tkwant._logging.filter = logging.Filter('tkwant.leads')
tkwant.logging.filter = logging.Filter('tkwant.leads')
Alternatively, one can also define a filter function. The following code
logs only the messages from MPI with rank zero (which is typically the root rank):
......@@ -87,7 +92,7 @@ logs only the messages from MPI with rank zero (which is typically the root rank
def rank_filter(record):
return True if record.rank == 0 else False
tkwant._logging.filter = rank_filter
tkwant.logging.filter = rank_filter
If one likes to log only messages containing the word *interval* one can use
......@@ -96,8 +101,18 @@ If one likes to log only messages containing the word *interval* one can use
def message_filter(record):
return True if 'interval' in record.getMessage() else False
tkwant._logging.filter = message_filter
tkwant.logging.filter = message_filter
Again, the filter must be set after importing the tkwant module and *before*
executing any tkwant code. The documentation of Python standard library logging
Again, the filter must be set *after* importing the tkwant module and *before*
executing any tkwant code. The documentation of the Python standard library logging
module provides more information to write custom filters.
References
----------
`Logging HOWTO
<https://docs.python.org/3/howto/logging.html#logging-basic-tutorial>`__
`Python standard library logging module documentation
<https://docs.python.org/3/library/logging.html>`__
......@@ -12,13 +12,15 @@ import os
from ._common import version as __version__ # pragma: no flakes
from ._common import TkwantDeprecationWarning
from . import _logging as logging
__all__ = ['TkwantDeprecationWarning']
__all__ = ['TkwantDeprecationWarning', 'logging']
for module in ('system', 'leads', 'onebody', 'manybody', 'mpi', '_logging'):
for module in ('system', 'leads', 'onebody', 'manybody', 'mpi'):
exec('from . import {0}'.format(module))
__all__.append(module)
# to make stuff available in tkwant namespace
# available = [
# ('system', [])
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment