ArmarX Logging

Every output in ArmarX should be done with the built-in logging features. The ArmarX logging facilities are available anytime and anywhere in the code and should be used instead of std::cout or printf().
ArmarX Logging provides the following main features:

• usable like std::cout
• stores meta data like file, line, time, who etc.
• offers several different log levels (from debug to fatal)
• can log backtraces
• provides logs over network (Ice)
• LogViewer (GUI) which works through Ice
• thread safety
• console coloring
• redirection of std::cout/cerr to ArmarX log

How to use the ArmarX logging facilities

For logging there are a few macros available (e.g. "ARMARX_INFO"). They all begin with "ARMARX_". Followed by the log level (e.g. "ARMARX_INFO").

An example looks like this:

ARMARX_INFO << "cycle time dropped below " << 1 << " fps in Capturer";

After the c++-line has ended (i.e. after the semi-colon), the data is written as one entry into the log.

To be able use the logging facilities, one has to include the file <ArmarXCore/core/logging/Logging.h>.

If you want to use all logging features, you need to let your class inherit from armarx::Logging. Then features like tagging and spam-deactivation are available.

Note

To log inside a static function of a class inheriting from Logging, you have to use the logging macros ending on _S, e.g. ARMARX_INFO_S.

If the current minimum log-level is below the used log level, the output string calculation is completly skipped. This means no code with effect on any variable should be put into the logging-code-line. This also means it is performance-wise safe to have a lot debug messages in the code.

The main features in detail:

• usable like std::cout
  The usage of ArmarX logging works like std::cout. That means after the macro (e.g. "ARMARX_INFO") follows the streaming operator (<<). There are conversions for all of the standard types available like with std::cout and some additional types (e.g. std::vector, QString in Gui). These can be easily extended by overloading/specializing the armarx::LogSender::operator<< <T>().
• stores meta data like file, line, time, who etc.
  At the moment the logging stores the following meta data: time, tag, log-level, Ice-component, file, line, function, threadId and backtrace (for log-level eWARN and above).
• offers several different log levels (from debug to fatal)
  There are 5 log levels available. In order of increasing severity: debug, verbose, info, warning, error, fatal (The corresponding macros are: ARMARX_DEBUG, ARMARX_VERBOSE, ARMARX_INFO, ARMARX_WARNING, ARMARX_ERROR, ARMARX_FATAL).
• can log backtraces
  For the log levels warning and above a backtrace is stored in the meta data. For lower levels the backtrace is empty to reduce the network traffic.
  The backtrace is not shown in the console, only in the LogViewer.
• provides logs over network (Ice)
  All log output is automatically streamed via Ice, if an Ice connection is available.
  If the connection is not established yet, all log outputs are buffered locally until the connection is ready.
  The logging facilties are using the publish-subscribe-methodology of Ice for this, so potential log-viewers can just subscribe to the topic "Log"(Type: LogPrx).
• LogViewer (GUI)
  The LogViewer is an ArmarX Gui Widget, that provides a comfortable access to the logs. It offers the possibility to define custom filters, to split the data in several logs, to search quickly through the log file and much more.
• thread safety
  As opposed to std::cout the ArmarX logging facilities are thread safe. So there is no mixing of log entries of different threads.
• console coloring
  If activated (default) the output on the console of different log levels is colorized. Additionally, the user can just use the streaming operator << and the LogSender color enum (e.g. LogSender::eGreen) to set the color for the current output message.