qblog.h (3)

#include <stdint.h>

#include <stdlib.h>

#include <stdio.h>

#include <stdarg.h>

#include <errno.h>

#include <syslog.h>

#include <string.h>

#include <qb/qbutil.h>

#include <qb/qbconfig.h>

Data Structures

struct qb_log_callsite

An instance of this structure is created in a special ELF section at every dynamic debug callsite.

Defines

#define LOG_TRACE (LOG_DEBUG + 1)

#define QB_LOG_MAX_LEN 512

#define QB_LOG_STRERROR_MAX_LEN 128

#define QB_LOG_INIT_DATA(name)

#define QB_LOG_TAG_LIBQB_MSG_BIT 31

#define QB_LOG_TAG_LIBQB_MSG (1 << QB_LOG_TAG_LIBQB_MSG_BIT)

#define qb_logt(priority, tags, fmt, args...)

This is the function to generate a log message if you want to manually add tags. #define qb_log(priority, fmt, args...) qb_logt(priority, 0, fmt, ##args)

This is the main function to generate a log message. #define qb_perror(priority, fmt, args...)

This is similar to perror except it goes into the logging system. #define qb_enter() qb_log(LOG_TRACE, 'ENTERING %s()', __func__)

#define qb_leave() qb_log(LOG_TRACE, 'LEAVING %s()', __func__)

#define QB_LOG_SYSLOG 0

#define QB_LOG_STDERR 1

#define QB_LOG_BLACKBOX 2

#define QB_LOG_STDOUT 3

#define QB_LOG_TARGET_MAX 32

Typedefs

typedef const char *(* qb_log_tags_stringify_fn )(uint32_t tags)

typedef void(* qb_log_filter_fn )(struct qb_log_callsite *cs)

typedef void(* qb_log_logger_fn )(int32_t t, struct qb_log_callsite *cs, time_t timestamp, const char *msg)

typedef void(* qb_log_vlogger_fn )(int32_t t, struct qb_log_callsite *cs, time_t timestamp, va_list ap)

typedef void(* qb_log_close_fn )(int32_t t)

typedef void(* qb_log_reload_fn )(int32_t t)

Enumerations

enum qb_log_target_state { QB_LOG_STATE_UNUSED = 1, QB_LOG_STATE_DISABLED = 2, QB_LOG_STATE_ENABLED = 3 }

enum qb_log_conf { QB_LOG_CONF_ENABLED, QB_LOG_CONF_FACILITY, QB_LOG_CONF_DEBUG, QB_LOG_CONF_SIZE, QB_LOG_CONF_THREADED, QB_LOG_CONF_PRIORITY_BUMP, QB_LOG_CONF_STATE_GET }

enum qb_log_filter_type { QB_LOG_FILTER_FILE, QB_LOG_FILTER_FUNCTION, QB_LOG_FILTER_FORMAT }

enum qb_log_filter_conf { QB_LOG_FILTER_ADD, QB_LOG_FILTER_REMOVE, QB_LOG_FILTER_CLEAR_ALL, QB_LOG_TAG_SET, QB_LOG_TAG_CLEAR, QB_LOG_TAG_CLEAR_ALL }

Functions

struct qb_log_callsite __attribute__ ((aligned(8)))

void qb_log_real_ (struct qb_log_callsite *cs,...)

Internal function: use qb_log() or qb_logt() void qb_log_real_va_ (struct qb_log_callsite *cs, va_list ap)

void qb_log_from_external_source (const char *function, const char *filename, const char *format, uint8_t priority, uint32_t lineno, uint32_t tags,...)

This function is to import logs from other code (like libraries) that provide a callback with their logs. struct qb_log_callsite * qb_log_callsite_get (const char *function, const char *filename, const char *format, uint8_t priority, uint32_t lineno, uint32_t tags)

Get or create a callsite at the give position. void qb_log_from_external_source_va (const char *function, const char *filename, const char *format, uint8_t priority, uint32_t lineno, uint32_t tags, va_list ap)

void qb_log_init (const char *name, int32_t facility, uint8_t priority)

Init the logging system. void qb_log_fini (void)

Logging system finalization function. int32_t qb_log_callsites_register (struct qb_log_callsite *_start, struct qb_log_callsite *_stop)

If you are using dynamically loadable modules via dlopen() and you load them after qb_log_init() then after you load the module you will need to do the following to get the filters to work in that module. void qb_log_callsites_dump (void)

Dump the callsite info to stdout. int32_t qb_log_ctl (int32_t target, enum qb_log_conf conf_type, int32_t arg)

Main logging control function. int32_t qb_log_filter_ctl (int32_t value, enum qb_log_filter_conf c, enum qb_log_filter_type type, const char *text, uint8_t low_priority)

This allows you modify the 'tags' and 'targets' callsite fields at runtime. int32_t qb_log_filter_ctl2 (int32_t value, enum qb_log_filter_conf c, enum qb_log_filter_type type, const char *text, uint8_t high_priority, uint8_t low_priority)

This extends qb_log_filter_ctl() by been able to provide a high_priority. int32_t qb_log_filter_fn_set (qb_log_filter_fn fn)

Instead of using the qb_log_filter_ctl() functions you can apply the filters manually by defining a callback and setting the targets field using qb_bit_set() and qb_bit_clear() like the following below. void qb_log_tags_stringify_fn_set (qb_log_tags_stringify_fn fn)

Set the callback to map the 'tags' bit map to a string. void qb_log_format_set (int32_t t, const char *format)

Set the format specifiers. int32_t qb_log_file_open (const char *filename)

Open a log file. void qb_log_file_close (int32_t t)

Close a log file and release is resources. int32_t qb_log_thread_priority_set (int32_t policy, int32_t priority)

When using threaded logging set the pthread policy and priority. int32_t qb_log_thread_start (void)

Start the logging pthread. ssize_t qb_log_blackbox_write_to_file (const char *filename)

Write the blackbox to file. void qb_log_blackbox_print_from_file (const char *filename)

Read the blackbox for file and print it out. int32_t qb_log_custom_open (qb_log_logger_fn log_fn, qb_log_close_fn close_fn, qb_log_reload_fn reload_fn, void *user_data)

Open a custom log target. void qb_log_custom_close (int32_t t)

Close a custom log target and release is resources. void * qb_log_target_user_data_get (int32_t t)

Retrieve the user data set by either qb_log_custom_open or qb_log_target_user_data_set. int32_t qb_log_target_user_data_set (int32_t t, void *user_data)

Associate user data with this log target. void qb_log_target_format (int32_t target, struct qb_log_callsite *cs, time_t timestamp, const char *formatted_message, char *output_buffer)

format the callsite and timestamp info according to the format set using qb_log_format_set() It is intended to be used from your custom logger function. int32_t qb_log_facility2int (const char *fname)

Convert string 'auth' to equivalent number 'LOG_AUTH' etc. const char * qb_log_facility2str (int32_t fnum)

Convert number 'LOG_AUTH' to equivalent string 'auth' etc.

Variables

const char * function

const char * filename

const char * format

uint8_t priority

uint32_t lineno

uint32_t targets

uint32_t tags

struct qb_log_callsite __start___verbose []

struct qb_log_callsite __stop___verbose []

enum qb_log_target_state __attribute__

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);

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

#define \fBLOG_TRACE\fP (LOG_DEBUG + 1)

#define \fBqb_enter\fP() \fBqb_log\fP(\fBLOG_TRACE\fP, 'ENTERING %s()', __func__)

#define \fBqb_leave\fP() \fBqb_log\fP(\fBLOG_TRACE\fP, 'LEAVING %s()', __func__)

#define \fBqb_log\fP(\fBpriority\fP, fmt, args...) \fBqb_logt\fP(\fBpriority\fP, 0, fmt, ##args)

This is the main function to generate a log message. Parameters:

priority this takes syslog priorities.

fmt usual printf style format specifiers

args usual printf style args

#define \fBQB_LOG_BLACKBOX\fP 2

#define \fBQB_LOG_INIT_DATA\fP(name) \fBValue:\fP

void name(void);                                                        void name(void) { if (__start___verbose != __stop___verbose) {assert(1);} }      void __attribute__ ((constructor)) name(void);

#define \fBQB_LOG_MAX_LEN\fP 512

#define \fBQB_LOG_STDERR\fP 1

#define \fBQB_LOG_STDOUT\fP 3

#define \fBQB_LOG_STRERROR_MAX_LEN\fP 128

#define \fBQB_LOG_SYSLOG\fP 0

#define \fBQB_LOG_TAG_LIBQB_MSG\fP (1 << \fBQB_LOG_TAG_LIBQB_MSG_BIT\fP)

#define \fBQB_LOG_TAG_LIBQB_MSG_BIT\fP 31

#define \fBQB_LOG_TARGET_MAX\fP 32

#define \fBqb_logt\fP(\fBpriority\fP, \fBtags\fP, fmt, args...) \fBValue:\fP

do {                              static struct qb_log_callsite descriptor                                 __attribute__((section('__verbose'), aligned(8))) =                      { __func__, __FILE__, fmt, priority, __LINE__, 0, tags };                qb_log_real_(&descriptor, ##args);                                   } while(0)

This is the function to generate a log message if you want to manually add tags. Parameters:

priority this takes syslog priorities.

tags this is a uint32_t that you can use with qb_log_tags_stringify_fn_set() to 'tag' a log message with a feature or sub-system then you can use '%g' in the format specifer to print it out.

fmt usual printf style format specifiers

args usual printf style args

#define \fBqb_perror\fP(\fBpriority\fP, fmt, args...) \fBValue:\fP

do {                                       char _perr_buf_[QB_LOG_STRERROR_MAX_LEN];                                const char *_perr_str_ = qb_strerror_r(errno, _perr_buf_, sizeof(_perr_buf_));           qb_logt(priority, 0, fmt ': %s (%d)', ##args, _perr_str_, errno);                    } while(0)

This is similar to perror except it goes into the logging system. Parameters:

priority this takes syslog priorities.

fmt usual printf style format specifiers

args usual printf style args

typedef void(* \fBqb_log_close_fn\fP)(int32_t t)

typedef void(* \fBqb_log_filter_fn\fP)(struct \fBqb_log_callsite\fP *cs)

typedef void(* \fBqb_log_logger_fn\fP)(int32_t t, struct \fBqb_log_callsite\fP *cs, time_t timestamp, const char *msg)

typedef void(* \fBqb_log_reload_fn\fP)(int32_t t)

typedef const char*(* \fBqb_log_tags_stringify_fn\fP)(uint32_t \fBtags\fP)

typedef void(* \fBqb_log_vlogger_fn\fP)(int32_t t, struct \fBqb_log_callsite\fP *cs, time_t timestamp, va_list ap)

enum \fBqb_log_conf\fP

Enumerator:

QB_LOG_CONF_ENABLED

QB_LOG_CONF_FACILITY

QB_LOG_CONF_DEBUG

QB_LOG_CONF_SIZE

QB_LOG_CONF_THREADED

QB_LOG_CONF_PRIORITY_BUMP

QB_LOG_CONF_STATE_GET

enum \fBqb_log_filter_conf\fP

Enumerator:

QB_LOG_FILTER_ADD

QB_LOG_FILTER_REMOVE

QB_LOG_FILTER_CLEAR_ALL

QB_LOG_TAG_SET

QB_LOG_TAG_CLEAR

QB_LOG_TAG_CLEAR_ALL

enum \fBqb_log_filter_type\fP

Enumerator:

QB_LOG_FILTER_FILE

QB_LOG_FILTER_FUNCTION

QB_LOG_FILTER_FORMAT

enum \fBqb_log_target_state\fP

Enumerator:

QB_LOG_STATE_UNUSED

QB_LOG_STATE_DISABLED

QB_LOG_STATE_ENABLED

struct \fBqb_log_callsite\fP \fB__attribute__\fP ((aligned(8)))

void \fBqb_log_blackbox_print_from_file\fP (const char *filename)

Read the blackbox for file and print it out.

ssize_t \fBqb_log_blackbox_write_to_file\fP (const char *filename)

Write the blackbox to file.

struct \fBqb_log_callsite\fP* \fBqb_log_callsite_get\fP (const char *function, const char *filename, const char *format, uint8_tpriority, uint32_tlineno, uint32_ttags)\fC [read]\fP

Get or create a callsite at the give position. The result can then be passed into qb_log_real_()

Parameters:

function originating function name

filename originating filename

format format string

priority this takes syslog priorities.

lineno file line number

tags the tag

void \fBqb_log_callsites_dump\fP (void)

Dump the callsite info to stdout.

int32_t \fBqb_log_callsites_register\fP (struct \fBqb_log_callsite\fP *_start, struct \fBqb_log_callsite\fP *_stop)

If you are using dynamically loadable modules via dlopen() and you load them after qb_log_init() then after you load the module you will need to do the following to get the filters to work in that module. .PP

  _start = dlsym (dl_handle, '__start___verbose');
        _stop = dlsym (dl_handle, '__stop___verbose');
        qb_log_callsites_register(_start, _stop);

int32_t \fBqb_log_ctl\fP (int32_ttarget, enum \fBqb_log_conf\fPconf_type, int32_targ)

Main logging control function. Parameters:

target QB_LOG_SYSLOG, QB_LOG_STDERR or result from qb_log_file_open()

conf_type what to configure

arg the new value

See also:

qb_log_conf

Return values:

-errno on error

0 on success

qb_log_target_state for QB_LOG_CONF_STATE_GET

void \fBqb_log_custom_close\fP (int32_tt)

Close a custom log target and release is resources.

int32_t \fBqb_log_custom_open\fP (\fBqb_log_logger_fn\fPlog_fn, \fBqb_log_close_fn\fPclose_fn, \fBqb_log_reload_fn\fPreload_fn, void *user_data)

Open a custom log target. Return values:

-errno on error

3 to 31 (to be passed into other qb_log_* functions)

int32_t \fBqb_log_facility2int\fP (const char *fname)

Convert string 'auth' to equivalent number 'LOG_AUTH' etc.

const char* \fBqb_log_facility2str\fP (int32_tfnum)

Convert number 'LOG_AUTH' to equivalent string 'auth' etc.

void \fBqb_log_file_close\fP (int32_tt)

Close a log file and release is resources.

int32_t \fBqb_log_file_open\fP (const char *filename)

Open a log file. Return values:

-errno on error

3 to 31 (to be passed into other qb_log_* functions)

int32_t \fBqb_log_filter_ctl\fP (int32_tvalue, enum \fBqb_log_filter_conf\fPc, enum \fBqb_log_filter_type\fPtype, const char *text, uint8_tlow_priority)

This allows you modify the 'tags' and 'targets' callsite fields at runtime.

int32_t \fBqb_log_filter_ctl2\fP (int32_tvalue, enum \fBqb_log_filter_conf\fPc, enum \fBqb_log_filter_type\fPtype, const char *text, uint8_thigh_priority, uint8_tlow_priority)

This extends qb_log_filter_ctl() by been able to provide a high_priority.

int32_t \fBqb_log_filter_fn_set\fP (\fBqb_log_filter_fn\fPfn)

Instead of using the qb_log_filter_ctl() functions you can apply the filters manually by defining a callback and setting the targets field using qb_bit_set() and qb_bit_clear() like the following below. .PP

 static void
 m_filter(struct qb_log_callsite *cs)
 {
        if ((cs->priority >= LOG_ALERT &&
             cs->priority <= LOG_DEBUG) &&
             strcmp(cs->filename, 'my_c_file.c') == 0) {
                qb_bit_set(cs->targets, QB_LOG_SYSLOG);
        } else {
                qb_bit_clear(cs->targets, QB_LOG_SYSLOG);
        }
 }

void \fBqb_log_fini\fP (void)

Logging system finalization function. It releases any shared memory. Stops the logging thread if running. Flushes the last message to their destinations.

void \fBqb_log_format_set\fP (int32_tt, const char *format)

Set the format specifiers. n FUNCTION NAME f FILENAME l FILELINE p PRIORITY t TIMESTAMP b BUFFER g TAGS N name (passed into qb_log_init) P PID H hostname

any number between % and character specify field length to pad or chop

void \fBqb_log_from_external_source\fP (const char *function, const char *filename, const char *format, uint8_tpriority, uint32_tlineno, uint32_ttags, ...)

This function is to import logs from other code (like libraries) that provide a callback with their logs. Note:

the performance of this will not impress you, as the filtering is done on each log message, not before hand. So try doing basic pre-filtering.

Parameters:

function originating function name

filename originating filename

format format string

priority this takes syslog priorities.

lineno file line number

tags this is a uint32_t that you can use with qb_log_tags_stringify_fn_set() to 'tag' a log message with a feature or sub-system then you can use '%g' in the format specifer to print it out.

void \fBqb_log_from_external_source_va\fP (const char *function, const char *filename, const char *format, uint8_tpriority, uint32_tlineno, uint32_ttags, va_listap)

void \fBqb_log_init\fP (const char *name, int32_tfacility, uint8_tpriority)

Init the logging system. Parameters:

name will be passed into openlog()

facility default for all new targets.

priority a basic filter with this priority will be added.

void \fBqb_log_real_\fP (struct \fBqb_log_callsite\fP *cs, ...)

Internal function: use qb_log() or qb_logt()

void \fBqb_log_real_va_\fP (struct \fBqb_log_callsite\fP *cs, va_listap)

void \fBqb_log_tags_stringify_fn_set\fP (\fBqb_log_tags_stringify_fn\fPfn)

Set the callback to map the 'tags' bit map to a string.

void \fBqb_log_target_format\fP (int32_ttarget, struct \fBqb_log_callsite\fP *cs, time_ttimestamp, const char *formatted_message, char *output_buffer)

format the callsite and timestamp info according to the format set using qb_log_format_set() It is intended to be used from your custom logger function.

void* \fBqb_log_target_user_data_get\fP (int32_tt)

Retrieve the user data set by either qb_log_custom_open or qb_log_target_user_data_set.

int32_t \fBqb_log_target_user_data_set\fP (int32_tt, void *user_data)

Associate user data with this log target. Note:

only use this with custom targets

int32_t \fBqb_log_thread_priority_set\fP (int32_tpolicy, int32_tpriority)

When using threaded logging set the pthread policy and priority. Return values:

-errno on error

0 success

int32_t \fBqb_log_thread_start\fP (void)

Start the logging pthread.

enum \fBqb_log_target_state\fP \fB__attribute__\fP

struct \fBqb_log_callsite\fP \fB__start___verbose\fP[]

struct \fBqb_log_callsite\fP \fB__stop___verbose\fP[]

const char* \fBfilename\fP

const char* \fBformat\fP

const char* \fBfunction\fP

uint32_t \fBlineno\fP

uint8_t \fBpriority\fP

uint32_t \fBtags\fP

uint32_t \fBtargets\fP

Generated automatically by Doxygen for libqb from the source code.