Commit d4e63784 authored by Kloss's avatar Kloss
Browse files

update logging

parent de460130
...@@ -3,11 +3,16 @@ ...@@ -3,11 +3,16 @@
Logging 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 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. 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 handlers (see below) and logging warning messages is enabled by the following
lines of code: lines of code:
...@@ -16,32 +21,32 @@ lines of code: ...@@ -16,32 +21,32 @@ lines of code:
import tkwant import tkwant
import logging 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. *before* executing any tkwant code.
Handlers Handlers
~~~~~~~~ ~~~~~~~~
The handlers contains the format of the logging output. The handler contains the format of the logging output.
Tkwant has implemented two predifined stream handlers: Tkwant has implemented two predefined stream handlers:
``tkwant._logging.debug_handler`` and ``tkwant._logging.simple_handler``. ``tkwant.logging.debug_handler`` and ``tkwant.logging.simple_handler``.
The debug handler, which was already used in above example, The debug handler, which was already used in above example,
prints the logging message in the format: prints the logging message in the format:
*level*: *module-name*: *line-number*: *MPI-rank*: *log message* *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. that might be different to the rank of sub-communicators.
The simple handler is less verbose and prints only the log message. 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 As an example, the line
.. jupyter-execute:: .. jupyter-execute::
tkwant._logging.handler = tkwant._logging.simple_handler tkwant.logging.handler = tkwant.logging.simple_handler
would use the simple handler for logging. would use the simple handler for logging.
Alternative handlers whose API matches the logging module of the Alternative handlers whose API matches the logging module of the
...@@ -54,16 +59,16 @@ Level ...@@ -54,16 +59,16 @@ Level
Logging has several severity levels to control which level of log messages are Logging has several severity levels to control which level of log messages are
recorded. By default, tkwant is logging only warning messages recorded. By default, tkwant is logging only warning messages
(corresponding to ``logging.WARNING``). (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 defined in the Python logging module.
As an example, to log also progress information, the additional line of code As an example, to log also progress information, the additional line of code
must be added: must be added:
.. jupyter-execute:: .. 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 *before* executing any tkwant code. The most verbose output is generated by setting
the level to ``logging.DEBUG``. the level to ``logging.DEBUG``.
...@@ -72,12 +77,12 @@ Filters ...@@ -72,12 +77,12 @@ Filters
~~~~~~~ ~~~~~~~
The logging output can be filtered to reduce the output to specific parts. 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 on can set
.. jupyter-execute:: .. 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 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): 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 ...@@ -87,7 +92,7 @@ logs only the messages from MPI with rank zero (which is typically the root rank
def rank_filter(record): def rank_filter(record):
return True if record.rank == 0 else False 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 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 ...@@ -96,8 +101,18 @@ If one likes to log only messages containing the word *interval* one can use
def message_filter(record): def message_filter(record):
return True if 'interval' in record.getMessage() else False 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* Again, the filter must be set *after* importing the tkwant module and *before*
executing any tkwant code. The documentation of Python standard library logging executing any tkwant code. The documentation of the Python standard library logging
module provides more information to write custom filters. 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 ...@@ -12,13 +12,15 @@ import os
from ._common import version as __version__ # pragma: no flakes from ._common import version as __version__ # pragma: no flakes
from ._common import TkwantDeprecationWarning 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)) exec('from . import {0}'.format(module))
__all__.append(module) __all__.append(module)
# to make stuff available in tkwant namespace # to make stuff available in tkwant namespace
# available = [ # available = [
# ('system', []) # ('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