Logging data

The refdb programs can spill out quite a lot of log messages to keep track of what is happening in your programs. This section explains the basics of setting up your message logging.

What to log

The application server refdbd as well as all command-line clients can generate log messages. Message logging is most important for two purposes:

A useful approach is to log all messages with a log level (explained below) of 6. This would give you a good overview over the usage of these programs but would not clutter the log files with debug information. Switch to log level 7 only if you suspect a bug or some user error and need the full debug information to understand the problem.

For the interactive use of the clients logging is usually not necessary, so you'd use a log level of -1 to prevent logging altogether or a log level of maybe 3 or 4. In the latter case you'd get log messages only if something goes badly wrong. Again, if you encounter bugs or user errors you may switch on debug messages by using a log level of 7.

Destinations

There are three possible destinations the log messages can be sent to. Select the proper destination with either the logdest variable in the configuration file or the -e switch on the command line. In both cases the values in the following list are accepted. You may use either the numerical value or the case-insensitive string in brackets, e.g. -e 1 and -e syslog are equivalent.

0 (stderr)

stderr is mostly useful for debugging purposes when refdbd is run as a standalone process and when clients are run interactively. stderr does not make much sense if you run refdbd as a daemon (daemons detach from the console at startup, so all output to stderr is lost).

1 (syslog)

Sending the data to syslog integrates the log data with the rest of your system's log output. The log messages will be sent to the user facility, which usually is configured to write to /var/log/user.log. See the syslog(8) man page for information how to configure the syslog facility.

Note: If you run refdbd on Cygwin, the syslog messages are sent to the application message list in the NT message logging system. If you are used to going through your log output with tools like grep and awk, you may find it more useful to write to a custom log file instead.

2 (file)

You can define the full path of a custom log file with either the logfile configuration file parameter or the -L command line option. By default, refdb applications write their log output to /var/log/<appname>.log. Make sure to set the appropriate access rights for these log files.

Note: Some libraries used by refdb, e.g. the PostgreSQL client library, send log messages to stderr. This is not controlled by the log settings of refdbd. The same PostgreSQL log messages show up in the PostgreSQL log which is usually sent to /var/log/pgsql.

Log levels

You can select how verbose the log output of refdbd will be. You can do this by either setting the loglevel configuration file variable or the -l command line option to an appropriate value. You may either use the numerical value or the case-insensitive string as explained in the table below. E.g. -l 5 and -l notice are equivalent. Set the log level to -1 to disable logging completely. Use a value from 0 through 7 to generate increasingly verbose log output. The definitions of the log levels are taken from the include file syslog.h:

Table 4-1. Log level definitions

level verbose explanation
0 emerg system is unusable
1 alert action must be taken immediately
2 crit the system is in a critical condition
3 err there is an error condition
4 warning there is a warning condition
5 notice a normal but significant condition
6 info a purely informational message
7 debug messages generated to debug the application

Setting the log level to a given value means that all messages with a priority level up to the given value will be logged. E.g. if you set the log level to 6 (which is a reasonable default value), all messages with a priority from 0 through 6 will be logged, whereas messages with a priority level of 7 will be ignored.

Warning

Use log level 7 with caution. The amount of log messages is considerable and sufficient to slow down the application. You should not use this level in everyday use, only to track down bugs or user errors that you may encounter.

Interpreting the log information

If the messages are sent to stderr, only the message proper will be printed. If the messages are sent to the syslog facility, the default format including the process name and process ID is used.

A line in the custom log file looks like this:

6:pid=267:Sun Jul 22 18:39:52 2001:application server started

You will easily recognize the following fields:

message_priority:process_id:time:message
message priority

This is the priority assigned to the message by refdbd. The values are explained above.

process ID

This is the process ID (as seen in the ps ax listing) of the refdb process that generated the message. In the case of refdbd this may either be the parent process (the one that generated the above "application server started" message) or one of the children that are forked off to answer client requests.

time

This is the full time and date information when the message was generated.

message

This is the message text proper.

The message entries are sufficiently structured to allow easy access to the information with the standard Unix tools like awk and grep.