The library (and ContexKit in general) use a simple logging system designed to unify the output and make the debugging easier.

API

Four types of log messages (presented here in the order of importance) are supported: Test, Debug, Warning and Critical.

The first one, the Test message requires some attention. It's meant to be used from tests and unit-tests to log various stages of the test execution. It'll make the test output more easily filterable.

The log messages can be used like this:

    contextTest() << "This is some message";
    contextDebug() << "My value is:" << someVariable;
    contextWarning() << "Expecting key:" << something.getKey();
    contextCritical() << 5 << "is bigger than" << 4;

Notice that the logging framework (very much like ie qDebug) automatically ads whitespace. So:

    contextDebug() << "My value is" << 5 << "and should be 5";

...will actually print:

    My value is 5 and should be 5

Compile-time verbosity control

During the compile time certain defines can be used to turn-off debug messages. Those defines are:

    CONTEXT_LOG_HIDE_TEST
    CONTEXT_LOG_HIDE_DEBUG
    CONTEXT_LOG_HIDE_WARNING
    CONTEXT_LOG_HIDE_CRITICAL

A given define makes a respective macro message evaluate to an empty code. To be precise: it makes the macro message evaluate to an inline do-nothing class that is optimized by the compiler to do nothing.

When ie. CONTEXT_LOG_HIDE_DEBUG define is used to turn off contextDebug() messages, the actual string content of the debug messages is not included in the binary and during runtime the machine does not spend time evaluating it.

Those compile-time control defines are integrated in the build/configure system.

Run-time verbosity control

During run-time, the amount of debugging can be limited (filtered) but it can't be increased (expanded). In other words, if a package was compiled with warnings-only, it's not possible to make it show debug messages at runtime. But it is possible to make it criticals-only.

The filtering happens via env variables. The major player is the CONTEXT_LOG_VERBOSITY variable which can be set to TEST, DEBUG, WARNING and CRITICAL. The CONTEXT_LOG_VERBOSITY specifies the minimal level of the messages shown. Ie. CONTEXT_LOG_VERBOSITY set to WARNING will show only warning and criticals.

The format of the output can be tweaked with CONTEXT_LOG_HIDE_TIMESTAMPS and CONTEXT_LOG_USE_COLOR. The first one makes the messages shorter by skipping the timestamp info. The second one adds a little bit of ANSI coloring to the messages.

CONTEXT_LOG_SHOW_MODULE will filter-out (kill) all messages except the ones coming from the specified module. Ie.:

    CONTEXT_LOG_SHOW_MODULE="subscriber" ./some-binary

...will run ./some-binary showing log messages only from subscriber module.

Lastly, CONTEXT_LOG_HIDE_MODULE will hide log messages coming from the specified module. All other messages will be show.

Modules in logging

In previous section we discussed and mentioned modules. For the purpose of logging, a module is a piece of code (not neccesarily limited to one binary or shared object) that forms one component (feature-wise). Specyfying and naming the modules is used to set the origin of the logging messages.

The logging module is set using the CONTEXT_LOG_MODULE_NAME define. It should be (in most cases) defined in the build system and automatically applied to the whole source code. Typically (with autotools) this can be achieved with something similar too:

    ...
    AM_CXXFLAGS = '-DCONTEXT_LOG_MODULE_NAME="libtest"'
    ...

If CONTEXT_LOG_MODULE_NAME is undefined, the log messages will be marked as coming from an "Undefined" module.

Featues

It's possible also to assign logging messages to feature groups and control the output based on that. Features can be compared to tags - one message can belong to zero or more features. To add to a feature to a log message:

    contextDebug() << contextFeature("threads") << "Message goes here" << someVariable;
    contextDebug() << contextFeature("threads") << contextFeature("something") << "Message...";

It doesn't matter where features are added to the message. There is no specific order required. The following syntax is supported as well:

    contextDebug() << contextFeature("threads") << "Some message..." << contextFeature("another");

Vanilla

If the default logging output is too much for you, it's possible to set a CONTEXT_LOG_VANILLA enviornment variable. This will simplify the logging output greatly -- no timestamps will be printed, no module information will be printed, no line/function/class info will be printed.

Generated on Sun Apr 21 16:11:51 2013 for libcontextsubscriber by  doxygen 1.5.6