Logging¶

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 LogLevel class. The available levels are are summarized in the table below.

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

PushVerbosityLevel(verbosity)¶

Change the verbosity level to the given integer value or LogLevel enumeration object. All log events which have a severity above verbosity will not be shown. By default, the log level is 2, meaning that errors, warnings and script logging events are visible. By setting it to -1, you can disable all logging.

Parameters:	verbosity (int) – Desired verbosity level

# Display warnings and errors:
ost.PushVerbosityLevel(ost.LogLevel.Warning)

# Disable all logging:
ost.PushVerbosityLevel(-1)

PopVerbosityLevel()¶

Change the log level back to the previous verbosity level. It is an error to pop the verbosity level without a matching call to PushVerbosityLevel().

GetVerbosityLevel()¶

Returns:	The current verbosity level
Return type:	int

class LogLevel¶

Enumerates the logging levels (see Guidelines for picking logging level). Values:

Error, Warning, Script, Info, Verbose, Debug, Trace

The enumerated LogLevel object, which wraps the corresponding integer value. Note that these attributes are LogLevel objects themselves.

Type:	LogLevel

ost.LogLevel.Info
# Outputs: ost._ost_base.LogLevel.Info

print(ost.LogLevel.Info)
# Outputs: Info

int(ost.LogLevel.Info)
# Outputs: 3

These objects behave like integers, meaning that numeric comparisons work as expected. So for instance if you want to increase verbosity to the Info level, but leave it unchanged if it was already set to a higher value (such as Debug), you can do the following:

new_level = max(ost.GetVerbosityLevel(), ost.LogLevel.Info)
ost.PopVerbosityLevel()
ost.PushVerbosityLevel(new_level)

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.

class LogSink¶

LogMessage(message, severity)¶

This method is called whenever something gets logged. This method must be implemented by all subclasses.

Parameters:	message (str) – The logged message severity (int) – Marks how severe the logged message is. Errors have severity 0, warnings 1 etc.

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

class FileLogSink(filename)¶

The FileLogSink logs all messages into the given file.

Parameters:	filename (str) – The filename

class StreamLogSink(stream)¶

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')

class MultiLogSink¶

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

AddSink(sink)¶

Add a new sink. The sink’s LogSink.LogMessage() method will be called every time something gets logged.

Parameters:	sink (LogSink) – the log sink to be added

RemoveSink(sink)¶

Remove the given sink. If the doesn’t exist, this method has no effect.

Parameters:	sink (LogSink) – the log sink to be removed

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

PushLogSink(sink)¶

Push the new sink onto the log sink stack. All of the messages will now be logged to the new sink. To switch back to the previous log sink, use PopLogSink().

PopLogSink()¶

Change the log sink back to the previous one. It is an error to pop the log sink when there is only one log sink on the stack.

GetCurrentLogSink()¶

Get the current (active) log sink.

Guidelines for picking logging level¶

Each logging event has an associated level that marks its importance. For example, users should always see errors, but they do not need to see detailed information on the loading process. Here is a list of guidelines that we use in the code. We encourage developers to adhere to these guidelines as closely as possible.

Error:

Very important message to the user, some command did not complete as expected or was aborted.

Warning:

Diagnose potential problems that do not abort the execution, but may point to a misconfiguration/misuse. This level is turned on by default.

Script:

Logging level that should be used from scripts, e.g. to report progress. These logging messages are turned on by default.

Info:

Informative and important messages that summarize a complex command, such as information on a loaded file, or results from an algorithm. These logging messages are not turned on by default.

Verbose:

Grey-zone between user and developer need, and perhaps the hardest to get right. This is the lowest logging level users will be able to see when they use an optimized build. An example for this is the OpenGL setup/info in gfx, or the path search during startup, or more detailed info on file IO. These messages are not turned on by default.

Debug:

For developers, but not quite at the trace level. This level is turned off by default and only enabled when compiling with debugging symbols.

Trace:

Used to debug inner loops. Once turned on, you will probably get more debug output that you will be able to handle. This level is turned off by default and only enabled when compiling with debugging symbols.

Example¶

The following snippet explains how to create a custom log sink which logs to the terminal (or the python shell in DNG). The logger also prints the current time.

import datetime
class PyLogger(ost.LogSink):
  def __init__(self):
    ost.LogSink.__init__(self)

  def LogMessage(self, message, severity):
    levels=['ERROR', 'WARNING', 'SCRIPT', 'INFO',
            'VERBOSE', 'DEBUG', 'TRACE']
    level=levels[severity]
    print('%s[%s]: %s' % (level, str(datetime.datetime.now()), message))

py_logger=PyLogger()
ost.PushLogSink(py_logger)

ost.LogInfo("amazing logging system")