Trace: Error Reporting and Debugging
[Query Object Framework]


Files

file  gnc-trace.h
 QOF error logging and tracing facility (to be renamed qoflog.h in libqof2.).

Defines

#define QOF_MOD_ENGINE   "qof-engine"
#define LOG_LEVEL_LIST(_)
#define GNC_TRACE_INDENT_WIDTH   4
#define FUNK   gnc_log_prettify(__FUNCTION__)
#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 TRACE(format, args...)
#define DEBUGCMD(x)
#define START_CLOCK(clockno, format, args...)
#define REPORT_CLOCK(clockno, format, args...)
#define REPORT_CLOCK_TOTAL(clockno, format, args...)

Typedefs

typedef void(* QofLogCB )(QofLogModule log_module, gncLogLevel *log_level, gpointer user_data)

Functions

void gnc_log_init (void)
void gnc_set_log_level (QofLogModule module, gncLogLevel level)
void gnc_set_log_level_global (gncLogLevel level)
void gnc_set_logfile (FILE *outfile)
void qof_log_init_filename (const gchar *logfilename)
void qof_log_shutdown (void)
const char * gnc_log_prettify (const char *name)
gboolean gnc_should_log (QofLogModule log_module, gncLogLevel log_level)
void qof_log_set_default (gncLogLevel log_level)
void qof_log_module_foreach (QofLogCB cb, gpointer data)
gint qof_log_module_count (void)
void gnc_start_clock (int clockno, QofLogModule log_module, gncLogLevel log_level, const char *function_name, const char *format,...)
void gnc_report_clock (int clockno, QofLogModule log_module, gncLogLevel log_level, const char *function_name, const char *format,...)
void gnc_report_clock_total (int clockno, QofLogModule log_module, gncLogLevel log_level, const char *function_name, const char *format,...)

Define Documentation

#define DEBUG (  format,
args...   ) 
 

Value:

do {                 \
  if (gnc_should_log (log_module, GNC_LOG_DEBUG)) {    \
    g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,        \
      "Debug: %s(): " format,                      \
      FUNK , ## args);                             \
  }                                                \
} while (0)
Print a debugging message

Definition at line 186 of file gnc-trace.h.

#define DEBUGCMD (  x   ) 
 

Value:

do {                            \
  if (gnc_should_log (log_module, GNC_LOG_DEBUG)) { \
                (x);                                        \
        }                                               \
} while (0)

Definition at line 224 of file gnc-trace.h.

#define ENTER (  format,
args...   ) 
 

Value:

do {                 \
  extern gint gnc_trace_num_spaces;                \
  if (gnc_should_log (log_module, GNC_LOG_DEBUG)) {    \
    g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,        \
      "Enter in %s: %s()" format, __FILE__,        \
      FUNK , ## args);                             \
    gnc_trace_num_spaces += GNC_TRACE_INDENT_WIDTH; \
  }                                                \
} while (0)
Print a function entry debugging message

Definition at line 195 of file gnc-trace.h.

#define FATAL (  format,
args...   ) 
 

Value:

do {                  \
    g_log (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR,          \
      "Fatal Error: %s(): " format, FUNK , ## args); \
} while (0)
Log an fatal error

Definition at line 155 of file gnc-trace.h.

#define GNC_TRACE_INDENT_WIDTH   4
 

Convert the log_string to a gncLogLevel

Only for use as a partner to gncLogLevelasString

Definition at line 68 of file gnc-trace.h.

#define LEAVE (  format,
args...   ) 
 

Value:

do {                 \
  extern gint gnc_trace_num_spaces;                \
  if (gnc_should_log (log_module, GNC_LOG_DEBUG)) {    \
    gnc_trace_num_spaces -= GNC_TRACE_INDENT_WIDTH; \
    g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,        \
      "Leave: %s()" format,                        \
      FUNK , ## args);                             \
  }                                                \
} while (0)
Print a function exit debugging message

Definition at line 206 of file gnc-trace.h.

#define LOG_LEVEL_LIST (  _   ) 
 

Value:

_(GNC_LOG_FATAL, = 0)   \
  _(GNC_LOG_ERROR, = 1)   \
  _(GNC_LOG_WARNING, = 2) \
  _(GNC_LOG_INFO, = 3)    \
  _(GNC_LOG_DEBUG, = 4)   \
  _(GNC_LOG_DETAIL, = 5)  \
  _(GNC_LOG_TRACE, = 6)

Definition at line 43 of file gnc-trace.h.

#define PERR (  format,
args...   ) 
 

Value:

do {                   \
  if (gnc_should_log (log_module, GNC_LOG_ERROR)) {    \
    g_log (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL,     \
      "Error: %s(): " format, FUNK , ## args);     \
  }                                                \
} while (0)
Log a serious error

Definition at line 161 of file gnc-trace.h.

#define PINFO (  format,
args...   ) 
 

Value:

do {                 \
  if (gnc_should_log (log_module, GNC_LOG_INFO)) {     \
    g_log (G_LOG_DOMAIN, G_LOG_LEVEL_INFO,         \
      "Info: %s(): " format,                       \
      FUNK , ## args);                             \
  }                                                \
} while (0)
Print an informational note

Definition at line 177 of file gnc-trace.h.

#define PWARN (  format,
args...   ) 
 

Value:

do {                    \
  if (gnc_should_log (log_module, GNC_LOG_WARNING)) {  \
    g_log (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING,      \
      "Warning: %s(): " format, FUNK , ## args);   \
  }                                                \
} while (0)
Log a warning

Definition at line 169 of file gnc-trace.h.

#define REPORT_CLOCK (  clockno,
format,
args...   ) 
 

Value:

do {       \
  if (gnc_should_log (log_module, GNC_LOG_INFO))                \
    gnc_report_clock (clockno, log_module, GNC_LOG_INFO, \
             __FUNCTION__, format , ## args);               \
} while (0)
report elapsed time since last report on a particular timer

Definition at line 258 of file gnc-trace.h.

#define REPORT_CLOCK_TOTAL (  clockno,
format,
args...   ) 
 

Value:

do {       \
  if (gnc_should_log (log_module, GNC_LOG_INFO))                \
    gnc_report_clock_total (clockno, log_module, GNC_LOG_INFO, \
             __FUNCTION__, format , ## args);               \
} while (0)
report total elapsed time since timer started

Definition at line 265 of file gnc-trace.h.

#define START_CLOCK (  clockno,
format,
args...   ) 
 

Value:

do {        \
  if (gnc_should_log (log_module, GNC_LOG_INFO))                \
    gnc_start_clock (clockno, log_module, GNC_LOG_INFO,  \
             __FUNCTION__, format , ## args);               \
} while (0)
start a particular timer

Definition at line 251 of file gnc-trace.h.

#define TRACE (  format,
args...   ) 
 

Value:

do {                 \
  if (gnc_should_log (log_module, GNC_LOG_TRACE)) {    \
    g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,        \
      "Trace: %s(): " format, FUNK , ## args);     \
  }                                                \
} while (0)
Print a function trace debugging message

Definition at line 217 of file gnc-trace.h.

Function Documentation

void gnc_log_init (  void   ) 
 

Initialize the error logging subsystem

Note:
Applications should call gnc_set_logfile to set the output, otherwise the default of /tmp/qof.trace will be used.
As an alternative, use qof_log_init_filename which sets the filename and initialises the logging subsystem in one operation.

Definition at line 72 of file gnc-trace.c.

00073 {
00074    if(!fout) /* allow gnc_set_logfile */
00075    {
00076            fout = fopen ("/tmp/qof.trace", "w");
00077    }
00078 
00079    if(!fout && (filename = (char *)g_malloc(MAX_TRACE_FILENAME))) {
00080       snprintf(filename, MAX_TRACE_FILENAME-1, "/tmp/qof.trace.%d", 
00081                getpid());
00082       fout = fopen (filename, "w");
00083       g_free(filename);
00084    }
00085 
00086    if(!fout)
00087    fout = stderr;
00088 
00089    g_log_set_handler (G_LOG_DOMAIN, G_LOG_LEVEL_MASK, fh_printer, fout);
00090 }

const char* gnc_log_prettify (  const char *  name  ) 
 

gnc_log_prettify() cleans up subroutine names. AIX/xlC has the habit of printing signatures not names; clean this up. On other operating systems, truncate name to 30 chars. Note this routine is not thread safe. Note we wouldn't need this routine if AIX did something more reasonable. Hope thread safety doesn't poke us in eye.

Definition at line 161 of file gnc-trace.c.

00162 {
00163   static char bf[128];
00164   char *p;
00165 
00166   if (!name)
00167     return "";
00168 
00169   strncpy (bf, name, MAX_CHARS-1); bf[MAX_CHARS-2] = 0;
00170   p = strchr (bf, '(');
00171 
00172   if (p)
00173   {
00174     *(p+1) = ')';
00175     *(p+2) = 0x0;
00176   }
00177   else
00178     strcpy (&bf[MAX_CHARS-4], "...()");
00179 
00180   return bf;
00181 }

void gnc_set_log_level (  QofLogModule  module,
gncLogLevel  level
) 
 

Set the logging level of the given log_module.

Definition at line 94 of file gnc-trace.c.

00095 {
00096         gchar* level_string;
00097 
00098         if(!log_module || level == 0) { return; }
00099         level_string = g_strdup(gncLogLevelasString(level));
00100         if(!log_table)
00101         {
00102                 log_table = g_hash_table_new(g_str_hash, g_str_equal);
00103         }
00104         g_hash_table_insert(log_table, (gpointer)log_module, level_string);
00105 }

void gnc_set_log_level_global (  gncLogLevel  level  ) 
 

Set the logging level for all known log_modules.

Note:
Unless a log_module has been registered using gnc_set_log_level, it will be unaffected by this change.

Definition at line 115 of file gnc-trace.c.

00116 {
00117         gchar* level_string;
00118 
00119         if(!log_table || level == 0) { return; }
00120         level_string = g_strdup(gncLogLevelasString(level));
00121         g_hash_table_foreach(log_table, log_module_foreach, level_string);
00122 }

void gnc_set_logfile (  FILE *  outfile  ) 
 

Specify an alternate log output, to pipe or file. By default, all logging goes to /tmp/qof.trace

Needs to be called before gnc_log_init()

Definition at line 125 of file gnc-trace.c.

00126 {
00127    if(!outfile) { fout = stderr; return; }
00128    fout = outfile;
00129 }

gboolean gnc_should_log (  QofLogModule  log_module,
gncLogLevel  log_level
) 
 

Do not log log_modules that have not been enabled.

Whether to log cannot be decided inline because a hashtable is now used. This is the price of extending logging to non-Gnucash log_modules.

Definition at line 299 of file gnc-trace.c.

00300 {
00301         gchar* log_string;
00302         gncLogLevel maximum; /* Any log_level less than this will be logged. */
00303 
00304         log_string = NULL;
00305         if(!log_table || log_module == NULL || log_level == 0) { return FALSE; }
00306         log_string = (gchar*)g_hash_table_lookup(log_table, log_module);
00307         /* if log_module not found, do not log. */
00308         if(!log_string) { return FALSE; }
00309         maximum = gncLogLevelfromString(log_string);
00310         if(log_level <= maximum) { return TRUE; }
00311         return FALSE;
00312 }

void gnc_start_clock (  int  clockno,
QofLogModule  log_module,
gncLogLevel  log_level,
const char *  function_name,
const char *  format,
  ...
) 
 

Infrastructure to make timing measurements for critical peices of code. Used for only for performance tuning & debugging.

Definition at line 201 of file gnc-trace.c.

00203 {
00204   struct timezone tz;
00205   va_list ap;
00206 
00207   if ((0>clockno) || (NUM_CLOCKS <= clockno)) return;
00208   gettimeofday (&gnc_clock[clockno], &tz);
00209 
00210   if (!fout) gnc_log_init();
00211 
00212   fprintf (fout, "Clock %d Start: %s: ",
00213            clockno, gnc_log_prettify (function_name));
00214 
00215   va_start (ap, format);
00216 
00217   vfprintf (fout, format, ap);
00218 
00219   va_end (ap);
00220 
00221   fprintf (fout, "\n");
00222   fflush (fout);
00223 }

void qof_log_init_filename (  const gchar *  logfilename  ) 
 

Specify a filename for log output.

Calls gnc_log_init() for you.

Definition at line 132 of file gnc-trace.c.

00133 {
00134         if(!logfilename)
00135         {
00136                 fout = stderr;
00137         }
00138         else
00139         {
00140                 filename = g_strdup(logfilename);
00141                 fout = fopen(filename, "w");
00142         }
00143         gnc_log_init();
00144 }

gint qof_log_module_count (  void   ) 
 

Number of log_modules registered

Definition at line 351 of file gnc-trace.c.

00352 {
00353         if(!log_table) { return 0; }
00354         return g_hash_table_size(log_table);
00355 }

void qof_log_module_foreach (  QofLogCB  cb,
gpointer  data
) 
 

Iterate over each known log_module

Only log_modules with log_levels set will be available.

Definition at line 341 of file gnc-trace.c.

00342 {
00343         struct hash_s iter;
00344 
00345         if(!cb) { return; }
00346         iter.cb = cb;
00347         iter.data = data;
00348         g_hash_table_foreach(log_table, hash_cb, (gpointer)&iter);
00349 }

void qof_log_set_default (  gncLogLevel  log_level  ) 
 

Set the default QOF log_modules to the log level.

Definition at line 314 of file gnc-trace.c.

00315 {
00316         gnc_set_log_level(QOF_MOD_BACKEND, log_level);
00317         gnc_set_log_level(QOF_MOD_CLASS,   log_level);
00318         gnc_set_log_level(QOF_MOD_ENGINE,  log_level);
00319         gnc_set_log_level(QOF_MOD_OBJECT,  log_level);
00320         gnc_set_log_level(QOF_MOD_KVP,     log_level);
00321         gnc_set_log_level(QOF_MOD_MERGE,   log_level);
00322         gnc_set_log_level(QOF_MOD_QUERY,   log_level);
00323         gnc_set_log_level(QOF_MOD_SESSION, log_level);
00324 }

void qof_log_shutdown (  void   ) 
 

Be nice, close the logfile is possible.

Definition at line 147 of file gnc-trace.c.

00148 {
00149         if(fout && fout != stderr) { fclose(fout); }
00150         if(filename) { g_free(filename); }
00151         g_hash_table_destroy(log_table);
00152 }

Generated on Fri Oct 21 15:49:58 2005 for QOF by  doxygen 1.4.5