Logging

The logging API provides four main parts (basics, filtering, threading & blackbox).

The idea behind this logging system is not to be prescriptive but to provide a set of tools to help the developer achieve what they want quickly and easily.

Basic logging API.

Call qb_log() to generate a log message. Then to write the message somewhere meaningful call qb_log_ctl() to configure the targets.

Simplist possible use:

main() {
     qb_log_init("simple-log", LOG_DAEMON, LOG_INFO);
        // ...
     qb_log(LOG_WARNING, "watch out");
        // ...
     qb_log_fini();
}

Configuring log targets.

A log target can by syslog, stderr, the blackbox or a text file. By default only syslog is enabled.

To enable a target do the following

qb_log_ctl(QB_LOG_BLACKBOX, QB_LOG_CONF_ENABLED, QB_TRUE);

syslog, stderr and the blackbox are static (they don't need to be created, just enabled or disabled. However you can open multiple logfiles (32 - QB_LOG_BLACKBOX). To do this use the following code.

mytarget = qb_log_file_open("/var/log/mylogfile");
qb_log_ctl(mytarget, QB_LOG_CONF_ENABLED, QB_TRUE);

Once your targets are enabled/opened you can configure them as follows: Configure the size of blackbox

qb_log_ctl(QB_LOG_BLACKBOX, QB_LOG_CONF_SIZE, 1024*10);

Make logging to file threaded:

qb_log_ctl(mytarget, QB_LOG_CONF_THREADED, QB_TRUE);

To workaround your syslog daemon filtering all messages > LOG_INFO

qb_log_ctl(QB_LOG_SYSLOG, QB_LOG_CONF_PRIORITY_BUMP,
      LOG_INFO - LOG_DEBUG);

To ensure all logs to file targets are fsync'ed (default QB_FALSE)

qb_log_ctl(mytarget, QB_LOG_CONF_FILE_SYNC, QB_TRUE);

Filtering messages.

To have more power over what log messages go to which target you can apply filters to the targets. What happens is the desired callsites have the correct bit set. Then when the log message is generated it gets sent to the targets based on which bit is set in the callsite's "target" bitmap. Messages can be filtered based on the:

1. filename + priority
2. function name + priority
3. format string + priority

So to make all logs from evil_fnunction() go to stderr do the following:

qb_log_filter_ctl(QB_LOG_STDERR, QB_LOG_FILTER_ADD,
             QB_LOG_FILTER_FUNCTION, "evil_fnunction", LOG_TRACE);

So to make all logs from totem* (with a priority <= LOG_INFO) go to stderr do the following:

qb_log_filter_ctl(QB_LOG_STDERR, QB_LOG_FILTER_ADD,
             QB_LOG_FILTER_FILE, "totem", LOG_INFO);

So to make all logs with the substring "ringbuffer" go to stderr do the following:

qb_log_filter_ctl(QB_LOG_STDERR, QB_LOG_FILTER_ADD,
             QB_LOG_FILTER_FORMAT, "ringbuffer", LOG_TRACE);

Threaded logging.

To achieve non-blocking logging you can use threaded logging. So any calls to write() or syslog() will not hold up your program.

Threaded logging use:

main() {
     qb_log_init("simple-log", LOG_DAEMON, LOG_INFO);
     qb_log_ctl(QB_LOG_SYSLOG, QB_LOG_CONF_THREADED, QB_TRUE);
        // ...
        daemonize();
        // call this after you fork()
        qb_log_thread_start();
        // ...
     qb_log(LOG_WARNING, "watch out");
        // ...
     qb_log_fini();
}

A blackbox for in-field diagnosis.

This stores log messages in a ringbuffer so they can be written to file if the program crashes (you will need to catch SIGSEGV). These can then be easily printed out later.

Note

the blackbox is not enabled by default.

Blackbox usage:

static void sigsegv_handler(int sig)
{
        (void)signal (SIGSEGV, SIG_DFL);
        qb_log_blackbox_write_to_file("simple-log.fdata");
        qb_log_fini();
        raise(SIGSEGV);
}

main() {

     signal(SIGSEGV, sigsegv_handler);

     qb_log_init("simple-log", LOG_DAEMON, LOG_INFO);
     qb_log_filter_ctl(QB_LOG_BLACKBOX, QB_LOG_FILTER_ADD,
                  QB_LOG_FILTER_FILE, "*", LOG_DEBUG);
     qb_log_ctl(QB_LOG_BLACKBOX, QB_LOG_CONF_SIZE, 1024*10);
     qb_log_ctl(QB_LOG_BLACKBOX, QB_LOG_CONF_ENABLED, QB_TRUE);
        // ...
     qb_log(LOG_WARNING, "watch out");
        // ...
     qb_log_fini();
}

Tagging messages.

You can tag messages using the second argument to qb_logt() or by using qb_log_filter_ctl(). This can be used to add feature or sub-system information to the logs.

const char* my_tags_stringify(uint32_t tags) {
        if (qb_bit_is_set(tags, QB_LOG_TAG_LIBQB_MSG_BIT) {
                return "libqb";
        } else if (tags == 3) {
                return "three";
        } else {
                return "MAIN";
        }
}
main() {
        // ...
        qb_log_tags_stringify_fn_set(my_tags_stringify);
        qb_log_format_set(QB_LOG_STDERR, "[%5g] %p %b");
        // ...
        qb_logt(LOG_INFO, 3, "hello");
        qb_logt(LOG_INFO, 0, "hello");
}

The code above will produce:

[libqb] some message
[three] info hello
[MAIN ] info hello

See Also

qblog.h