LoggingGoodPractice

From MantidProject

Contents 1 Logging Within Mantid 2 How to include a logger in your class 3 What to log at the various levels 4 Configuring the logging service 4.1 How to change the logging configuration 5 Logging complex data 5.1 If logging data that takes significant resources tgenerate the message 5.2 If you need to dump binary data

Logging Within Mantid

Logging is provided by two classes within the Manrid Kernel.

• Logger - This provides the majority of the logging functionality.
• ConfigService - This configures the logging service on first instantiation.

Both of these classes are thin wrappers on top of the logging functionality provided by the POCO library.

How to include a logger in your class

in the .h

#include "Logger.h"

class A
{
  private:
 
    /// Static reference to the logger class
    static Logger& g_log;
}

in your .cpp

Logger& FrameworkManager::g_log = Logger::get("FrameworkManager");

A::func()
{
  g_log.error("Log message");
}

What to log at the various levels

Level	What to log
Debug	Anything that may be usefull to understand what the code has been doing for debugging purposes. e.g. Parameter values, "I got here" lines, internal variable values. Log at this level often throughout your code.
Information	Useful information to relay back to the user of the framework.
Warning	Something was wrong, but the framework was able to continue despite the problem.
Error	An error has occured but the framework is able to handle it and continue.
Fatal	An unrecoverable error has occured and the application will terminate

Configuring the logging service

For the logging to work you will need to have configured the logging service. This will occur when you do either of the following.

• Call FrameworkManager.initialise().
• Get a refence to the ConfigService singleton.

When the framework is initialised it attempts to read a file called Mantid.properties that it assumes will be available in the current working directory. This contains among other things the logging configuration.

Here is an example

logging.loggers.root.level = debug
logging.loggers.root.channel.class = SplitterChannel
logging.loggers.root.channel.channel1 = consoleChannel
logging.loggers.root.channel.channel2 = fileChannel
logging.channels.consoleChannel.class = ConsoleChannel
logging.channels.consoleChannel.formatter = f1
logging.channels.fileChannel.class = FileChannel
logging.channels.fileChannel.path = mantid.log
logging.channels.fileChannel.formatter.class = PatternFormatter
logging.channels.fileChannel.formatter.pattern = %Y-%m-%d %H:%M:%S,%i [%I] %p %s - %t
logging.formatters.f1.class = PatternFormatter
logging.formatters.f1.pattern = %s-[%p] %t
logging.formatters.f1.times = UTC

This specifiy that the logging comments will go to the console as well as a file called mantid.log. In the example here the level is set to debug, so all messages will be output. In production this will usually be set to Information.

How to change the logging configuration

Within the code you can get the logging service to configure from a different file using the LoadConfig method on the Configuration Service and specifying a different file. The ConfigServiceTest class shows an example of this.

Logging complex data

If logging data that takes significant resources tgenerate the message

Use the is(priority) function of the logger to check if the message would actually be output.

if (g_log.is(Logger::PRIO_DEBUG))
{
  //generate message and output to log.
}

If you need to dump binary data

Use the dump method of the logger. Note that all dump messages are sent at debug level.

/// Logs the given message at debug level, followed by the data in buffer.
void dump(const std::string& msg, const void* buffer, std::size_t length);