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.

See

logconf_get_field() for fetching config file field’s value

Parameters

  • conf – pointer to the struct logconf structure to be initialized

  • id – the struct logconf module id

  • fp – the configuration file pointer that will fill struct logconf fields

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.

See

logconf_setup() for initializing conf with a config file

Parameters

  • conf – the struct logconf module

  • json_field – the field to fetch the value of

Returns

a read-only sized buffer containing the field’s value

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

previous

Cee-Utils Reference

next

Null-Terminated List Reference