You are reading the documentation for version 1.6 of OpenStructure. You may also want to read the documentation for:
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.
Add a message to the log. For the choice of the appropriate logging level,
see Guidelines for picking logging level.
|Parameters:||message (convertible to string) – The message to be logged
Similar to the built-int print function, several arguments can be passed to
the logging functions. The arguments will be converted to string and then
concatenated together, separated by space. For example:
LogMessage('here be numbers', 1, 2)
will be converted to ‘here be numbers 1 2’.
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.
You can change the verbosity level with the following two methods:
Change the verbosity level to the given integer value. All log events
which have a severity above verbosity will be ignored. By default, the log
level is 2, meaning that errors, warnings and script logging events are
Change the log level back to the previous verbosity level. It is an error to
pop the verbosity level without a matching call to
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.
This method is called whenever something gets logged. This method must be
implemented by all subclasses.
- 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.
The FileLogSink logs all messages into the given file.
str) – The filename
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
A LogSink for multiplexing the log messages into multiple sinks at the same
time, e.g. the terminal and the messages widget.
Add a new sink. The sink’s
LogSink.LogMessage() method will be called
every time something gets logged.
LogSink) – the log sink to be added
Remove the given sink. If the doesn’t exist, this method has no effect.
LogSink) – the log sink to be removed
To change the current log sink you can use the following methods:
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
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.
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.
- Cannot be silenced, very important message to the user, some command did not
complete as expected or was aborted.
- Diagnose potential problems that do not abort the execution, but may
point to a misconfiguration/misuse. This level is turned on by default.
- Logging level that should be used from scripts, e.g. to report progress. These
logging messages are turned on by default.
- 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.
- 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.
- For developers, but not quite at the trace level. This level is turned off by
default, not available in Python and only enabled when compiling with
- 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,
not available in python and only enabled when compiling with debugging
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.
def LogMessage(self, message, severity):
levels=['ERROR', 'WARNING', 'SCRIPT', 'INFO',
'VERBOSE', 'DEBUG', 'TRACE']
print '%s[%s]: %s' % (level, str(datetime.datetime.now()), message),
ost.LogInfo("amazing logging system")
Enter search terms or a module, class or function name.
ost - OpenStructure Base Module
ost.settings - Locate Files and Retrieve Preferences
You are here