Logging and tracing facility. More...

Macros
#define	QOF_MOD_ENGINE "qof.engine"

#define	LOG_LEVEL_LIST(_)

#define	PRETTY_FUNC_NAME qof_log_prettify(G_STRFUNC)

#define	FATAL(format, args...)

#define	PERR(format, args...)

#define	PWARN(format, args...)

#define	PINFO(format, args...)

#define	DEBUG(format, args...)

#define	ENTER(format, args...)

#define	LEAVE(format, args...)

#define	gnc_leave_return_val_if_fail(test, val)

#define	gnc_leave_return_if_fail(test)

Enumerations
enum	QofLogLevel { QOF_LOG_FATAL = G_LOG_LEVEL_ERROR, QOF_LOG_ERROR = G_LOG_LEVEL_CRITICAL, QOF_LOG_WARNING = G_LOG_LEVEL_WARNING, QOF_LOG_MESSAGE = G_LOG_LEVEL_MESSAGE, QOF_LOG_INFO = G_LOG_LEVEL_INFO, QOF_LOG_DEBUG = G_LOG_LEVEL_DEBUG }

Functions
const char *	qof_log_level_to_string (QofLogLevel lvl)

QofLogLevel	qof_log_level_from_string (const char *str)

void	qof_log_indent (void)

void	qof_log_dedent (void)

void	qof_log_init (void)

void	qof_log_set_level (QofLogModule module, QofLogLevel level)

void	qof_log_set_file (FILE *outfile)

void	qof_log_init_filename (const gchar *logfilename)

void	qof_log_init_filename_special (const char *log_to_filename)

void	qof_log_parse_log_config (const char *filename)

void	qof_log_shutdown (void)

const gchar *	qof_log_prettify (const gchar *name)

gboolean	qof_log_check (QofLogModule log_module, QofLogLevel log_level)

void	qof_log_set_default (QofLogLevel log_level)

Detailed Description

Logging and tracing facility.

See Also: "Logging overhaul" announcement http://lists.gnucash.org/pipermail/gnucash-devel/2007-February/019836.html

qof_log_init(void) installs a handler that interprets the "log_domain" as a "."-separated path. Log level thresholds can be set for each level in the tree. When a message is logged, the longest level match is found, and used as the threshold.

For instance, we can set the levels as such:

  "qof"                        = WARN
  "gnc"                        = WARN
  "gnc.ui"                     = INFO
  "gnc.ui.plugin-page.sx-list" = DEBUG

When code in the log_module of "gnc.import" attempts to log at DEBUG (let's say), the handler will attempt to match the log domain to successively-longer paths: first "", then "gnc", then "gnc.import". Given the settings above, the path "gnc" will match – at a level of "WARN" – and the DEBUG-level log will be rejected. When code in the log domain of "gnc.ui.plugin-page.sx-list" logs at DEBUG, however, it will match at DEBUG, and be allowed.

The current log format is as above:

    * [timestamp] [level] <[log-domain]> [message]

The timestamp and level are constant width (level is 5 characters). The log domain is re-iterated, which gives some context, but could become annoying if they get long.

Trailing newlines (e.g. PINFO("...\n", ...)) are removed; the logger will newline separate output.

Best Practices

Code should:

Define both static QofLogModule log_module and #define G_LOG_DOMAIN to the same value.
Define a logical, specific path as the log domain; "gnc.gui.plugin-pages.sx-list" or "gnc.register.gnome.cell.quickfill" are good examples.
Use glib-provided g_debug(...), g_message(...), g_warning(...), g_critical(...) and g_error(...) functions in preference to the historical qof/gnc PINFO, PERR (&c.) macros

See Also: qof_log_parse_log_config(const char*)

Macro Definition Documentation

#define DEBUG	(	format,
		args...
	)

Value:

do { \
    g_log (log_module, G_LOG_LEVEL_DEBUG, \
      "[%s] " format, PRETTY_FUNC_NAME , ## args); \
} while (0)

Print a debugging message

Definition at line 255 of file qoflog.h.

#define ENTER	(	format,
		args...
	)

Value:

do { \
    if (qof_log_check(log_module, (QofLogLevel)G_LOG_LEVEL_DEBUG)) { \
      g_log (log_module, G_LOG_LEVEL_DEBUG, \
        "[enter %s:%s()] " format, __FILE__, \
        PRETTY_FUNC_NAME , ## args); \
      qof_log_indent(); \
    } \
} while (0)

Print a function entry debugging message

Definition at line 261 of file qoflog.h.

#define FATAL	(	format,
		args...
	)

Value:

do { \
    g_log (log_module, G_LOG_LEVEL_ERROR, \
      "[%s()] " format, PRETTY_FUNC_NAME , ## args); \
} while (0)

Log a fatal error

Definition at line 231 of file qoflog.h.

#define gnc_leave_return_if_fail ( test )

Value:

do { \
  if (! (test)) { LEAVE(""); } \
  g_return_if_fail(test); \
} while (0);

Replacement for g_return_if_fail, but calls LEAVE if the test fails.

Definition at line 289 of file qoflog.h.

#define gnc_leave_return_val_if_fail	(	test,
		val
	)

Value:

do { \
  if (! (test)) { LEAVE(""); } \
  g_return_val_if_fail(test, val); \
} while (0);

Replacement for g_return_val_if_fail, but calls LEAVE if the test fails.

Definition at line 283 of file qoflog.h.

#define LEAVE	(	format,
		args...
	)

Value:

do { \
    if (qof_log_check(log_module, (QofLogLevel)G_LOG_LEVEL_DEBUG)) { \
      qof_log_dedent(); \
      g_log (log_module, G_LOG_LEVEL_DEBUG, \
        "[leave %s()] " format, \
        PRETTY_FUNC_NAME , ## args); \
    } \
} while (0)

Print a function exit debugging message.

Definition at line 271 of file qoflog.h.

#define LOG_LEVEL_LIST ( _ )

Value:

_(QOF_LOG_FATAL,   = G_LOG_LEVEL_ERROR)   \
  _(QOF_LOG_ERROR,   = G_LOG_LEVEL_CRITICAL)   \
  _(QOF_LOG_WARNING, = G_LOG_LEVEL_WARNING) \
  _(QOF_LOG_MESSAGE, = G_LOG_LEVEL_MESSAGE) \
  _(QOF_LOG_INFO,    = G_LOG_LEVEL_INFO)    \
  _(QOF_LOG_DEBUG,   = G_LOG_LEVEL_DEBUG)

Definition at line 99 of file qoflog.h.

#define PERR	(	format,
		args...
	)

Value:

do { \
    g_log (log_module, G_LOG_LEVEL_CRITICAL, \
      "[%s()] " format, PRETTY_FUNC_NAME , ## args); \
} while (0)

Log a serious error

Definition at line 237 of file qoflog.h.

#define PINFO	(	format,
		args...
	)

Value:

do { \
    g_log (log_module, G_LOG_LEVEL_INFO, \
      "[%s] " format, PRETTY_FUNC_NAME , ## args); \
} while (0)

Print an informational note

Definition at line 249 of file qoflog.h.

#define PWARN	(	format,
		args...
	)

Value:

do { \
    g_log (log_module, G_LOG_LEVEL_WARNING, \
      "[%s()] " format, PRETTY_FUNC_NAME , ## args); \
} while (0)

Log a warning

Definition at line 243 of file qoflog.h.

Function Documentation

gboolean qof_log_check	(	QofLogModule	log_module,
		QofLogLevel	log_level
	)

Check to see if the given log_module is configured to log at the given log_level. This implements the "log.path.hierarchy" logic.

void qof_log_dedent ( void )

De-dent one level, capped at 0; see LEAVE macro.

void qof_log_indent ( void )

Indents one level; see ENTER macro.

void qof_log_init ( void )

Initialize the error logging subsystem. Defaults to a level-threshold of "warning", and logging to stderr.

void qof_log_init_filename ( const gchar * logfilename )

Specify a filename for log output.

void qof_log_init_filename_special ( const char * log_to_filename )

If log_to_filename is "stderr" or "stdout" (exactly, case-insensitive), then those special files are used; otherwise, the literal filename as given, as qof_log_init_filename(gchar*)

void qof_log_parse_log_config ( const char * filename )

Parse a log-configuration file. A GKeyFile-format file of the schema:

   [levels]
   # log.ger.path=level
   gnc.engine.sx=debug
   gnc.gui.sx=debug
   gnc.import-export.qif.parse=debug
   [output]
   # to=["stderr"|"stdout"|filename]
   to=stderr

const gchar* qof_log_prettify ( const gchar * name )

Cleans up subroutine names. AIX/xlC has the habit of printing signatures not names; clean this up. On other operating systems, truncate name to QOF_LOG_MAX_CHARS chars.

void qof_log_set_default ( QofLogLevel log_level )

Set the default level for QOF-related log paths.

void qof_log_set_file ( FILE * outfile )

Specify an alternate log output, to pipe or file.

void qof_log_set_level	(	QofLogModule	module,
		QofLogLevel	level
	)

Set the logging level of the given log_module.

void qof_log_shutdown ( void )

Be nice, close the logfile if possible.

Macros

Enumerations

Functions

Detailed Description

Best Practices

Macro Definition Documentation

Function Documentation