Logging

The logging facility allows messages to be written to the active output destination, depending on the currently active verbosity level. They differ slightly in their syntax for C++ and Python, but are in essence the same.

Verbosity Level

The verbosity level is an integer between 0 and 6, and is set in C++ using iplt::Verbosity::SetLevel(int n) (defined in <iplt/base.hh>). In Python, the function is named SetVerbosityLevel(n). The levels should be used in the following way:

0 = essential output: only the absolutely necessary messages should be given this level, as there is no way to turn them off. Fatal error messages certainly fall into this category.

1 = normal output: the normal, informative output, such as the initiation of high-level processing steps in a script. Non-fatal errors or other minor problems should be here as well.

2 = verbose output: more information than for level 1, such as interesting results from high-level processing steps.

4 = debug output: the classical debug information to display parameters and assumptions and intermediate results.

5 = dump output: this goes beyond the normal debug output, and should be used to log detailed steps within algorithms or procedures, but not inside inner loops

6 = trace output: debug information that includes inner loops and very intermediate calculation results

Writing Messages

In C++, the log messages are written using the normal << stream operator, with a special target ostream provided by the iplt::mlog(int n) function; the integer parameter indicates the verbosity level this particular message belongs to; if the number is higher than the current verbosity level (see above), the message will be ignored. In Python, there are two functions variants of this, in the form mlog(level,string) and mlogn(level,string), where the latter appends a newline after string has been written out. Note that the usual formatting capabilities apply for this Python string 9see example below).

Output Destination

Initially, the logging output is directed to the text or graphical terminal. With iplt::Verbosity::PushFile(string filename), a file of the given name will be used as the output. The Verbosity class maintains a stack of such output files, so that the previous output is restored with a call to iplt::Verbosity::Pop(). In Python, these functions are named PushVerbosityFile(filename) and PopVerbosity(), respectively.

Examples

def f():
  mlogn(0,"essential output")
  mlogn(1,"normal output")
  mlogn(2,"verbose output")
  mlogn(4,"debug output")
  mlogn(5,"detailed dump output")
  x=range(10)
  mlogn(6,"very detailed trace output: %s"%(str(range)))

SetVerbosityLevel(1)
f()
SetVerbosityLevel(5)
PushVerbosityFile("dump.log")
f()
PopVerbosity()

#include <iplt/message.hh>

using namespace iplt;

void f() 
{
  mlog(0) << "essential output" << std::endl;
  mlog(1) << "normal output" << std::endl;
  mlog(2) << "verbose output" << std::endl;
  mlog(4) << "debug output" << std::endl;
  mlog(5) << "detailed dump output" << std::endl;
  mlog(6) << "very detailed trace output" << std::endl;
}

int main()
{
  Verbosity::SetLevel(1);
  f();
  Verbosity::SetLevel(5);
  Verbosity::PushFile("dump.log")  
  f();
  Verbosity::PopFile()
  return;
}