15. Logging and Console Output

The Febrl system is provided with a logging system that can display and save to a file logging information with different levels (i.e. different details of output). A project log can be initialised in a project.py module as shown in the code example below. It is assumed that the febrl.py module has been imported using the from febrl import * command (as the init_febrl_logger() function is implemented in the febrl module). A project log should be initialised first thing in a project module, as shown in Chapter 5. See the Python standard module logging.py for more details about the Python logging system.

# ====================================================================

init_febrl_logger(log_file_name = 'example-febrl-project.log',
                     file_level = 'WARNING',
                  console_level = 'INFO',
                      clear_log = False,
                parallel_output = 'host')

The following arguments need to be given to a project log when it is initialised.

log_file_name
The name of the text file into which logging information is saved. If set to None (the default) no logging information will be saved (but still displayed).

file_level
The level of logging information that is written to the log file (if set to a file name). Possible values are: 'NOTSET', 'DEBUG', 'INFO', 'WARNING', 'ERROR', and 'CRITICAL', with decreasing level of logging information being written (i.e. all log messages are written when the level is set to 'NOTSET', and only critical information is written when set to 'CRITICAL'). A useful amount of information is logged if the level is set to 'WARNING'. A current limitation is that the file log level can only be equal to or higher than the console level. If the console level is higher, then the file level is set to the console level as well by the Python logging system.

console_level
The level of logging information that is displayed in the console (terminal window). The same levels as with file_level are possible. Useful levels are 'INFO' or 'WARNING'.

clear_log
A flag that can be set to True or False (default is False). When set to True, all information stored in the given log file is deleted first, and a new log is started. Otherwise, logging information is appended to a log file (if it exists, otherwise it is created first).

parallel_output
This argument defines how displaying and logging is done when Febrl is run in parallel. Possible values are either 'host' (the default) in which case only the host process (where Febrl has been started on) is displaying and logging messages, or 'all' in which case all processes are displaying and logging. Note that when run in parallel each process writes it's own log file.

Note: The current version of the Febrl system only supports logging into text files. Future version will provide logging into other formats as well, for example HTML, XML or LaTeX.