Coding Guidelines/Debugging Functions

From The Open Source Backup Wiki (Amanda, MySQL Backup, BackupPC)

Jump to: navigation, search

Amanda uses glib's debug logging facility. The most common function for debugging is g_debug. Its first argument should not end in a newline, but should be translated if it contains any English text. Example:

if (fd < 0)
  g_debug(_("Could not open '%s': %s"), filename, strerror(errno));

In this example, the format string is not translated, since it does not contain any text worthy of translation:

g_debug("%s: %s", device->name, device->errmsg);

Using Debugging in Executables

When an executable starts, it needs to set up debugging. Early in its main, it should call set_pname to set the process name correctly, then call dbopen with an appropriate subdirectory name (typically one of the DBG_SUBDIR_* constants). If the executable runs in the context of a particular Amanda configuration, it should call

dbrename(config_name, DBG_SUBDIR_SERVER);

to move the debugging information into the relevant subdirectory.

When the executable finishes, it should call dbclose to flush and close any open debug files.

In Perl, this looks like

 use Amanda::Config qw( :init );
 use Amanda::Util qw( :constants );
 use Amanda::Debug;
 Amanda::Util::setup_application("myapp", "server", "cmdline");
 # .. command-line processing ..
 Amanda::Config::config_init(...);
 Amanda::Util::finish_setup($RUNNING_AS_DUMPUSER);

see Amanda::Util for more information.

More Severe

Currently, Amanda does not distinguish any logging levels except critical and error, so a g_warning is equivalent to a g_debug. However, at some point such a distinction may be added (for example, forwarding warnings to syslog), so it makes sense to use a level appropriate to the message.

Conditional Debugging

Some parts of Amanda produce such verbose output that they are individually controlled by debug_* directives in amanda.conf(5). In general, this is handled with a macro such as

#define auth_debug(i, ...) do {         \
        if ((i) <= debug_auth) {        \
            g_debug(__VA_ARGS__);      \
        }                               \
} while (0)

where conffile.c has been modified to set the relevant debug variable (debug_auth in this case).

Debugging Other Applications

Amanda often runs other applications (dumpers, security utilities, and so on), and it is often necessary to redirect the stderr of those applications to the debug log. 'dbfd' returns the file descriptor for the debug file, which can be manipulated as necesary (e.g., with dup2) to connect it to an external application.

Personal tools