Modular Logging Reference#

An add-on to the popular log.c logging library that adds modularity over the existing functionalities. All functions from log.c are included and can be expected to behave the same.

The following outlines the modular logging functionalities.

Datatypes#

struct logconf#

A stackful and modularized wrapper over the popular ‘log.c’ facilities.

Provides a way to split logging into individual modules, that can be configured separately from one another, or have their resources shared via branching.

Public Members

char id[LOGCONF_ID_LEN]#: logging module id

log_Logger L#: log.c main structure

unsigned pid#: the id of the process where this module was created

_Bool is_branch#: if true then logconf_cleanup() won’t cleanup shared resources

struct sized_buffer file#: config file conents

char fname[LOGCONF_PATH_MAX]#: name of logging output file

FILE *f#: pointer to logging output file

struct logconf.[anonymous] *logger#

struct logconf.[anonymous] *http#

struct ja_str **disable_modules#: list of ‘id’ that should be ignored

Constants#

LOGCONF_ID_LEN 64 + 1#: Maximum length for module id

LOGCONF_PATH_MAX 4096#: Maximum length for the output file path

Configure logging via a JSON file#

void logconf_setup(struct logconf *conf, const char id[], FILE *fp)#

Initialize a struct logconf module from a config file.

Get file field#

struct sized_buffer logconf_get_field(struct logconf *conf, char *json_field)#

Get the value from a given JSON field of the config file.

Branch a logging module#

void logconf_branch(struct logconf *branch, struct logconf *orig, const char id[])#

Branch and link a struct logconf module to a existing one.

Initialize a branch logging module thats expected to share common resources with its parent module orig. The common resources include: config file directives, logging output and disabled modules list.

Parameters:

branch – pointer to the struct logconf structure to be initialized as orig branch
orig – pointer to the struct logconf structure that holds the parent module
id – the branch module id

Cleanup#

void logconf_cleanup(struct logconf *conf)#

Cleanup a struct logconf module.

Parameters:

conf – the struct logconf structure to be cleaned

Logging#

logconf_trace(conf, ...) logconf_log(conf, LOG_TRACE, __FILE__, __LINE__, __VA_ARGS__)#

Log level trace.

Parameters:

conf – the struct logconf module
... – the printf-like format string and successive arguments

logconf_debug(conf, ...) logconf_log(conf, LOG_DEBUG, __FILE__, __LINE__, __VA_ARGS__)#

Log level debug.

Parameters:

conf – the struct logconf module
... – the printf-like format string and successive arguments

logconf_info(conf, ...) logconf_log(conf, LOG_INFO, __FILE__, __LINE__, __VA_ARGS__)#

Log level info.

Parameters:

conf – the struct logconf module
... – the printf-like format string and successive arguments

logconf_warn(conf, ...) logconf_log(conf, LOG_WARN, __FILE__, __LINE__, __VA_ARGS__)#

Log level warn.

Parameters:

conf – the struct logconf module
... – the printf-like format string and successive arguments

logconf_error(conf, ...) logconf_log(conf, LOG_ERROR, __FILE__, __LINE__, __VA_ARGS__)#

Log level error.

Parameters:

conf – the struct logconf module
... – the printf-like format string and successive arguments

logconf_fatal(conf, ...) logconf_log(conf, LOG_FATAL, __FILE__, __LINE__, __VA_ARGS__)#

Log level fatal.

Parameters:

conf – the struct logconf module
... – the printf-like format string and successive arguments

logconf_log(conf, level, file, line, ...) __logconf_log(conf, level, file, line, __VA_ARGS__, "")#

Run-time configurable log level.

Parameters:

conf – the struct logconf module
level – the log level enumerator from log.c
file – the origin file name
line – the origin file line
... – the printf-like format string and successive arguments

HTTP#

void logconf_http(struct logconf *conf, struct loginfo *info, char url[], struct sized_buffer header, struct sized_buffer body, char label_fmt[], ...)#

Log HTTP transfers.

Parameters:

conf – the struct logconf module
info – retrieve information on this logging
url – the transfer URL
header – the transfer header
body – the transfer body
label_fmt – a printf() like formatting string to provide additional logging description, such as the transfer’s HTTP method, or HTTP response code.
... – subsequent arguments that are converted for output

struct loginfo#

Store logging information from log_http()

Public Members

size_t counter#: log count

uint64_t tstamp_ms#: log timestamp

Configuring logging manually#

void logconf_set_quiet(struct logconf *conf, bool enable)#

Toggle quiet mode.

Quiet-mode can be enabled by settings enable to true. While this mode is enabled the library will not output anything to stderr, but will continue to write to files and callbacks if any are set.

Parameters:

conf – the struct logconf module
enable – true enables quiet-mode

void logconf_set_level(struct logconf *conf, int level)#

Set the current logging level.

All logs below the given level will not be written to stderr. By default the level is LOG_TRACE, such that nothing is ignored.

Parameters:

conf – the struct logconf module
level – logging level

int logconf_add_fp(struct logconf *conf, FILE *fp, int level)#

File where the log will be written.

One or more file pointers where the log will be written can be provided to the library. Any messages below the given level are ignored. If the library failed to add a file pointer a value less-than-zero is returned.

Parameters:

conf – the struct logconf module
fp – the write-to file pointer
level – logging level condition for writing to fp

void logconf_add_callback(struct logconf *conf, log_LogFn fn, void *udata, int level)#

Callback functions called when logging data.

One or more callback functions which are called with the log data can be provided to the library. A callback function is passed a log_Event structure containing the line number, filename, fmt string, va printf va_list, level and the given udata.

Parameters:

conf – the struct logconf module
fn – the callback function
udata – user arbitrary data
level – logging level to trigger callback

void logconf_set_lock(struct logconf *conf, log_LockFn fn, void *udata)#

If the log will be written to from multiple threads a lock function can be set.

The function is passed the boolean true if the lock should be acquired or false if the lock should be released and the given udata value.

Parameters:

conf – the struct logconf module
fn – lock callback
udata – user arbitrary data