logging.rst

Logging

OpenStructure has a logging system going beyond what print statements can offer. Messages can be logged to the terminal to the graphical user interface or a file. Depending on the needs, groups of messages can be turned and off.

Note

In C++, the logging facility is implemented as a set of macros, called LOG_ERROR, LOG_WARNING, LOG_SCRIPT, LOG_INFO, LOG_VERBOSE, LOG_DEBUG and LOG_TRACE. The last two are only active when compiling with debugging symbols. When debugging symbols are off, they expand to an empty macro and thus don't create any overhead.

Verbosity Level

Several verbosity levels are available. Verbosity levels are represented by an enumeration of integer values. They are wrapped to objects with memorable names by the :class:`LogLevel` class. The available levels are are summarized in the table below.

Level name	Verbosity value	LogLevel object
Error	0	LogLevel.Error
Warning	1	LogLevel.Warning
Script	2	LogLevel.Script
Info	3	LogLevel.Info
Verbose	4	LogLevel.Verbose
Debug	5	LogLevel.Debug
Trace	6	LogLevel.Trace

You can change the verbosity level with the following two methods:

Enumerates the logging levels (see :ref:`picking-logging-level`). Values:

Log sinks

When running OpenStructure from the command-line, the log messages are by default output to stderr. When running DNG, the log messages are additionally logged to the messages widget. However, it is also possible to log into a file or theoretically even to a remote computer. All these are instances of so-called log sinks: classes that derive from LogSink and implement the LogMessage method.

For convenience, there are 3 LogSink implementations available in OpenStructure that are sufficient for most use cases.

The FileLogSink logs all messages into the given file.

param filename:	The filename
type filename:	:class:`str`

The stream log sink writes all log messages to the stream. stream must have a write method that accepts a string. To write messages to stderr, use

stderr_sink=ost.StreamLogSink(sys.stderr)
ost.PushLogSink(stderr_sink)
ost.LogInfo('Welcome, master')

A LogSink for multiplexing the log messages into multiple sinks at the same time, e.g. the terminal and the messages widget.

To change the current log sink you can use the following methods: