Difference between revisions of "Logging"

From GnuCash
Jump to: navigation, search
(Add sections on command line configuration of logging)
(use {{URL:docs:API}})
 
(16 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
For users: See [[Tracefile]] and [[Stack Trace]] on how to look up the logging information after some problem occurred.
+
;Users: See [[Tracefile]] and [[Stack Trace]] on how to look up the logging information after some problem occurred.
−
 
+
;Developers: See the [{{URL:docs:API}}group__Logging.html Logging API documentation], as well. So each module defines its own log_domain. Best way to figure out what to use is to look at the top of the .c file and look for the LOG_MODULE. E.g. <tt>print-session.c</tt> defines <tt>G_LOG_DOMAIN "gnc.printing"</tt>.
−
For developers: See the [http://code.gnucash.org/docs/MAINT/group__Logging.html Logging API documentation], as well. So each module defines its own log_domain. Best way to figure out what to use is to look at the top of the .c file and look for the LOG_MODULE. E.g. <tt>print-session.c</tt> defines <tt>G_LOG_DOMAIN "gnc.printing"</tt>.
+
[[Category:Log]]
−
 
 
−
The rest of this page is targeted towards developers.
 
−
 
 
 
= Logging in GnuCash =
 
= Logging in GnuCash =
 +
GnuCash leverages glib logging, with some historical and convenience macros.  Since 2007 GnuCash has used an ad-hoc layer on top of glib's "gmessage.h" logging inspired by log4j.  In short, '''messages''' are logged in a given [[GnuCash Log Domains |log-domains]] and at a specific [[GnuCash Log-levels |log-level]].  The log-domain is a "."-separated path, and a table of log levels is configured.  Between the two, a tree of log-level is established.  Log messages are checked against the tree before being emitted.
  
−
GnuCash leverages glib logging, with some historical and convenience macros.  Since 2007 GnuCash has used an ad-hoc layer on top of glib's "gmessage.h" logging inspired by log4j.  In short, '''messages''' are logged in a given [[GnuCash Log Domains |'''log-domains''']] and at a specific [[GnuCash Log-levels |'''log-level''']].  The log-domain is a "."-separated path, and a table of log levels is configured.  Between the two, a tree of log-level is established.  Log messages are checked against the tree before being emitted.
+
== Configuring Logging ==
 +
Logging may be configured by using either using the [[#With log.conf | log.conf]] file or by specifying [[#Command Line Options |command line options]] when starting GnuCash from a terminal/shell.  
  
 +
=== With log.conf ===
 +
The special file
 +
:;since GnuCash 3.0: <tt>[[Configuration Locations#GNC_CONFIG_HOME|GNC_CONFIG_HOME]]/log.conf</tt>
 +
:;Up to GnuCash 2.6.x: <tt>[[Configuration Locations#DOT_GNUCASH_DIR|DOT_GNUCASH_DIR]]/log.conf</tt>
 +
is checked for at gnucash start up; if present, its contents will configure the logging subsystem. The primary purpose of the configuration file it to setup a specific set of log-levels, though it's also useful for changing the default logging location from <tt>/tmp/gnucash.trace</tt> to stdout, stderr or another file.
  
 +
The specific set of log paths that exist are going to be a function of the code at any given point, but some basic patterns will stabilize. As of Feb 13 2007, [[User:Jsled]] is using the following entries in log.conf to generally raise the log level of the app, but also to get debugging detail about file-backend and UI code changes related to scheduled transactions:
 +
<syntaxhighlight lang="ini">
 +
[levels]
 +
gnc=message
  
−
The special file <tt>[[Configuration Locations#GNC_CONFIG_HOME|GNC_CONFIG_HOME]]/log.conf</tt> (for GnuCash 3.x and up) or <tt>[[Configuration Locations#DOT_GNUCASH_DIR|DOT_GNUCASH_DIR]]/log.conf</tt> (for GnuCash 2.6.x and older) is checked for at gnucash start up; if present, its contents will configure the logging subsystem.   The primary purpose of the configuration file it to setup a specific set of log-levels, though it's also useful for changing the default logging location from <tt>/tmp/gnucash.trace</tt> to stdout, stderr or another file.
+
gnc.bin=info
 +
gnc.gui=info
 +
gnc.backend.file=info
  
−
The specific set of log paths that exist are going to be a function of the code at any given point, but some basic patterns will stabilize. As of Feb 13 2007, [[User:Jsled]] is using the following to generally raise the log level of the app, but also to get debugging detail about file-backend and U I code changes related to scheduled transactions:
+
gnc.engine.sx=debug
−
<syntaxhighlight>
+
gnc.app-util.sx=debug
−
    [levels]
+
gnc.backend.file.sx=debug
−
    gnc=message
+
gnc.gui.sx=debug
 +
gnc.gui.frequency=debug
 
      
 
      
−
    gnc.bin=info
+
GLib=error
−
    gnc.gui=info
 
−
    gnc.backend.file=info
 
 
      
 
      
−
    gnc.engine.sx=debug
+
[output]
−
    gnc.app-util.sx=debug
+
to=stderr
−
    gnc.backend.file.sx=debug
 
−
    gnc.gui.sx=debug
 
−
    gnc.gui.frequency=debug
 
−
   
 
−
    GLib=error
 
−
   
 
−
    [output]
 
−
    to=stderr
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
;Note:
 +
:* These settings are probably not suitable for your purpose, but serve as an example of what's possible.
 +
:* Configuring using log.conf will change logging behavior for all versions of gnucash run by you as a user. This may not be convenient if you use a stable production version for accounting and work on a development version as the same user on the same computer
 +
 +
=== Command Line Options ===
 +
The full list of command options can be obtained by starting a shell and entering the appropriate <tt>gnucash --help</tt> command for your operating system according to the following sections (provided that the GnuCash bin folder is in <tt>PATH</tt> or the current folder of the shell):
 +
;Windows:
 +
Microsoft Windows Graphical programs can't ordinarily deliver text output to a shell window so gnucash --help is of little use. As of GnuCash 4.5 the output is:
 +
<pre>
 +
bin/gnucash [options] [datafile] - GnuCash, accounting for personal and small business finance:
 +
 +
Common Options:
 +
  -h [ --help ]          Show this help message
 +
  -v [ --version ]        Show GnuCash version
 +
  --debug                Enable debugging mode: provide deep detail in the
 +
                          logs.
 +
                          This is equivalent to: --log "=info" --log "qof=info"
 +
                          --log "gnc=info"
 +
  --extra                Enable extra/development/debugging features.
 +
  --log arg              Log level overrides, of the form
 +
                          "modulename={debug,info,warn,crit,error}"
 +
                          Examples: "--log qof=debug" or "--log
 +
                          gnc.backend.file.sx=info"
 +
                          This can be invoked multiple times.
 +
  --logto arg            File to log into; defaults to "/tmp/gnucash.trace";
 +
                          can be "stderr" or "stdout".
 +
  --gsettings-prefix arg  Set the prefix for gsettings schemas for gsettings
 +
                          queries. This can be useful to have a different
 +
                          settings tree while debugging.
 +
 +
Application Options:
 +
  --nofile                Do not load the last file opened
 +
  --help-gtk              Show help for gtk options
 +
 +
Deprecated Options:
 +
  --add-price-quotes      Add price quotes to given GnuCash datafile.
 +
                          Note this option has been deprecated and will be
 +
                          removed in GnuCash 5.0.
 +
                          Please use 'gnucash-cli --quotes get <datafile>'
 +
                          instead.
 +
  --namespace arg        Regular expression determining which namespace
 +
                          commodities will be retrieved.
 +
                          Note this option has been deprecated and will be
 +
                          removed in GnuCash 5.0.
 +
                          Please use 'gnucash-cli --quotes get --namespace
 +
                          <namespace> <datafile>' instead.
 +
</pre>
 +
;Gnucash.app on {{mac}}
 +
Gnucash.app is really a directory tree with a special layout; its executable isn't on the path. To start it from the command line you write
 +
<syntaxhighlight lang="sh">/Applications/Gnucash.app/Contents/MacOS/Gnucash</syntaxhighlight>
 +
if you'd installed it in the main Applications folder so to see the command line options you'd use
 +
<syntaxhighlight lang="sh">/Applications/Gnucash.app/Contents/MacOS/Gnucash --help</syntaxhighlight>
 +
If you installed GnuCash in a different folder you'll have to adjust the path.
 +
;Other platforms: <syntaxhighlight lang="sh">gnucash --help</syntaxhighlight>
 +
The specific options which may be used from the command line to configure general logging in GnuCash are:
 +
{| class="wikitable" style="text-align: left;"
 +
|-
 +
!Option
 +
!Description
 +
|-
 +
| --logto=<filespecifier> || File to log into;
 +
;defaults:
 +
:;Linux etc.:
 +
::<tt>/tmp/gnucash.trace</tt>
 +
:;Microsoft Windows:
 +
::<tt>%LOCALAPPDATA%\Temp\gnucash.trace.''XXXXXX''.log</tt>
 +
::where ''XXXXXX'' is replaced by random characters.
 +
:;{{mac}}
 +
::<tt>$TMPDIR/gnucash.trace</tt>
 +
Use <tt>stderr</tt> or <tt>stdout</tt> to write to the terminal or enter a path to any file. E.g a logging file in the user directory which doesn't require administrator privileges to access
 +
|-
 +
|style="width: 20em;"| --log "<log-domain>=<log-level>" || Overrides the default log-level settings or settings specified in log.conf. <log-domain> is of the form of a "." separated path. <log-level> is one of debug,info, warn, crit or error. Examples: "--log qof=debug" or "--log gnc.backend.file.sx=info"
 +
|-
 +
| --debug || Enable debugging mode: provide deep detail in the logs. This is equivalent to: --log "=info" --log "qof=info" --log "gnc=info".
 +
|-
 +
| --extra || Enable extra/development/debugging features.
 +
|-
 +
| --gsettings-prefix=GSETTINGSPREFIX || Set the prefix for gsettings schemas for gsettings queries. This can be useful to have a different settings tree while debugging.
 +
|-
 +
|}
  
−
Note that these settings are probably not suitable for your purpose, but serve as an example of what's possible.
+
GTK+ options ( $gnucash --help-gtk) allow setting debugging options for GTK+.
 +
See also [{{URL:docs:API}}group__Logging.html API group Logging].

Latest revision as of 23:35, 24 October 2023

Users
See Tracefile and Stack Trace on how to look up the logging information after some problem occurred.
Developers
See the Logging API documentation, as well. So each module defines its own log_domain. Best way to figure out what to use is to look at the top of the .c file and look for the LOG_MODULE. E.g. print-session.c defines G_LOG_DOMAIN "gnc.printing".

Logging in GnuCash

GnuCash leverages glib logging, with some historical and convenience macros. Since 2007 GnuCash has used an ad-hoc layer on top of glib's "gmessage.h" logging inspired by log4j. In short, messages are logged in a given log-domains and at a specific log-level. The log-domain is a "."-separated path, and a table of log levels is configured. Between the two, a tree of log-level is established. Log messages are checked against the tree before being emitted.

Configuring Logging

Logging may be configured by using either using the log.conf file or by specifying command line options when starting GnuCash from a terminal/shell.

With log.conf

The special file

since GnuCash 3.0
GNC_CONFIG_HOME/log.conf
Up to GnuCash 2.6.x
DOT_GNUCASH_DIR/log.conf

is checked for at gnucash start up; if present, its contents will configure the logging subsystem. The primary purpose of the configuration file it to setup a specific set of log-levels, though it's also useful for changing the default logging location from /tmp/gnucash.trace to stdout, stderr or another file.

The specific set of log paths that exist are going to be a function of the code at any given point, but some basic patterns will stabilize. As of Feb 13 2007, User:Jsled is using the following entries in log.conf to generally raise the log level of the app, but also to get debugging detail about file-backend and UI code changes related to scheduled transactions: 

[levels]
gnc=message

gnc.bin=info
gnc.gui=info
gnc.backend.file=info

gnc.engine.sx=debug
gnc.app-util.sx=debug
gnc.backend.file.sx=debug
gnc.gui.sx=debug
gnc.gui.frequency=debug
    
GLib=error
    
[output]
to=stderr
Note
  • These settings are probably not suitable for your purpose, but serve as an example of what's possible.
  • Configuring using log.conf will change logging behavior for all versions of gnucash run by you as a user. This may not be convenient if you use a stable production version for accounting and work on a development version as the same user on the same computer

Command Line Options

The full list of command options can be obtained by starting a shell and entering the appropriate gnucash --help command for your operating system according to the following sections (provided that the GnuCash bin folder is in PATH or the current folder of the shell):

Windows

Microsoft Windows Graphical programs can't ordinarily deliver text output to a shell window so gnucash --help is of little use. As of GnuCash 4.5 the output is: 

bin/gnucash [options] [datafile] - GnuCash, accounting for personal and small business finance:

Common Options:
  -h [ --help ]           Show this help message
  -v [ --version ]        Show GnuCash version
  --debug                 Enable debugging mode: provide deep detail in the
                          logs.
                          This is equivalent to: --log "=info" --log "qof=info"
                          --log "gnc=info"
  --extra                 Enable extra/development/debugging features.
  --log arg               Log level overrides, of the form
                          "modulename={debug,info,warn,crit,error}"
                          Examples: "--log qof=debug" or "--log
                          gnc.backend.file.sx=info"
                          This can be invoked multiple times.
  --logto arg             File to log into; defaults to "/tmp/gnucash.trace";
                          can be "stderr" or "stdout".
  --gsettings-prefix arg  Set the prefix for gsettings schemas for gsettings
                          queries. This can be useful to have a different
                          settings tree while debugging.

Application Options:
  --nofile                Do not load the last file opened
  --help-gtk              Show help for gtk options

Deprecated Options:
  --add-price-quotes      Add price quotes to given GnuCash datafile.
                          Note this option has been deprecated and will be
                          removed in GnuCash 5.0.
                          Please use 'gnucash-cli --quotes get <datafile>'
                          instead.
  --namespace arg         Regular expression determining which namespace
                          commodities will be retrieved.
                          Note this option has been deprecated and will be
                          removed in GnuCash 5.0.
                          Please use 'gnucash-cli --quotes get --namespace
                          <namespace> <datafile>' instead.
Gnucash.app on macOS

Gnucash.app is really a directory tree with a special layout; its executable isn't on the path. To start it from the command line you write 

/Applications/Gnucash.app/Contents/MacOS/Gnucash

if you'd installed it in the main Applications folder so to see the command line options you'd use 

/Applications/Gnucash.app/Contents/MacOS/Gnucash --help

If you installed GnuCash in a different folder you'll have to adjust the path.

Other platforms
gnucash --help

The specific options which may be used from the command line to configure general logging in GnuCash are:

Option Description
--logto=<filespecifier> File to log into;
defaults
Linux etc.
/tmp/gnucash.trace
Microsoft Windows
%LOCALAPPDATA%\Temp\gnucash.trace.XXXXXX.log
where XXXXXX is replaced by random characters.
macOS
$TMPDIR/gnucash.trace

Use stderr or stdout to write to the terminal or enter a path to any file. E.g a logging file in the user directory which doesn't require administrator privileges to access

--log "<log-domain>=<log-level>" Overrides the default log-level settings or settings specified in log.conf. <log-domain> is of the form of a "." separated path. <log-level> is one of debug,info, warn, crit or error. Examples: "--log qof=debug" or "--log gnc.backend.file.sx=info"
--debug Enable debugging mode: provide deep detail in the logs. This is equivalent to: --log "=info" --log "qof=info" --log "gnc=info".
--extra Enable extra/development/debugging features.
--gsettings-prefix=GSETTINGSPREFIX Set the prefix for gsettings schemas for gsettings queries. This can be useful to have a different settings tree while debugging. 
GTK+ options ( $gnucash --help-gtk) allow setting debugging options for GTK+.

See also API group Logging.

Retrieved from "https://code.gnucash.org/wiki/index.php?title=Logging&oldid=21930"