Logging Concept

Table of Contents

• Basic Information on Logging
• Categorize your Logging Messages
• Logging Levels
• Conditional Logging

Basic Information on Logging

To use logging in MITK you can stream your messages into a logging stream, similar to the "std::cout" stream in standard c++. A simple example is shown next.

MITK_INFO << "Here comes my message";

Please only use the MITK_INFO (respectively MITK_WARN, MITK_ERROR, MITK_FATAL, MITK_DEBUG, see Logging Levels for more details) in MITK, the std::cout stream should not be used. You can also log object information, like shown in the next example.

MITK_INFO << "I want to log my vector size: " << m_vector.getSize();

All logged information will be displayed in the console and be written to a logging file in the MITK binary folder. Advanced users may want to know that this behavior is controlled by the logging backend class, which can be adapted if you want to change the behavior. This is everything you need to know about simple logging. Further reading will show you how you can categorize your logging message and what logging levels are.

Categorize your Logging Messages

You may also want to categorize your logging messages, so you can assign messages to your specific topic. You can simply add classes and subclasses to your MITK logging messages by using brackets, like shown in the next example.

MITK_INFO << "no class";
MITK_INFO("MyClass") << "single class";
MITK_INFO("MyClass")("MySubClass") << "class with subclass";

This classes makes it easy to e.g. simply filter all logging messages only for relevant information.

Logging Levels

MITK offers different logging levels. You may mostly want to use MITK_INFO, but please consider using the other levels, e.g. when logging debug information or errors.

Debug (MITK_DEBUG): These messages are designed for debug output, used to debug your source code. Example:

MITK_DEBUG << "Result of method LoadPicture(): true."

These messages are only displayed if you turn the CMake-Variable MBILOG_ENABLE_DEBUG_MESSAGES on. You can also use the debug message in release mode, output only depends on the CMake-Variable. If you want to enable the debug messages only for a single class / module / plugin you can also simply define the variable in your source code for the time you want to see the messages. Therefore you add a line "#define MBILOG_ENABLE_DEBUG" in the beginning of your cpp file. But don't forget to remove the definition before commiting the source code.

Info (MITK_INFO): For standard information messages that inform about expected changes/results in the program flow. Info messages should be important and understandable for the users of the program.

Example:

MITK_INFO << "The picture test.pic has been loaded successfully."

Warning (MITK_WARN): Warning messages should inform about unexpected or potentially problematic states in the program flow that do not lead directly to an error. Thus, after a warning the program should be able continue without errors and in a clear state.

Example:

MITK_WARN << "The picture test.pic was not loaded because access was denied."

Error (MITK_ERROR): Error messages notify the user about corrupt states in the program flow. Such states may occur after unexpected behavior of source code.

Example:

MITK_ERROR << "Error while adding test.pic to the data storage, aborting."

Fatal (MITK_FATAL): Fatal messages report corrupt states in the program flow that lead directly to a crash of the program.

Example:

MITK_FATAL << "Memory allocation error during instantiation of image object."

Conditional Logging

Another feature of the logging mechanism is that you can directly give conditions for logging your message. These bool values or expressions can be defined in brackets. An example is shown next.

MITK_INFO(x>1000) << "x is too large"; //logs only if x > 1000