GLib Logging (Guile-GI)

2.8.2 GLib Logging

GLib provides a logging library whose behavior can be tailored using environment variables. GLib’s logging library has a concept of log levels: critical, error, warning, message, info, and debug.

The G_MESSAGES_DEBUG environment variable may be set to a space-separated list of log domains for which debug messages should be printed. Some useful log domains are GuileGI for Guile-GI messages, dconf, GLib, GLib-GIO, Gdk, and Gtk. Also, the special log domain all will print debug messages from all domains. For more information on how to take advantage of this logging, see https://developer.gnome.org/glib/stable/glib-running.html.

When G_MESSAGES_DEBUG is set to GuileGI or all, you will receive a lot of debugging information from any Guile-GI libraries being used. To help better filter through all this, a (gi logging) library provides a pair of alternative loggers.

Using the Port Logger
Using the systemd journal Logger
Using a custom logger

2.8.2.1 Using the Port Logger

The (gi logging) library provides the install-port-logger! procedure that sends logging output to a Scheme port and provides functionality to target specific categories of debug information

Procedure: install-port-logger! port ¶

Given port, an output port, this procedure installs a GLib log writer function that outputs to port.

The default behavior of this GLib log writer is to print critical, error, and warning messages to the port. This logger behaves like the default GLib logger – i.e. it respects G_MESSAGES_DEBUG – but in addition to that also reads GIG_DEBUG for more fine-grained control over the messages Guile-GI prints to the port.

Set the GIG_DEBUG environment variable to a list of topics separated by any delimiter or the specific value all.

amap prints information about the mapping of function arguments.
load prints information – when libraries are loaded – on how C procedures, structs, unions, and objects are bound to Guile.
transfers prints information on how C arguments are converted to Guile objects and vice versa.
all prints all the debug information.

If GIG_DEBUG is not set, only information about function calls will be output.

2.8.2.2 Using the systemd journal Logger

The (gi logging) library provides the install-journal-logger! procedure.

Procedure: install-journal-logger! ¶: This procedure sets GLib’s g_log_writer_journald function as the current GLib log writer function.

For distributions that use systemd’s journal, the journalctl command can help filter debug output. Guile-GI’s debug messages have the message key GIG_DOMAIN which can be used to filter debug info into general categories.

2.8.2.3 Using a custom logger

The (gi logging) library provides the install-custom-logger! procedure.

Procedure: install-custom-logger! logger ¶

This procedure installs a helper, which will call logger to do the actual logging, as the GLib log writer function.

For the call to logger, the GLogField structures used by GLib internally are translated to keyword arguments. For that, the keys are kebab-cased and the values either transformed into suitable scheme datatypes or left as-is and passed by pointer. In the latter case, another argument is added for the length of the field, which takes the same keyword as the first one, but with the suffix -length.

The currently supported conversions are:

#:message, the current message as a string,
#:priority, a string representation of the log level,
#:glib-domain, the log domain as a string,
#:gig-domain, the Guile-GI log domain as a string, and
#:code-file, #:code-func and #:code-line, the location from which the log call was made, each as strings.

The log level is passed as an integer under the keyword #:log-level. If you’ve loaded the GLib typelib before installing the logger, you can transform that into log level flags by using number->log-level.