log.c File Reference

A general-purpose logging system. More...

#include "log.h"
#include "list.h"
#include "macro.h"
#include "mpkutils.h"
#include "process.h"
#include "strutils.h"
#include "timing.h"
#include "uthash.h"
#include <stdarg.h>

Data Structures
struct	checkpoint_entry_t
	an entry for the "checkpoint" hash map, keeping track of pass counts More...

Typedefs
typedef struct checkpoint_entry_t	checkpoint_entry_t
	an entry for the "checkpoint" hash map, keeping track of pass counts

Functions
void	log_register_backend (backend_callback_t *callback, backend_command_t *notify, void *userptr)
	Add a callback function to the list of logging backends. More...
void	log_unregister_backend (backend_callback_t *callback, void *userptr)
	Remove a callback function from the list of logging backends.
void	log_shutdown (void)
	Notify all the logging backends of impending shutdown. More...
void	log_reset (bool with_checkpoints)
	Reset (internal) log system variables. More...
void	attach_log_level (msgpack_object *attachment, LOG_LEVEL level, const char *origin, const char *msg, int len)
	Create a simple log message with an attachment. More...
void	attach_log_level_ap (msgpack_object *attachment, LOG_LEVEL level, const char *origin, const char *fmt, va_list ap)
	printf-style creation of a log message with attachment, using format string and a vararg list. More...
void	attach_log_level_fmt (msgpack_object *attachment, LOG_LEVEL level, const char *origin, const char *fmt,...)
	vararg wrapper for attach_log_level_ap()
void	log_scratch (const char *origin, const char *key, const char *value)
	"scratchpad" message logging a key-value pair
const char *	log_level_string (LOG_LEVEL level)
	return string representation of a LOG_LEVEL

Detailed Description

A general-purpose logging system.

The idea is to have a standardized way of creating log messages; something that is mostly self-explaining and easy to call from the user's perspective, preferably boiling down to some simple printf-style log(fmt, ...) in most cases.

The log messages will then get 'serialized', transforming them into an internal format (using MessagePack), and after that will be "sent" by calling one or more logging "backends" on the result. Depending on the backends used / active, this allows very flexible message handling - leaving the actual workload to the various backend implementations for specific logging targets. Keeping the list of backends 'dynamic' also allows to add / remove logging backends at any time.

// have your main module set up logging, e.g. attach a specific backend
#include "logstdio.h"
log_stdio("stdout");

// then (from the same or other module/s) use logging functions like this
#include "log.h"
error("foo = %s", "bar");

Function Documentation

void attach_log_level	(	msgpack_object *	attachment,
		LOG_LEVEL	level,
		const char *	origin,
		const char *	msg,
		int	len
	)

Create a simple log message with an attachment.

Parameters

attachment	pointer to an arbitrary MessagePack object to 'attach'. The object gets serialized and transferred along with the log message. optional, may be NULL
level	the LOG_LEVEL to use for the message
origin	a string indicating the message source (e.g. module name). optional, may be NULL
msg	the actual message string
len	length of the message string (excluding terminating NUL). You can pass len < 0, to use strlen(msg) instead.

void attach_log_level_ap	(	msgpack_object *	attachment,
		LOG_LEVEL	level,
		const char *	origin,
		const char *	fmt,
		va_list	ap
	)

printf-style creation of a log message with attachment, using format string and a vararg list.

Parameters

attachment	pointer to an arbitrary MessagePack object to 'attach'. The object gets serialized and transferred along with the log message. optional, may be NULL
level	the LOG_LEVEL to use for the message
origin	a string indicating the message source (e.g. module name). optional, may be NULL
fmt	printf-style format string
ap	variable argument list, see <stdarg.h>

void log_register_backend	(	backend_callback_t *	callback,
		backend_command_t *	notify,
		void *	userptr
	)

Add a callback function to the list of logging backends.

Parameters

callback	function for actual logging
notify	(internal) notification function. optional, may be NULL
userptr	arbitrary "user" data (pointer) that will be passed to the callbacks. optional, may be NULL

void log_reset

(

bool

with_checkpoints

)

Reset (internal) log system variables.

This restores a zero indentation level, and optionally clears the checkpoint pass counters (if with_checkpoints is set).

void log_shutdown

(

void

)

Notify all the logging backends of impending shutdown.

This is to give backends the opportunity to flush any outstanding messages, and to free up resources before the log system terminates.